WAYFARER PROJECT REVIEW
=======================

Generated: 2026-09-29 21:57:58
Files: 75

FILE MANIFEST
-------------
admin/builder-refactored.php
admin/builder.php
admin/games/edit.php
admin/games/index.php
assets/css/admin.css
assets/css/builder.css
assets/css/hierarchical-targets.css
assets/css/status-subject-effects.css
assets/js/builder.js
assets/js/game-endings.js
assets/js/game-travel.js
assets/js/hierarchical-targets.js
assets/js/starting-choices.js
assets/js/status-lifecycle.js
assets/js/status-subject-effects.js
assets/js/target-search.js
assets/js/trait-display.js
assets/js/traits.js
config/builder-types.php
includes/builder/collection-table.php
includes/builder/collection.php
includes/builder/config-field.php
includes/builder/editor.php
includes/builder/field.php
includes/builder/functions.php
includes/builder/load-record.php
includes/builder/location-tick-effects.php
includes/builder/navigation.php
includes/builder/region-hud.php
includes/builder/region-travel.php
includes/builder/relationship-field.php
includes/builder/save-record.php
includes/builder/status-lifecycle.php
includes/builder/storylet-gameplay.php
includes/builder/tick-effects.php
includes/gameplay/condition-editor.php
includes/gameplay/conditions.php
includes/gameplay/effects-editor.php
includes/gameplay/functions.php
includes/gameplay/game-endings.php
includes/gameplay/starting-choices.php
includes/gameplay/status-lifecycle.php
includes/gameplay/storylet-bindings.php
includes/gameplay/tick-effects-editor.php
includes/gameplay/travel-modifiers.php
includes/header.php
includes/traits/editor.php
includes/traits/functions.php
includes/traits/render.php
play/api/presentation.php
play/api/restart.php
play/api/storylet.php
play/api/tick.php
play/assets/play.css
play/assets/play.js
play/includes/action-screen.php
play/includes/applicable-traits.v15-disabled.php
play/includes/author-mode.php
play/includes/current-region.php
play/includes/effects.php
play/includes/ending-screen.php
play/includes/entity-state.php
play/includes/hud.php
play/includes/player-state.php
play/includes/presentation-screen.php
play/includes/runtime-bootstrap.php
play/includes/runtime.php
play/includes/scene.php
play/includes/setup.php
play/includes/start-screen.php
play/includes/statuses.php
play/includes/storylet-bindings.php
play/includes/storylets.php
play/includes/tick-panel.php
play/index.php




==============================================================================
FILE: admin/builder-refactored.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Wayfarer Builder Compatibility Redirect
|--------------------------------------------------------------------------
|
| builder-refactored.php was the temporary entry point while the
| componentized builder was being proven. builder.php is now canonical.
|
*/

$queryString =
    $_SERVER['QUERY_STRING']
    ?? '';

$location =
    'builder.php';

if ($queryString !== '') {
    $location .=
        '?' .
        $queryString;
}

header(
    'Location: ' .
    $location
);

exit;


==============================================================================
FILE: admin/builder.php
==============================================================================

<?php
/* WAYFARER_TICK_EFFECT_BRANCHES_V28 */
/*
 * WAYFARER_PRESERVE_ACTIVE_TAB_V20
 * Successful saves reopen the previously selected builder tab.
 */

/*
 * WAYFARER_STAY_ON_SAVED_RECORD_V19
 * Successful saves redirect back to the saved authored object.
 */


ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

require_once __DIR__ . '/../config/database.php';
require_once __DIR__ . '/../config/builder-types.php';
require_once __DIR__ . '/../includes/traits/functions.php';

require_once __DIR__ . '/../includes/builder/functions.php';
require_once __DIR__ . '/../includes/builder/load-record.php';
require_once __DIR__ . '/../includes/builder/save-record.php';
require_once __DIR__ . '/../includes/builder/collection.php';


// ================================================================
// REQUEST
// ================================================================

$gameId = isset($_GET['game']) ? (int)$_GET['game'] : 0;
$type   = $_GET['type'] ?? 'regions';
$id     = isset($_GET['id']) ? (int)$_GET['id'] : 0;

$builderPage = basename($_SERVER['PHP_SELF']);

if (!$gameId) {
    die('Game ID is required.');
}


// ================================================================
// LOAD GAME
// ================================================================

/* WAYFARER_BUILDER_LOAD_GAME_CONFIG_V27_2 */
$stmt = $pdo->prepare("
    SELECT id, name, config
    FROM wf_games
    WHERE id = ?
");

$stmt->execute([$gameId]);
$game = $stmt->fetch();

if (!$game) {
    die('Game not found.');
}


// ================================================================
// LOAD BUILDER DEFINITION
// ================================================================

if (!isset($builderTypes[$type])) {
    die('Unknown builder type.');
}

$definition    = $builderTypes[$type];
$table         = $definition['table'];
$listField     = $definition['list_field'];
$listColumns   = $definition['list_columns'] ?? [];
$fields        = $definition['fields'] ?? [];
$relationships = $definition['relationships'] ?? [];
$configFields  = $definition['config_fields'] ?? [];
$scope         = $definition['scope'];


// ================================================================
// LOAD EDITOR RECORD
// ================================================================

$editorState = loadBuilderRecord(
    $pdo,
    $definition,
    $gameId,
    $id
);

$record       = $editorState['record'];
$configValues = $editorState['configValues'];
$traits       = $editorState['traits'];
$error        = '';


/* WAYFARER_STORYLET_BUILDER_V56
 * A + New Branch Storylet link can preselect its parent and choose a sensible
 * sibling order without making parent_storylet_id part of the generic request.
 */
if (
    $type === 'storylets' &&
    !$id &&
    !empty($_GET['parent_storylet_id'])
) {
    $requestedParentId =
        (int)$_GET['parent_storylet_id'];

    $parentStmt = $pdo->prepare(
        "
        SELECT id
        FROM wf_storylets
        WHERE id = ?
          AND game_id = ?
        LIMIT 1
        "
    );

    $parentStmt->execute([
        $requestedParentId,
        $gameId,
    ]);

    if ($parentStmt->fetchColumn()) {
        $record['parent_storylet_id'] =
            $requestedParentId;

        $orderStmt = $pdo->prepare(
            "
            SELECT COALESCE(MAX(branch_sort_order), 0)
            FROM wf_storylets
            WHERE game_id = ?
              AND parent_storylet_id = ?
            "
        );

        $orderStmt->execute([
            $gameId,
            $requestedParentId,
        ]);

        $record['branch_sort_order'] =
            (int)$orderStmt->fetchColumn() + 10;
    }
}

// ================================================================
// SAVE / DELETE / DUPLICATE
// WAYFARER_STORYLET_DUPLICATE_V83
// ================================================================

if ($_SERVER['REQUEST_METHOD'] === 'POST') {

    /*
     * WAYFARER DELETE ACTION
     *
     * Save remains the default action so existing save forms do not need
     * an additional hidden field.
     */
    $postAction =
        $_POST['action'] ?? 'save';

    if ($postAction === 'duplicate') {

        $duplicateId =
            !empty($_POST['id'])
                ? (int)$_POST['id']
                : 0;

        if (
            ($definition['table'] ?? '') !==
            'wf_storylets'
        ) {
            $error =
                'Only Storylets can be duplicated.';
        } else {
            $duplicateResult =
                duplicateStoryletRecord(
                    $pdo,
                    $gameId,
                    $duplicateId
                );

            $error =
                $duplicateResult['error'];

            if ($duplicateResult['duplicated']) {
                header(
                    'Location: ' .
                    $builderPage .
                    '?game=' . $gameId .
                    '&type=' . urlencode($type) .
                    '&id=' . (int)$duplicateResult['id'] .
                    '&tab=basics' .
                    '&duplicated=1'
                );

                exit;
            }
        }

    } elseif ($postAction === 'delete') {

        $deleteId =
            !empty($_POST['id'])
                ? (int)$_POST['id']
                : 0;

        $deleteResult =
            deleteBuilderRecord(
                $pdo,
                $definition,
                $gameId,
                $deleteId
            );

        $error =
            $deleteResult['error'];

        if ($deleteResult['deleted']) {
            header(
                'Location: ' .
                $builderPage .
                '?game=' . $gameId .
                '&type=' . urlencode($type)
            );

            exit;
        }

    } else {

        $saveResult = saveBuilderRecord(
            $pdo,
            $definition,
            $gameId,
            $_POST,
            $record,
            $configValues,
            $traits
        );

        $record       = $saveResult['record'];
        $configValues = $saveResult['configValues'];
        $traits       = $saveResult['traits'];
        $error        = $saveResult['error'];

        if ($saveResult['saved']) {

            /*
             * Media Library associations are applied only after the authored
             * object has saved successfully and therefore has a stable ID.
             */
            $savedRecordId =
                (int)$saveResult['id'];

            $mediaResult =
                applyBuilderMediaSelections(
                    $pdo,
                    $gameId,
                    $definition['table'],
                    $savedRecordId,
                    $_POST,
                    $_FILES
                );

            if (!$mediaResult['saved']) {

                /*
                 * The authored object itself has already saved. Keep the
                 * editor on that record and report the media failure
                 * accurately rather than pretending the object save failed.
                 */
                $id =
                    $savedRecordId;

                $record['id'] =
                    $savedRecordId;

                $error =
                    'Record saved, but media was not changed: ' .
                    $mediaResult['error'];

            } else {

                header(
                    'Location: ' .
                    $builderPage .
                    '?game=' . $gameId .
                    '&type=' . urlencode($type) .
                    '&id=' . (int)$saveResult['id'] .
                    '&tab=' . rawurlencode(
                        (string)($_POST['active_tab'] ?? 'basics')
                    )
                );

                exit;
            }
        }
    }
}

// ================================================================
// LOAD COLLECTION + UI SUPPORT DATA
// ================================================================

$collectionState = loadBuilderCollection(
    $pdo,
    $definition,
    $gameId
);

$records             = $collectionState['records'];
$relationshipOptions = $collectionState['relationshipOptions'];
$conditionData       = $collectionState['conditionData'];

?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title><?= builderEscape($game['name']) ?> - Wayfarer Builder</title>
    <!-- WAYFARER_GENERIC_CONDITION_INIT_CACHE_V45_2 -->
<link rel="stylesheet" href="../assets/css/builder.css?v=58">
<!-- WAYFARER_STATUS_SUBJECT_EFFECTS_UI_V89 -->
<link rel="stylesheet" href="../assets/css/status-subject-effects.css?v=89">
</head>
<body class="wayfarer-builder-page">

<h1><?= builderEscape($game['name']) ?></h1>
<p>Wayfarer Builder</p>

<?php require __DIR__ . '/../includes/builder/navigation.php'; ?>

<div
    class="builder-workspace"
    data-builder-workspace
>
    <aside class="builder-collection-pane">

        <div class="builder-collection-toolbar">
            <a
                class="builder-new-object"
                href="<?= builderEscape($builderPage) ?>?game=<?= $gameId ?>&amp;type=<?= urlencode($type) ?>"
            >
                + New <?= builderEscape($definition['singular']) ?>
            </a>
        </div>

        <div class="builder-collection-scroll">
            <?php require __DIR__ . '/../includes/builder/collection-table.php'; ?>
        </div>

    </aside>

    <main
        class="builder-editor-pane"
        data-builder-editor
    >
        <?php require __DIR__ . '/../includes/builder/editor.php'; ?>
    </main>
</div>

<p class="builder-back-link">
    <a href="games/index.php">&larr; Games</a>
</p>

<script>
window.wayfarerConditionData = <?= json_encode(
    $conditionData,
    JSON_UNESCAPED_SLASHES |
    JSON_UNESCAPED_UNICODE
) ?>;
</script>
<!-- WAYFARER_BUILDER_JS_CACHE_V25_2 -->
<script src="../assets/js/builder.js?v=58"></script>


<script>
/* WAYFARER_CONFIRM_TRAIT_REMOVAL_V21_1 */
(function () {

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


    function findTraitContainer(button) {

        let node =
            button.parentElement;

        while (
            node &&
            node !== document.body
        ) {

            if (
                node.querySelector &&
                node.querySelector(
                    'input[name^="traits["], ' +
                    'select[name^="traits["], ' +
                    'textarea[name^="traits["]'
                )
            ) {
                return node;
            }

            /*
             * Stop before accidentally climbing into the entire form.
             */
            if (
                node.tagName === 'FORM'
            ) {
                break;
            }

            node =
                node.parentElement;
        }

        return null;
    }


    function getTraitName(container) {

        if (!container) {
            return '';
        }

        const nameInput =
            container.querySelector(
                'input[name^="traits["][name$="[name]"], ' +
                'input[name*="[name]"]'
            );

        if (!nameInput) {
            return '';
        }

        return String(
            nameInput.value || ''
        ).trim();
    }


    document.addEventListener(
        'click',
        function (event) {

            const button =
                event.target.closest(
                    'button, input[type="button"], input[type="submit"]'
                );

            if (!button) {
                return;
            }

            const buttonText =
                normalizeText(
                    button.tagName === 'INPUT'
                        ? button.value
                        : button.textContent
                );

            const explicitRemoveTrait =
                buttonText === 'remove trait';

            const traitContainer =
                findTraitContainer(
                    button
                );

            /*
             * A generic "Remove" button counts only when it is inside a
             * container with traits[...] form controls. This avoids touching
             * Tick Effects, media controls, or object deletion.
             */
            const contextualTraitRemove =
                traitContainer !== null &&
                (
                    buttonText === 'remove' ||
                    buttonText === 'remove trait'
                );

            if (
                !explicitRemoveTrait &&
                !contextualTraitRemove
            ) {
                return;
            }

            const traitName =
                getTraitName(
                    traitContainer
                );

            const message =
                traitName !== ''
                    ? 'Are you sure you want to remove the trait "' +
                        traitName +
                        '"?'
                    : 'Are you sure you want to remove this trait?';

            if (
                !window.confirm(
                    message
                )
            ) {

                event.preventDefault();
                event.stopPropagation();
                event.stopImmediatePropagation();
            }
        },
        true
    );

})();
</script>

<script>
/* WAYFARER_CONFIRM_TICK_EFFECT_REMOVAL_V21_3 */
(function () {

    function normalizeText(value) {

        return String(
            value || ''
        )
            .replace(/\s+/g, ' ')
            .trim();
    }


    function findAction(event) {

        let node =
            event.target;

        while (
            node &&
            node !== document.body
        ) {

            if (
                node.matches &&
                node.matches(
                    'button, a, [role="button"], [onclick], ' +
                    'input[type="button"], input[type="submit"]'
                )
            ) {
                return node;
            }

            node =
                node.parentElement;
        }

        return null;
    }


    function actionLabel(action) {

        if (!action) {
            return '';
        }

        return normalizeText(
            action.tagName === 'INPUT'
                ? action.value
                : (
                    action.getAttribute('aria-label') ||
                    action.getAttribute('title') ||
                    action.textContent ||
                    ''
                )
        );
    }


    function selectedText(select) {

        if (!select) {
            return '';
        }

        const option =
            select.options[
                select.selectedIndex
            ];

        return option
            ? normalizeText(
                option.textContent
            )
            : '';
    }


    document.addEventListener(
        'click',
        function (event) {

            const panel =
                event.target.closest(
                    '[data-builder-panel="tick_effects"], ' +
                    '[data-builder-tick-effects]'
                );

            if (!panel) {
                return;
            }

            const action =
                findAction(
                    event
                );

            if (!action) {
                return;
            }

            const label =
                actionLabel(
                    action
                );

            const explicitRemove =
                action.matches(
                    '[data-remove-tick-effect]'
                );

            const textRemove =
                /\b(remove|delete)\b/i.test(
                    label
                );

            if (
                !explicitRemove &&
                !textRemove
            ) {
                return;
            }

            const row =
                action.closest(
                    '[data-tick-effect-row], ' +
                    '.builder-tick-effect-row'
                );

            let detail =
                '';

            if (row) {

                const target =
                    selectedText(
                        row.querySelector(
                            '[data-tick-effect-target], ' +
                            'select[name*="[target]"]'
                        )
                    );

                const operation =
                    selectedText(
                        row.querySelector(
                            'select[name*="[operation]"]'
                        )
                    );

                const valueInput =
                    row.querySelector(
                        'input[name*="[value]"]'
                    );

                const value =
                    valueInput
                        ? normalizeText(
                            valueInput.value
                        )
                        : '';

                const parts = [];

                if (target) {
                    parts.push(
                        target
                    );
                }

                if (operation) {
                    parts.push(
                        operation
                    );
                }

                if (value) {
                    parts.push(
                        value
                    );
                }

                if (parts.length) {

                    detail =
                        '\n\n' +
                        parts.join(
                            ' — '
                        );
                }
            }

            const confirmed =
                window.confirm(
                    'Are you sure you want to remove this Tick Effect?' +
                    detail
                );

            if (!confirmed) {

                event.preventDefault();
                event.stopPropagation();
                event.stopImmediatePropagation();

                return false;
            }
        },
        true
    );

})();
</script>

<!-- WAYFARER_STATUS_LIFECYCLE_UI_V88 -->
<script src="../assets/js/status-lifecycle.js?v=88"></script>
<!-- WAYFARER_STATUS_SUBJECT_EFFECTS_UI_V89 -->
<script src="../assets/js/status-subject-effects.js?v=89"></script>
<!-- WAYFARER_HIERARCHICAL_TARGETS_V80 -->
<script src="/wayfarer/assets/js/hierarchical-targets.js?v=85"></script>
</body>
</html>



==============================================================================
FILE: admin/games/edit.php
==============================================================================

<?php

ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

require_once __DIR__ . '/../../config/database.php';
require_once __DIR__ . '/../../includes/traits/functions.php';
require_once __DIR__ . '/../../includes/builder/functions.php';
require_once __DIR__ . '/../../includes/gameplay/functions.php';
require_once __DIR__ . '/../../includes/gameplay/starting-choices.php';
require_once __DIR__ . '/../../includes/gameplay/game-endings.php';
require_once __DIR__ . '/../../includes/gameplay/travel-modifiers.php';
/* WAYFARER_GAME_TRAVEL_MODIFIERS_V73 */
/* WAYFARER_GAME_ENDINGS_V45 */

/* WAYFARER_GAME_SETUP_AND_GAMEPLAY_V33 */
/* WAYFARER_STARTING_CHOICES_V36 */

$game = [
    'id' => null,
    'name' => '',
    'slug' => '',
    'description' => '',
    'instructions' => '',
    'player_slots' => 0,
    'config' => null,
    'status' => 'draft'
];

$traits = [];
$playerTraits = [];
$config = [];
/* WAYFARER_PLAYER_TRAIT_DEFINITIONS_V52 */
$gameTickEffects = [];
$gameplayTickEffects = [];
$startingChoices = [];
$startingChoicesEditor = [];
$startingChoiceItemTargets = [];
/* WAYFARER_STARTING_CHOICE_ITEM_QUANTITY_V54 */
$gameEndings = [];
$gameEndingsEditor = [];
/* WAYFARER_GAME_TRAVEL_MODIFIERS_V73 */
$gameTravelModifiers = [];
$gameTravelModifiersEditor = [];
$error = '';


// ================================================================
// LOAD EXISTING GAME
// ================================================================

if (isset($_GET['id'])) {

    $stmt = $pdo->prepare("
        SELECT *
        FROM wf_games
        WHERE id = ?
    ");

    $stmt->execute([(int)$_GET['id']]);
    $existingGame = $stmt->fetch();

    if (!$existingGame) {
        die('Game not found.');
    }

    $game = array_merge($game, $existingGame);

    if (!empty($game['config'])) {

        $decodedConfig = json_decode(
            $game['config'],
            true
        );

        if (is_array($decodedConfig)) {
            $config = $decodedConfig;
        }
    }

    if (
        isset($config['traits']) &&
        is_array($config['traits'])
    ) {
        $traits = $config['traits'];
    }

    /* WAYFARER_PLAYER_TRAIT_DEFINITIONS_V52 */
    if (
        isset($config['player_traits']) &&
        is_array($config['player_traits'])
    ) {
        $playerTraits =
            array_values(
                $config['player_traits']
            );
    }

    /* WAYFARER_LOAD_GAME_TICK_EFFECTS_V33 */
    if (
        isset($config['tick_effects']) &&
        is_array($config['tick_effects'])
    ) {
        $gameTickEffects =
            array_values(
                $config['tick_effects']
            );
    }

    if (
        isset($config['setup']['choices']) &&
        is_array($config['setup']['choices'])
    ) {
        $startingChoices =
            array_values(
                $config['setup']['choices']
            );
    }

    /* WAYFARER_GAME_ENDINGS_V45 */
    if (
        isset($config['endings']) &&
        is_array($config['endings'])
    ) {
        $gameEndings =
            array_values(
                $config['endings']
            );
    }

    /* WAYFARER_LOAD_GAME_TRAVEL_MODIFIERS_V73 */
    if (
        isset($config['travel']['modifiers']) &&
        is_array($config['travel']['modifiers'])
    ) {
        $gameTravelModifiers =
            array_values(
                $config['travel']['modifiers']
            );
    }
}

$gameplayTickEffects =
    $gameTickEffects;

$startingChoicesEditor =
    $startingChoices;

$gameEndingsEditor =
    $gameEndings;

$gameTravelModifiersEditor =
    $gameTravelModifiers;


// ================================================================
// SAVE
// ================================================================

if ($_SERVER['REQUEST_METHOD'] === 'POST') {

    $game['id'] = !empty($_POST['id'])
        ? (int)$_POST['id']
        : null;

    $game['name'] =
        trim($_POST['name'] ?? '');

    $game['slug'] =
        trim($_POST['slug'] ?? '');

    $game['description'] =
        trim($_POST['description'] ?? '');

    $game['instructions'] =
        trim($_POST['instructions'] ?? '');

    $game['player_slots'] =
        max(0, (int)($_POST['player_slots'] ?? 0));

    $game['status'] =
        $_POST['status'] ?? 'draft';

	
    // ------------------------------------------------------------
    // BUILD GAME + PLAYER TRAIT DEFINITIONS
    // WAYFARER_PLAYER_TRAIT_DEFINITIONS_V52
    // ------------------------------------------------------------

$traitResult = buildTraitsFromPost(
    $_POST['traits'] ?? [],
    ['status']
);

$traits = $traitResult['traits'];

if ($traitResult['error'] !== '') {
    $error = $traitResult['error'];
}

$playerTraitResult =
    buildTraitsFromPost(
        $_POST['player_traits'] ?? [],
        ['status']
    );

$playerTraits =
    $playerTraitResult['traits'];

if (
    $error === '' &&
    $playerTraitResult['error'] !== ''
) {
    $error =
        'Player Traits: ' .
        $playerTraitResult['error'];
}


/* WAYFARER_GAME_SETTINGS_UNIVERSAL_TARGETS_V56 */
$gameplayRuntimeTargets =
    gameplayRuntimeStateTargets(
        $pdo,
        (int)($game['id'] ?? 0),
        $traits,
        $playerTraits,
        (int)(
            $game['player_slots']
            ?? 0
        )
    );

/* WAYFARER_BUILD_GAME_TRAVEL_MODIFIERS_V73 */
$postedGameTravelModifiers =
    isset($_POST['travel_modifiers']) &&
    is_array($_POST['travel_modifiers'])
        ? array_values(
            $_POST['travel_modifiers']
        )
        : [];

$gameTravelModifiersEditor =
    $postedGameTravelModifiers;

/*
 * Build the editor structure even if another Game Settings section already
 * has a validation error. This keeps selected Travel Conditions intact on the
 * failed POST. Only the first validation error becomes the page error.
 */
$gameTravelModifierResult =
    wayfarerBuildGameTravelModifiersFromPost(
        $postedGameTravelModifiers,
        $gameplayRuntimeTargets
    );

$gameTravelModifiersEditor =
    $gameTravelModifierResult[
        'editor_modifiers'
    ];

if (
    $error === '' &&
    $gameTravelModifierResult['error'] !==
    ''
) {
    $error =
        $gameTravelModifierResult['error'];
}

if (
    $gameTravelModifierResult['error'] ===
    ''
) {
    $gameTravelModifiers =
        $gameTravelModifierResult[
            'modifiers'
        ];
}

/* WAYFARER_STARTING_CHOICE_ITEM_QUANTITY_V54 */
$startingChoiceItemTargets =
    wayfarerStartingChoiceItemQuantityTargets(
        $pdo,
        (int)($game['id'] ?? 0)
    );

/* WAYFARER_BUILD_STARTING_CHOICES_V36 */
/* WAYFARER_STARTING_CHOICES_CANONICAL_EMPTY_V36_1 */
$startingChoicesSubmitted =
    isset($_POST['setup_choices_present']) ||
    array_key_exists(
        'setup_choices',
        $_POST
    );

$postedStartingChoices =
    isset($_POST['setup_choices']) &&
    is_array($_POST['setup_choices'])
        ? array_values(
            $_POST['setup_choices']
        )
        : [];

$startingChoicesEditor =
    $postedStartingChoices;

if ($error === '') {

    $startingChoiceResult =
        wayfarerBuildStartingChoicesFromPost(
            $postedStartingChoices,
            $traits,
            $playerTraits,
            (int)(
                $game['player_slots']
                ?? 0
            ),
            $startingChoiceItemTargets,
            $gameplayRuntimeTargets
        );

    if (
        $startingChoiceResult['error'] !==
        ''
    ) {
        $error =
            $startingChoiceResult['error'];
    } else {
        $startingChoices =
            $startingChoiceResult['choices'];

        $startingChoicesEditor =
            $startingChoices;
    }
}

/* WAYFARER_BUILD_GAME_ENDINGS_V45 */
$postedGameEndings =
    isset($_POST['endings']) &&
    is_array($_POST['endings'])
        ? array_values(
            $_POST['endings']
        )
        : [];

$gameEndingsEditor =
    $postedGameEndings;

if ($error === '') {

    $endingResult =
        wayfarerBuildGameEndingsFromPost(
            $pdo,
            (int)($game['id'] ?? 0),
            $postedGameEndings,
            $traits
        );

    if (
        $endingResult['error'] !==
        ''
    ) {
        $error =
            $endingResult['error'];
    } else {
        $gameEndings =
            $endingResult['endings'];

        $gameEndingsEditor =
            $gameEndings;
    }
}


/* WAYFARER_BUILD_GAME_TICK_EFFECTS_V33 */
$postedGameTickEffects =
    isset($_POST['tick_effects']) &&
    is_array($_POST['tick_effects'])
        ? array_values(
            $_POST['tick_effects']
        )
        : [];

$gameplayTickEffects =
    $postedGameTickEffects;

if ($error === '') {

    $gameTickEffectResult =
        gameplayBuildTickEffectsFromPost(
            $gameplayRuntimeTargets,
            $postedGameTickEffects,
            $gameplayRuntimeTargets
        );

    if (
        $gameTickEffectResult['error'] !==
        ''
    ) {
        $error =
            $gameTickEffectResult['error'];
    } else {
        $gameTickEffects =
            $gameTickEffectResult['effects'];

        $gameplayTickEffects =
            $gameTickEffects;
    }
}

    // ------------------------------------------------------------
    // VALIDATE GAME
    // ------------------------------------------------------------

    if ($error === '') {

        if ($game['name'] === '') {
            $error = 'Game name is required.';
        } elseif ($game['slug'] === '') {
            $error = 'Slug is required.';
        }
    }


    // ------------------------------------------------------------
    // BUILD CONFIG JSON
    // ------------------------------------------------------------

    if ($error === '') {

        /*
         * Preserve any other configuration already stored for the game.
         * Traits own only the "traits" section of config.
         */

        if (empty($config) && !empty($game['config'])) {

            $decodedConfig = json_decode(
                $game['config'],
                true
            );

            if (is_array($decodedConfig)) {
                $config = $decodedConfig;
            }
        }

		$startingRegionId =
    !empty($_POST['starting_region_id'])
        ? (int)$_POST['starting_region_id']
        : null;

if ($startingRegionId !== null) {
    $config['starting_region_id'] = $startingRegionId;
} else {
    unset($config['starting_region_id']);
}

        /* WAYFARER_GAME_TIME_SETTINGS_SAVE_V61 */
        $timeMode = strtolower(trim((string)($_POST['time_tracking'] ?? 'none')));
        if (!in_array($timeMode, ['none', 'days', 'hours'], true)) {
            $timeMode = 'none';
        }

        if ($timeMode === 'none') {
            unset($config['time']);
        } else {
            $startingDay = max(1, (int)($_POST['time_starting_day'] ?? 1));

            if ($timeMode === 'days') {
                $config['time'] = [
                    'mode' => 'days',
                    'starting_day' => $startingDay,
                    'ticks_per_day' => max(1, (int)($_POST['time_ticks_per_day'] ?? 1)),
                ];
            } else {
                $hoursPerDay = max(1, (int)($_POST['time_hours_per_day'] ?? 24));
                $startingHour = max(0, (int)($_POST['time_starting_hour'] ?? 8));
                if ($startingHour >= $hoursPerDay) {
                    $startingHour = $hoursPerDay - 1;
                }

                $config['time'] = [
                    'mode' => 'hours',
                    'starting_day' => $startingDay,
                    'starting_hour' => $startingHour,
                    'ticks_per_hour' => max(1, (int)($_POST['time_ticks_per_hour'] ?? 1)),
                    'hours_per_day' => $hoursPerDay,
                ];
            }
        }

        $config['traits'] =
            array_values(
                $traits
            );

        /* WAYFARER_PLAYER_TRAIT_DEFINITIONS_V52 */
        $config['player_traits'] =
            array_values(
                $playerTraits
            );

        /* WAYFARER_SAVE_GAME_TRAVEL_MODIFIERS_V73 */
        if ($gameTravelModifiers) {
            if (
                !isset($config['travel']) ||
                !is_array($config['travel'])
            ) {
                $config['travel'] = [];
            }

            $config['travel']['modifiers'] =
                array_values(
                    $gameTravelModifiers
                );
        } else {
            if (
                isset($config['travel']) &&
                is_array($config['travel'])
            ) {
                unset(
                    $config['travel']['modifiers']
                );

                if ($config['travel'] === []) {
                    unset($config['travel']);
                }
            }
        }

        /* WAYFARER_SAVE_GAME_TICK_EFFECTS_V33 */
        if ($gameTickEffects) {
            $config['tick_effects'] =
                array_values(
                    $gameTickEffects
                );
        } else {
            unset(
                $config['tick_effects']
            );
        }

        /* WAYFARER_SAVE_STARTING_CHOICES_V36 */
        /*
         * WAYFARER_STARTING_CHOICES_CANONICAL_EMPTY_V36_1
         *
         * If the Setup editor participated in this submission, its current
         * collection is the canonical collection. In particular, deleting the
         * final card must persist an explicit empty array rather than relying
         * on the absence of setup_choices in POST.
         */
        if ($startingChoicesSubmitted) {

            if (
                !isset($config['setup']) ||
                !is_array($config['setup'])
            ) {
                $config['setup'] = [];
            }

            $config['setup']['choices'] =
                array_values(
                    $startingChoices
                );
        }

        /* WAYFARER_SAVE_GAME_ENDINGS_V45 */
        $config['endings'] =
            array_values(
                $gameEndings
            );


        $game['config'] = json_encode(
            $config,
            JSON_UNESCAPED_SLASHES |
            JSON_UNESCAPED_UNICODE
        );

        if ($game['config'] === false) {
            $error = 'Unable to encode game configuration.';
        }
    }


    // ------------------------------------------------------------
    // WRITE GAME
    // ------------------------------------------------------------

    if ($error === '') {

        if ($game['id']) {

            $stmt = $pdo->prepare("
                UPDATE wf_games
                SET
                    name = ?,
                    slug = ?,
                    description = ?,
                    instructions = ?,
                    player_slots = ?,
                    config = ?,
                    status = ?
                WHERE id = ?
            ");

            $stmt->execute([
                $game['name'],
                $game['slug'],
                $game['description'],
                $game['instructions'],
                $game['player_slots'],
                $game['config'],
                $game['status'],
                $game['id']
            ]);

        } else {

            $uuid =
                bin2hex(random_bytes(16));

            $stmt = $pdo->prepare("
                INSERT INTO wf_games
                (
                    uuid,
                    name,
                    slug,
                    description,
                    instructions,
                    player_slots,
                    config,
                    status
                )
                VALUES (?, ?, ?, ?, ?, ?, ?, ?)
            ");

            $stmt->execute([
                $uuid,
                $game['name'],
                $game['slug'],
                $game['description'],
                $game['instructions'],
                $game['player_slots'],
                $game['config'],
                $game['status']
            ]);

            $game['id'] =
                (int)$pdo->lastInsertId();
        }

        /*
         * WAYFARER_STAY_ON_GAME_SETTINGS_V38
         *
         * Successful saves remain on the same Game Settings record and reopen
         * the tab the author was using.
         */
        $savedGameTab =
            (string)(
                $_POST['active_tab']
                ?? 'basics'
            );

        if (
            !in_array(
                $savedGameTab,
                [
                    'basics',
                    'setup',
                    'traits',
                    'gameplay',
                    'travel',
                    'endings',
                ],
                true
            )
        ) {
            $savedGameTab =
                'basics';
        }

        header(
            'Location: edit.php?id=' .
            (int)$game['id'] .
            '&tab=' .
            rawurlencode(
                $savedGameTab
            )
        );

        exit;
    }
}
// ================================================================
// LOAD REGIONS FOR STARTING REGION
// ================================================================

$regions = [];

if (!empty($game['id'])) {

    $regionStmt = $pdo->prepare("
        SELECT id, name
        FROM wf_regions
        WHERE game_id = ?
        ORDER BY name
    ");

    $regionStmt->execute([
        $game['id']
    ]);

    $regions = $regionStmt->fetchAll();
}

/* WAYFARER_GAME_SETTINGS_UNIVERSAL_TARGETS_RENDER_V56 */
$gameplayRuntimeTargets =
    gameplayRuntimeStateTargets(
        $pdo,
        (int)($game['id'] ?? 0),
        $traits,
        $playerTraits,
        (int)(
            $game['player_slots']
            ?? 0
        )
    );

/* WAYFARER_STARTING_CHOICE_ITEM_QUANTITY_RENDER_V54 */
$startingChoiceItemTargets =
    wayfarerStartingChoiceItemQuantityTargets(
        $pdo,
        (int)($game['id'] ?? 0)
    );

?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>
        <?= $game['id'] ? 'Edit Game' : 'New Game' ?> - Wayfarer
    </title>
    <link rel="stylesheet" href="../../assets/css/admin.css">
    <link rel="stylesheet" href="../../assets/css/builder.css?v=58">

<style>
/* WAYFARER_GAME_SETTINGS_NATIVE_BUILDER_PAGE_V24 */

.wayfarer-game-builder-page > h1,
.wayfarer-game-builder-page > .admin-back-link,
.wayfarer-game-builder-page > .admin-error-message,
.wayfarer-game-builder-page > .game-settings-editor {
    max-width: 1400px;
    margin-left: auto;
    margin-right: auto;
}

.wayfarer-game-builder-page .game-settings-editor {
    padding: 20px 24px 24px;
}

.wayfarer-game-builder-page .builder-save-bar {
    margin-bottom: -24px;
}

/*
 * admin.css has older Game Settings rules aimed at .admin-form-card.
 * The native Builder form intentionally no longer uses that class, so those
 * rules cannot reshape the Builder component.
 */

@media (max-width: 900px) {
    .wayfarer-game-builder-page .game-settings-editor {
        padding: 18px;
    }

    .wayfarer-game-builder-page .builder-save-bar {
        margin-bottom: -18px;
    }
}
</style>
</head>

<body class="wayfarer-admin-page wayfarer-game-edit-page wayfarer-game-builder-page">

<p class="admin-back-link"><a href="index.php">&larr; Games</a></p>

<h1>
    <?= $game['id'] ? 'Edit Game' : 'New Game' ?>
</h1>

<?php if ($error): ?>
    <p class="admin-error-message">
        <?= htmlspecialchars($error) ?>
    </p>
<?php endif; ?>

<div class="builder-editor-pane game-settings-editor" data-game-settings-editor>
<form method="post" class="builder-object-form game-settings-form">
    <!-- WAYFARER_GAME_SETTINGS_NATIVE_BUILDER_V24 -->
    <!-- WAYFARER_GAME_SETTINGS_TABS_V22 -->

    <?php if ($game['id']): ?>
        <input
            type="hidden"
            name="id"
            value="<?= (int)$game['id'] ?>"
        >
    <?php endif; ?>

    <input
        type="hidden"
        name="active_tab"
        value="<?= htmlspecialchars($_POST['active_tab'] ?? ($_GET['tab'] ?? 'basics')) ?>"
        data-game-active-tab
    >

    <div
        class="builder-editor-tabs"
        role="tablist"
        aria-label="Game Settings"
    >
        <button
            type="button"
            class="builder-editor-tab"
            data-game-tab="basics"
            role="tab"
        >
            Basics
        </button>

        <button
            type="button"
            class="builder-editor-tab"
            data-game-tab="setup"
            role="tab"
        >
            Setup
        </button>

        <button
            type="button"
            class="builder-editor-tab"
            data-game-tab="traits"
            role="tab"
        >
            Traits
        </button>

        <button
            type="button"
            class="builder-editor-tab"
            data-game-tab="gameplay"
            role="tab"
        >
            Gameplay
        </button>

        <button
            type="button"
            class="builder-editor-tab"
            data-game-tab="travel"
            role="tab"
        >
            Travel
        </button>

        <button
            type="button"
            class="builder-editor-tab"
            data-game-tab="endings"
            role="tab"
        >
            Endings
        </button>
    </div>


    <div
        class="builder-tab-panel"
        data-game-panel="basics"
        role="tabpanel"
    >
        <p>
            <label>
                Game Name<br>
                <input
                    type="text"
                    name="name"
                    size="60"
                    required
                    value="<?= htmlspecialchars($game['name']) ?>"
                >
            </label>
        </p>

        <p>
            <label>
                Slug<br>
                <input
                    type="text"
                    name="slug"
                    size="60"
                    required
                    value="<?= htmlspecialchars($game['slug']) ?>"
                >
            </label>
            <br>
            <small>
                Example: stormgate
            </small>
        </p>

        <p>
            <label>
                Description<br>
                <textarea
                    name="description"
                    rows="6"
                    cols="70"
                ><?= htmlspecialchars($game['description'] ?? '') ?></textarea>
            </label>
        </p>


        <p>
            <label>
                Status<br>
                <select name="status">
                    <option
                        value="draft"
                        <?= $game['status'] === 'draft' ? 'selected' : '' ?>
                    >
                        Draft
                    </option>

                    <option
                        value="active"
                        <?= $game['status'] === 'active' ? 'selected' : '' ?>
                    >
                        Active
                    </option>

                    <option
                        value="inactive"
                        <?= $game['status'] === 'inactive' ? 'selected' : '' ?>
                    >
                        Inactive
                    </option>
                </select>
            </label>
        </p>
    </div>


    <div
        class="builder-tab-panel"
        data-game-panel="setup"
        role="tabpanel"
        hidden
    >
        <h2>Setup</h2>

        <p class="admin-game-panel-intro">
            Configure what the player sees and chooses before the runtime state
            is created.
        </p>

        <p>
            <label>
                Instructions / Introduction<br>
                <textarea
                    name="instructions"
                    rows="8"
                    cols="70"
                ><?= htmlspecialchars($game['instructions'] ?? '') ?></textarea>
            </label>
            <br>
            <small>
                This text will become the opening introduction on the Game Start
                screen.
            </small>
        </p>

        <p>
            <label>
                Player Character Slots<br>
                <input
                    type="number"
                    name="player_slots"
                    min="0"
                    value="<?= (int)$game['player_slots'] ?>"
                >
            </label>
            <br>
            <small>
                Each slot creates one built-in player character, requires a name at game start, and receives its own copy of every Player Trait. Use 0 for games without named player characters.
            </small>
        </p>

        <p>
            <label>
                Starting Region
                <br>

                <select name="starting_region_id">

                    <option value="">
                        -- Select Starting Region --
                    </option>

                    <?php foreach ($regions as $region): ?>

                        <option
                            value="<?= (int)$region['id'] ?>"
                            <?= ($config['starting_region_id'] ?? '') == $region['id']
                                ? 'selected'
                                : ''
                            ?>
                        >
                            <?= htmlspecialchars($region['name']) ?>
                        </option>

                    <?php endforeach; ?>

                </select>
            </label>
        </p>

        <!-- WAYFARER_STARTING_CHOICES_EDITOR_V36 -->
        <?php
        $GLOBALS[
            'wayfarer_starting_item_quantity_targets'
        ] = $startingChoiceItemTargets;

        wayfarerRenderStartingChoicesEditor(
            $startingChoicesEditor,
            $traits,
            $playerTraits,
            (int)(
                $game['player_slots']
                ?? 0
            ),
            $gameplayRuntimeTargets
        );

        unset(
            $GLOBALS[
                'wayfarer_starting_item_quantity_targets'
            ]
        );
        ?>
    </div>

    <div
        class="builder-tab-panel"
        data-game-panel="traits"
        role="tabpanel"
        hidden
    >
        <h2>Traits</h2>

        <!-- WAYFARER_PLAYER_TRAIT_DEFINITIONS_V52 -->
        <?php require_once __DIR__ . '/../../includes/traits/render.php'; ?>

        <section class="game-trait-definition-section">
            <h3>Game Traits</h3>

            <p class="admin-game-panel-intro">
                One shared value for the entire playthrough. Use these for
                global state such as Day, Weather, or world-wide Reputation.
            </p>

            <?php
            wayfarerRenderTraitEditor(
                $traits,
                [
                    'field_name' => 'traits',
                    'editor_id' => 'game-traits',
                    'allowed_surfaces' => ['status'],
                    'intro' =>
                        'Game Traits have one runtime value for the whole game. ' .
                        'Status controls whether that shared value appears to the player.',
                ]
            );
            ?>
        </section>

        <hr>

        <section class="game-trait-definition-section">
            <h3>Player Traits</h3>

            <p class="admin-game-panel-intro">
                Define a trait once here and Wayfarer gives every built-in player
                character an independent runtime copy. For example, five Player
                Character Slots plus a Health trait creates five separate Health values.
            </p>

            <?php
            wayfarerRenderTraitEditor(
                $playerTraits,
                [
                    'field_name' => 'player_traits',
                    'editor_id' => 'player-traits',
                    'allowed_surfaces' => ['status'],
                    'intro' =>
                        'Player Traits are instantiated once per named player slot. ' .
                        'They are separate from Character Entity traits used by NPCs ' .
                        'and characters who may later join the party.',
                ]
            );
            ?>
        </section>
    </div>


    <div
        class="builder-tab-panel"
        data-game-panel="gameplay"
        data-builder-editor
        role="tabpanel"
        hidden
    >
        <h2>Gameplay</h2>

        <p class="admin-game-panel-intro">
            Global gameplay rules that apply regardless of the player's current
            Region.
        </p>

        <!-- WAYFARER_GAME_LEVEL_TICK_EFFECT_EDITOR_V33 -->
        <?php
        $gameConfig =
            $config;

        $gameplayGameTraitTargets =
            gameplayNumericTraitTargets(
                $traits,
                'game'
            );

        $gameplayScopeTraitTargets =
            [];

        $gameplayScopeKey =
            '';

        $gameplayScopeLabel =
            '';

        $gameplayAllowNavigation =
            false;

        $gameplayNavigationType =
            '';

        $gameplayTargetCatalog =
            $gameplayRuntimeTargets;

        $gameplayConditionTargets =
            $gameplayRuntimeTargets;

        $gameplayDescription =
            'These effects are applied on every gameplay tick before the ' .
            'current Region Tick Effects.';

        $gameplayEmbedded =
            true;

        require __DIR__ .
            '/../../includes/gameplay/tick-effects-editor.php';
        ?>

        <!-- WAYFARER_GAME_TIME_SETTINGS_UI_V61 -->
        <?php
        $timeSettings =
            isset($config['time']) && is_array($config['time'])
                ? $config['time']
                : [];
        $timeModeValue = (string)($timeSettings['mode'] ?? 'none');
        ?>
        <div class="admin-game-placeholder-card" data-wayfarer-time-settings>
            <strong>Game Time</strong>

            <p>
                Configure an optional player-facing clock. Time advances once for
                every normal gameplay tick. It is runtime clock state, not a Game Trait.
            </p>

            <p>
                <label>
                    Time Tracking<br>
                    <select name="time_tracking" data-wayfarer-time-mode>
                        <option value="none" <?= $timeModeValue === 'none' ? 'selected' : '' ?>>None</option>
                        <option value="days" <?= $timeModeValue === 'days' ? 'selected' : '' ?>>Days</option>
                        <option value="hours" <?= $timeModeValue === 'hours' ? 'selected' : '' ?>>Hours</option>
                    </select>
                </label>
            </p>

            <div data-wayfarer-time-common>
                <p>
                    <label>
                        Starting Day<br>
                        <input type="number" name="time_starting_day" min="1" value="<?= (int)($timeSettings['starting_day'] ?? 1) ?>">
                    </label>
                </p>
            </div>

            <div data-wayfarer-time-days>
                <p>
                    <label>
                        Ticks per Day<br>
                        <input type="number" name="time_ticks_per_day" min="1" value="<?= (int)($timeSettings['ticks_per_day'] ?? 4) ?>">
                    </label>
                </p>
            </div>

            <div data-wayfarer-time-hours>
                <p>
                    <label>
                        Starting Hour<br>
                        <input type="number" name="time_starting_hour" min="0" value="<?= (int)($timeSettings['starting_hour'] ?? 8) ?>">
                    </label>
                </p>
                <p>
                    <label>
                        Ticks per Hour<br>
                        <input type="number" name="time_ticks_per_hour" min="1" value="<?= (int)($timeSettings['ticks_per_hour'] ?? 1) ?>">
                    </label>
                </p>
                <p>
                    <label>
                        Hours per Day<br>
                        <input type="number" name="time_hours_per_day" min="1" value="<?= (int)($timeSettings['hours_per_day'] ?? 24) ?>">
                    </label>
                </p>
            </div>
        </div>

        <script>
        (() => {
            const host = document.querySelector('[data-wayfarer-time-settings]');
            if (!host) return;
            const mode = host.querySelector('[data-wayfarer-time-mode]');
            const common = host.querySelector('[data-wayfarer-time-common]');
            const days = host.querySelector('[data-wayfarer-time-days]');
            const hours = host.querySelector('[data-wayfarer-time-hours]');
            const render = () => {
                const value = mode ? mode.value : 'none';
                if (common) common.hidden = value === 'none';
                if (days) days.hidden = value !== 'days';
                if (hours) hours.hidden = value !== 'hours';
            };
            if (mode) mode.addEventListener('change', render);
            render();
        })();
        </script>
    </div>


    <!-- WAYFARER_GAME_TRAVEL_MODIFIERS_PANEL_V73 -->
    <div
        class="builder-tab-panel"
        data-game-panel="travel"
        role="tabpanel"
        hidden
    >
        <?php
        wayfarerRenderGameTravelModifiersEditor(
            $gameTravelModifiersEditor,
            $gameplayRuntimeTargets
        );
        ?>
    </div>


    <!-- WAYFARER_GAME_ENDINGS_V45 -->
    <div
        class="builder-tab-panel"
        data-game-panel="endings"
        role="tabpanel"
        hidden
    >
        <h2>Endings</h2>

        <p class="admin-game-panel-intro">
            Endings are terminal game states. After any runtime state change,
            Wayfarer checks these conditions in priority order.
        </p>

        <?php
        wayfarerRenderGameEndingsEditor(
            $pdo,
            (int)($game['id'] ?? 0),
            $gameEndingsEditor,
            $traits
        );
        ?>
    </div>


    <div class="builder-save-bar">
        <button class="admin-primary-button" type="submit">
            Save Game
        </button>
    </div>

</form>
</div>

<script>
/* WAYFARER_CONFIRM_TRAIT_REMOVAL_V21_1 */
(function () {

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


    function findTraitContainer(button) {

        let node =
            button.parentElement;

        while (
            node &&
            node !== document.body
        ) {

            if (
                node.querySelector &&
                node.querySelector(
                    'input[name^="traits["], ' +
                    'select[name^="traits["], ' +
                    'textarea[name^="traits["], ' +
                    'input[name^="player_traits["], ' +
                    'select[name^="player_traits["], ' +
                    'textarea[name^="player_traits["]'
                )
            ) {
                return node;
            }

            /*
             * Stop before accidentally climbing into the entire form.
             */
            if (
                node.tagName === 'FORM'
            ) {
                break;
            }

            node =
                node.parentElement;
        }

        return null;
    }


    function getTraitName(container) {

        if (!container) {
            return '';
        }

        const nameInput =
            container.querySelector(
                'input[name^="traits["][name$="[name]"], ' +
                'input[name*="[name]"]'
            );

        if (!nameInput) {
            return '';
        }

        return String(
            nameInput.value || ''
        ).trim();
    }


    document.addEventListener(
        'click',
        function (event) {

            const button =
                event.target.closest(
                    'button, input[type="button"], input[type="submit"]'
                );

            if (!button) {
                return;
            }

            const buttonText =
                normalizeText(
                    button.tagName === 'INPUT'
                        ? button.value
                        : button.textContent
                );

            const explicitRemoveTrait =
                buttonText === 'remove trait';

            const traitContainer =
                findTraitContainer(
                    button
                );

            /*
             * A generic "Remove" button counts only when it is inside a
             * container with traits[...] form controls. This avoids touching
             * Tick Effects, media controls, or object deletion.
             */
            const contextualTraitRemove =
                traitContainer !== null &&
                (
                    buttonText === 'remove' ||
                    buttonText === 'remove trait'
                );

            if (
                !explicitRemoveTrait &&
                !contextualTraitRemove
            ) {
                return;
            }

            const traitName =
                getTraitName(
                    traitContainer
                );

            const message =
                traitName !== ''
                    ? 'Are you sure you want to remove the trait "' +
                        traitName +
                        '"?'
                    : 'Are you sure you want to remove this trait?';

            if (
                !window.confirm(
                    message
                )
            ) {

                event.preventDefault();
                event.stopPropagation();
                event.stopImmediatePropagation();
            }
        },
        true
    );

})();
</script>

<!-- WAYFARER_GAME_SETTINGS_GAMEPLAY_JS_V33 -->
<script src="../../assets/js/builder.js?v=58"></script>
<!-- WAYFARER_GAME_TRAVEL_MODIFIERS_JS_INCLUDE_V73 -->
<script src="../../assets/js/game-travel.js?v=73"></script>
<script src="../../assets/js/starting-choices.js?v=58"></script>
<script src="../../assets/js/game-endings.js?v=45"></script>

<script>
/* WAYFARER_GAME_SETTINGS_NATIVE_TAB_BEHAVIOR_V24 */
(function () {

    const editor =
        document.querySelector(
            '[data-game-settings-editor]'
        );

    if (!editor) {
        return;
    }

    const form =
        editor.querySelector(
            '.game-settings-form'
        );

    if (!form) {
        return;
    }

    const tabs =
        Array.from(
            form.querySelectorAll(
                '[data-game-tab]'
            )
        );

    const panels =
        Array.from(
            form.querySelectorAll(
                '[data-game-panel]'
            )
        );

    const activeTabInput =
        form.querySelector(
            '[data-game-active-tab]'
        );

    function activateTab(tabKey) {

        const valid =
            tabs.some(
                function (tab) {
                    return tab.dataset.gameTab === tabKey;
                }
            );

        if (!valid) {
            tabKey = 'basics';
        }

        tabs.forEach(
            function (tab) {

                const active =
                    tab.dataset.gameTab === tabKey;

                tab.classList.toggle(
                    'is-active',
                    active
                );

                tab.setAttribute(
                    'aria-selected',
                    active ? 'true' : 'false'
                );
            }
        );

        panels.forEach(
            function (panel) {
                panel.hidden =
                    panel.dataset.gamePanel !== tabKey;
            }
        );

        if (activeTabInput) {
            activeTabInput.value =
                tabKey;
        }

        const url =
            new URL(
                window.location.href
            );

        url.searchParams.set(
            'tab',
            tabKey
        );

        window.history.replaceState(
            {},
            '',
            url
        );
    }

    tabs.forEach(
        function (tab) {
            tab.addEventListener(
                'click',
                function () {
                    activateTab(
                        tab.dataset.gameTab
                    );
                }
            );
        }
    );

    const requestedTab =
        new URLSearchParams(
            window.location.search
        ).get('tab') ||
        (
            activeTabInput
                ? activeTabInput.value
                : 'basics'
        );

    activateTab(
        requestedTab
    );

})();
</script>

<!-- WAYFARER_HIERARCHICAL_TARGETS_V80 -->
<script src="/wayfarer/assets/js/hierarchical-targets.js?v=85"></script>
</body>
</html>



==============================================================================
FILE: admin/games/index.php
==============================================================================

<?php

require_once __DIR__ . '/../../config/database.php';

$stmt = $pdo->query("
    SELECT id, name, slug, status, updated_at
    FROM wf_games
    ORDER BY name
");

$games = $stmt->fetchAll();

?>
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <title>Wayfarer</title>
    <link rel="stylesheet" href="../../assets/css/admin.css">
</head>

<body class="wayfarer-admin-page wayfarer-games-page">

<h1>Wayfarer</h1>

<h2>Games</h2>

<p>
    <a class="admin-primary-action" href="edit.php">+ New Game</a>
</p>

<?php if (empty($games)): ?>

    <p>No games have been created yet.</p>

<?php else: ?>

    <table border="1" cellpadding="8" cellspacing="0" class="admin-table games-table">

        <thead>
            <tr>
                <th>Name</th>
                <th>Slug</th>
                <th>Status</th>
                <th>Last Updated</th>
                <th>Actions</th>
            </tr>
        </thead>

        <tbody>

        <?php foreach ($games as $game): ?>

            <tr>

                <td>
                    <strong>
                        <?= htmlspecialchars($game['name']) ?>
                    </strong>
                </td>

                <td>
                    <?= htmlspecialchars($game['slug']) ?>
                </td>

                <td>
                    <?= htmlspecialchars($game['status']) ?>
                </td>

                <td>
                    <?= htmlspecialchars($game['updated_at']) ?>
                </td>

                <td>

                    <a href="../builder.php?game=<?= (int)$game['id'] ?>">
                        Open Builder
                    </a>

                    |

                    <a href="edit.php?id=<?= (int)$game['id'] ?>">
                        Game Settings
                    </a>

                </td>

            </tr>

        <?php endforeach; ?>

        </tbody>

    </table>

<?php endif; ?>

</body>
</html>


==============================================================================
FILE: assets/css/admin.css
==============================================================================

/*
|--------------------------------------------------------------------------
| Wayfarer Admin Theme
|--------------------------------------------------------------------------
| Shared visual language for Wayfarer administrative pages.
*/

:root {
    --wf-border: #d8dbe2;
    --wf-border-strong: #b8bdc7;
    --wf-surface: #ffffff;
    --wf-surface-soft: #f6f7f9;
    --wf-page: #f3f4f6;
    --wf-text: #20242a;
    --wf-muted: #667085;
    --wf-accent: #2f5ea8;
    --wf-accent-hover: #244b88;
    --wf-accent-soft: #edf3fc;
    --wf-success-soft: #eef8f1;
    --wf-success-text: #28603a;
    --wf-radius: 8px;
    --wf-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
}


.wayfarer-admin-page {
    box-sizing: border-box;
    margin: 0;
    padding: 28px;
    background: var(--wf-page);
    color: var(--wf-text);
    font-family:
        -apple-system,
        BlinkMacSystemFont,
        "Segoe UI",
        Roboto,
        Arial,
        sans-serif;
    font-size: 15px;
    line-height: 1.45;
}


.wayfarer-admin-page *,
.wayfarer-admin-page *::before,
.wayfarer-admin-page *::after {
    box-sizing: border-box;
}


.wayfarer-admin-page > * {
    max-width: 1180px;
    margin-left: auto;
    margin-right: auto;
}


.wayfarer-admin-page > h1 {
    margin-top: 0;
    margin-bottom: 2px;
    font-size: 2rem;
    line-height: 1.15;
}


.wayfarer-admin-page > h2 {
    margin-top: 0;
    margin-bottom: 20px;
    color: var(--wf-muted);
    font-size: 1rem;
    font-weight: 500;
}


.wayfarer-admin-page a {
    color: var(--wf-accent);
}


.wayfarer-admin-page a:hover {
    color: var(--wf-accent-hover);
}


/* ------------------------------------------------------------------
   GAMES INDEX
------------------------------------------------------------------ */

.wayfarer-games-page > p {
    margin-top: 0;
    margin-bottom: 18px;
}


.admin-primary-action {
    display: inline-block;
    padding: 9px 14px;
    border: 1px solid #214b86;
    border-radius: 6px;
    background: var(--wf-accent);
    color: #ffffff !important;
    text-decoration: none;
    font-weight: 600;
    box-shadow: var(--wf-shadow);
}


.admin-primary-action:hover {
    background: var(--wf-accent-hover);
    color: #ffffff !important;
}


.admin-table {
    width: 100%;
    overflow: hidden;
    border: 1px solid var(--wf-border);
    border-collapse: separate;
    border-spacing: 0;
    border-radius: var(--wf-radius);
    background: var(--wf-surface);
    box-shadow: var(--wf-shadow);
}


.admin-table th,
.admin-table td {
    padding: 12px 14px;
    border: 0;
    border-bottom: 1px solid var(--wf-border);
    text-align: left;
    vertical-align: middle;
}


.admin-table th {
    background: var(--wf-surface-soft);
    color: #404650;
    font-size: 0.78rem;
    font-weight: 700;
    letter-spacing: 0.045em;
    text-transform: uppercase;
}


.admin-table tr:last-child td {
    border-bottom: 0;
}


.admin-table tbody tr:hover td {
    background: #fafbfc;
}


.games-table td:first-child {
    font-weight: 700;
}


.games-table td:nth-child(2) {
    color: var(--wf-muted);
    font-family:
        ui-monospace,
        SFMono-Regular,
        Menlo,
        Consolas,
        monospace;
    font-size: 0.9rem;
}


.games-table td:nth-child(3) {
    text-transform: capitalize;
}


.games-table td:last-child {
    white-space: nowrap;
}


.games-table td:last-child a {
    display: inline-block;
    margin: 2px 5px 2px 0;
    padding: 6px 9px;
    border: 1px solid var(--wf-border-strong);
    border-radius: 5px;
    background: var(--wf-surface);
    color: var(--wf-text);
    text-decoration: none;
    font-size: 0.9rem;
    font-weight: 600;
}


.games-table td:last-child a:hover {
    border-color: #9cabc0;
    background: var(--wf-accent-soft);
    color: var(--wf-accent-hover);
}


/* Make the primary builder action visually stronger. */
.games-table td:last-child a:first-child {
    border-color: #a9bddc;
    background: var(--wf-accent-soft);
    color: var(--wf-accent);
}


/* ------------------------------------------------------------------
   RESPONSIVE
------------------------------------------------------------------ */

@media (max-width: 760px) {

    .wayfarer-admin-page {
        padding: 16px;
    }

    .games-table {
        display: block;
        overflow-x: auto;
        white-space: nowrap;
    }

}


@media (max-width: 520px) {

    .wayfarer-admin-page > h1 {
        font-size: 1.65rem;
    }

    .admin-table th,
    .admin-table td {
        padding: 10px;
    }

}


/* ==========================================================================
   GAME SETTINGS PAGE — v13.1
   ========================================================================== */

.wayfarer-game-edit-page {
    padding-bottom: 60px;
}


.wayfarer-game-edit-page > h1,
.wayfarer-game-edit-page > .admin-back-link,
.wayfarer-game-edit-page > .admin-error-message,
.wayfarer-game-edit-page > .admin-form-card {
    max-width: 980px;
}


.admin-back-link {
    margin-top: 0;
    margin-bottom: 14px;
}


.admin-back-link a {
    text-decoration: none;
    font-weight: 600;
}


.admin-error-message {
    padding: 11px 14px;
    border: 1px solid #e8b8be;
    border-radius: 6px;
    background: #fff4f5;
    color: #9a1b2a;
    font-weight: 600;
}


.admin-form-card {
    padding: 22px 26px 0;
    border: 1px solid var(--wf-border);
    border-radius: var(--wf-radius);
    background: var(--wf-surface);
    box-shadow: var(--wf-shadow);
}


.admin-form-card > p:first-of-type {
    margin-top: 0;
}


.admin-form-card h2,
.admin-form-card h3 {
    color: var(--wf-text);
}


.admin-form-card h2 {
    margin-top: 26px;
    margin-bottom: 6px;
    font-size: 1.2rem;
}


.admin-form-card label {
    color: #303640;
    font-weight: 600;
}


.admin-form-card small {
    color: var(--wf-muted);
    font-weight: 400;
}


.admin-form-card input[type="text"],
.admin-form-card input[type="number"],
.admin-form-card input[type="password"],
.admin-form-card input[type="file"],
.admin-form-card select,
.admin-form-card textarea {
    box-sizing: border-box;
    max-width: 100%;
    margin-top: 5px;
    padding: 8px 9px;
    border: 1px solid var(--wf-border-strong);
    border-radius: 5px;
    background: #fff;
    color: var(--wf-text);
    font: inherit;
}


.admin-form-card input[type="text"],
.admin-form-card textarea {
    width: min(100%, 720px);
}


.admin-form-card textarea {
    min-height: 110px;
    resize: vertical;
}


.admin-form-card input:focus,
.admin-form-card select:focus,
.admin-form-card textarea:focus {
    outline: 2px solid rgba(47, 94, 168, 0.18);
    border-color: #7f9dc8;
}


.admin-form-card > hr {
    margin: 26px -26px 22px;
    border: 0;
    border-top: 1px solid var(--wf-border);
}


/*
 * This deliberately styles any fieldset in Game Settings rather than
 * depending on the old traits-container/add-trait implementation.
 */
.admin-form-card fieldset {
    margin: 16px 0;
    padding: 16px 18px;
    border: 1px solid var(--wf-border);
    border-radius: 7px;
    background: var(--wf-surface-soft);
}


.admin-form-card fieldset legend {
    padding: 0 6px;
    color: #404650;
    font-weight: 700;
}


.admin-form-card fieldset > p {
    margin-top: 10px;
    margin-bottom: 10px;
}


/*
 * Existing trait row hooks continue to get slightly tighter handling when
 * present, but they are not required.
 */
.admin-form-card .trait-row {
    margin-bottom: 14px !important;
}


.admin-form-card .trait-number-fields {
    display: flex;
    flex-wrap: wrap;
    gap: 16px;
}


.admin-form-card .trait-number-fields > p {
    margin-top: 0;
    margin-bottom: 0;
}


/* ------------------------------------------------------------------
   BUTTONS
------------------------------------------------------------------ */

.admin-form-card button,
.admin-primary-button,
.admin-secondary-button,
.admin-danger-button {
    padding: 8px 13px;
    border: 1px solid var(--wf-border-strong);
    border-radius: 6px;
    background: var(--wf-surface);
    color: var(--wf-text);
    font: inherit;
    font-weight: 600;
    cursor: pointer;
}


.admin-form-card button:hover {
    background: var(--wf-accent-soft);
    border-color: #9cabc0;
}


.admin-primary-button {
    border-color: #214b86 !important;
    background: var(--wf-accent) !important;
    color: #fff !important;
}


.admin-primary-button:hover {
    background: var(--wf-accent-hover) !important;
}


.admin-secondary-button {
    background: var(--wf-surface) !important;
}


.admin-danger-button,
.admin-form-card .remove-trait {
    border-color: #d7a4ab !important;
    background: #fff !important;
    color: #a61b2b !important;
}


.admin-danger-button:hover,
.admin-form-card .remove-trait:hover {
    background: #fff4f5 !important;
}


/*
 * Treat the last form paragraph as the Save footer. In the current editor,
 * the Save Game control lives there.
 */
.admin-form-card > p:last-child {
    display: flex;
    justify-content: flex-end;
    margin: 22px -26px 0;
    padding: 14px 26px;
    border-top: 1px solid var(--wf-border);
    border-radius: 0 0 var(--wf-radius) var(--wf-radius);
    background: var(--wf-surface-soft);
}


/* ------------------------------------------------------------------
   RESPONSIVE
------------------------------------------------------------------ */

@media (max-width: 720px) {

    .admin-form-card {
        padding: 18px 18px 0;
    }

    .admin-form-card > hr {
        margin-left: -18px;
        margin-right: -18px;
    }

    .admin-form-card > p:last-child {
        margin-left: -18px;
        margin-right: -18px;
        padding-left: 18px;
        padding-right: 18px;
    }

    .admin-form-card .trait-number-fields {
        display: block;
    }

}


/* ==========================================================================
   GAME SETTINGS TABS — v22
   Mirrors the authored-object tab language used by builder.php.
   ========================================================================== */

.admin-game-tabs-form {
    padding-top: 0;
}

.admin-game-tabs {
    display: flex;
    gap: 4px;
    margin: 0 -26px 20px;
    padding: 0 26px;
    border-bottom: 1px solid var(--wf-border);
    background: var(--wf-surface);
    border-radius: var(--wf-radius) var(--wf-radius) 0 0;
}

.admin-game-tab {
    position: relative;
    bottom: -1px;
    margin: 0;
    padding: 12px 14px !important;
    border: 1px solid transparent !important;
    border-bottom: 1px solid var(--wf-border) !important;
    border-radius: 0 !important;
    background: transparent !important;
    color: var(--wf-muted) !important;
    font: inherit;
    font-weight: 600 !important;
    cursor: pointer;
}

.admin-game-tab:hover {
    color: var(--wf-text) !important;
    background: var(--wf-surface-soft) !important;
}

.admin-game-tab.is-active {
    color: var(--wf-accent) !important;
    background: var(--wf-surface) !important;
    border-color:
        var(--wf-border)
        var(--wf-border)
        var(--wf-surface) !important;
    border-radius: 6px 6px 0 0 !important;
}

.admin-game-tab-panel[hidden] {
    display: none !important;
}

.admin-game-tab-panel > h2:first-child {
    margin-top: 0;
}

.admin-game-tab-panel > p:first-child {
    margin-top: 0;
}

.admin-game-panel-intro {
    color: var(--wf-muted);
}

.admin-game-placeholder-card {
    margin: 16px 0 4px;
    padding: 16px 18px;
    border: 1px solid var(--wf-border);
    border-radius: 7px;
    background: var(--wf-surface-soft);
}

.admin-game-placeholder-card > p:last-child {
    margin-bottom: 0;
}

.admin-game-save-bar {
    display: flex;
    justify-content: flex-end;
    margin: 22px -26px 0;
    padding: 14px 26px;
    border-top: 1px solid var(--wf-border);
    border-radius: 0 0 var(--wf-radius) var(--wf-radius);
    background: var(--wf-surface-soft);
}

/*
 * The old rule treated the form's last direct <p> as the save footer.
 * The tabbed editor now has an explicit save bar.
 */
.admin-game-tabs-form > p:last-child {
    display: block;
    margin: initial;
    padding: initial;
    border: 0;
    background: transparent;
}

@media (max-width: 720px) {

    .admin-game-tabs {
        overflow-x: auto;
        margin-left: -18px;
        margin-right: -18px;
        padding-left: 18px;
        padding-right: 18px;
    }

    .admin-game-tab {
        white-space: nowrap;
    }

    .admin-game-save-bar {
        margin-left: -18px;
        margin-right: -18px;
        padding-left: 18px;
        padding-right: 18px;
    }
}

/* ==========================================================================
   WAYFARER_GAME_SETTINGS_BUILDER_MATCH_V23

   Make Game Settings use the same visual language as the object editor in
   builder.php: wide editor card, compact tabs, 720px fields, and persistent
   save footer.
   ========================================================================== */

.wayfarer-game-edit-page > h1,
.wayfarer-game-edit-page > .admin-back-link,
.wayfarer-game-edit-page > .admin-error-message,
.wayfarer-game-edit-page > .admin-form-card {
    max-width: 1400px;
}

/* Match the Builder editor card. */
.wayfarer-game-edit-page .admin-game-tabs-form {
    padding: 20px 24px 0;
    border: 1px solid var(--wf-border);
    border-radius: var(--wf-radius);
    background: var(--wf-surface);
    box-shadow: var(--wf-shadow);
}

/* Builder tabs sit inside the editor padding rather than spanning the card. */
.wayfarer-game-edit-page .admin-game-tabs {
    display: flex;
    gap: 4px;
    margin: 0 0 20px;
    padding: 0;
    border-bottom: 1px solid var(--wf-border);
    background: transparent;
    border-radius: 0;
}

.wayfarer-game-edit-page .admin-game-tab {
    position: relative;
    bottom: -1px;
    margin: 0;
    padding: 9px 14px !important;
    border: 1px solid transparent !important;
    border-bottom: 1px solid var(--wf-border) !important;
    border-radius: 0 !important;
    background: transparent !important;
    color: var(--wf-muted) !important;
    font: inherit;
    font-weight: 600 !important;
    cursor: pointer;
}

.wayfarer-game-edit-page .admin-game-tab:hover {
    color: var(--wf-text) !important;
    background: var(--wf-surface-soft) !important;
}

.wayfarer-game-edit-page .admin-game-tab.is-active {
    color: var(--wf-accent) !important;
    background: var(--wf-surface) !important;
    border-color:
        var(--wf-border)
        var(--wf-border)
        var(--wf-surface) !important;
    border-radius: 6px 6px 0 0 !important;
}

/* Match Builder field sizing. */
.wayfarer-game-edit-page .admin-game-tab-panel label {
    font-weight: 600;
}

.wayfarer-game-edit-page .admin-game-tab-panel small {
    color: var(--wf-muted);
    font-weight: 400;
}

.wayfarer-game-edit-page .admin-game-tab-panel input[type="text"],
.wayfarer-game-edit-page .admin-game-tab-panel input[type="number"],
.wayfarer-game-edit-page .admin-game-tab-panel input[type="file"],
.wayfarer-game-edit-page .admin-game-tab-panel select,
.wayfarer-game-edit-page .admin-game-tab-panel textarea {
    box-sizing: border-box;
    max-width: 100%;
    margin-top: 4px;
    padding: 7px 8px;
    border: 1px solid var(--wf-border-strong);
    border-radius: 5px;
    background: var(--wf-surface);
    color: var(--wf-text);
    font: inherit;
}

.wayfarer-game-edit-page .admin-game-tab-panel input[type="text"],
.wayfarer-game-edit-page .admin-game-tab-panel textarea {
    width: min(100%, 720px);
}

.wayfarer-game-edit-page .admin-game-tab-panel textarea {
    resize: vertical;
}

/* Do not let old Game Settings paragraph/footer rules distort tab contents. */
.wayfarer-game-edit-page .admin-game-tab-panel > p {
    display: block;
    justify-content: initial;
    margin-left: 0;
    margin-right: 0;
    padding-left: 0;
    padding-right: 0;
    border: 0;
    border-radius: 0;
    background: transparent;
}

/* Match builder.php's save bar exactly. */
.wayfarer-game-edit-page .admin-game-save-bar {
    display: flex;
    justify-content: flex-end;
    margin: 22px -24px 0;
    padding: 14px 24px;
    border-top: 1px solid var(--wf-border);
    border-radius: 0 0 var(--wf-radius) var(--wf-radius);
    background: var(--wf-surface-soft);
}

.wayfarer-game-edit-page .admin-game-save-bar .admin-primary-button {
    padding: 9px 16px;
}

/* Trait fieldsets should also resemble Builder fieldsets. */
.wayfarer-game-edit-page .admin-game-tab-panel fieldset {
    margin: 0 0 16px;
    padding: 14px 16px;
    border: 1px solid var(--wf-border);
    border-radius: 7px;
    background: var(--wf-surface);
}

.wayfarer-game-edit-page .admin-game-tab-panel fieldset legend {
    padding: 0 6px;
}

/* Responsive behavior mirrors Builder. */
@media (max-width: 900px) {

    .wayfarer-game-edit-page .admin-game-tabs-form {
        padding: 18px 18px 0;
    }

    .wayfarer-game-edit-page .admin-game-save-bar {
        margin-left: -18px;
        margin-right: -18px;
        padding-left: 18px;
        padding-right: 18px;
    }
}

@media (max-width: 560px) {

    .wayfarer-game-edit-page .admin-game-tabs {
        overflow-x: auto;
        margin-left: 0;
        margin-right: 0;
        padding-left: 0;
        padding-right: 0;
    }

    .wayfarer-game-edit-page .admin-game-tab {
        white-space: nowrap;
    }
}


==============================================================================
FILE: assets/css/builder.css
==============================================================================

/*
|--------------------------------------------------------------------------
| Wayfarer Builder
|--------------------------------------------------------------------------
| Master/detail authored-object workspace.
| This stylesheet is intentionally presentation-only.
*/

:root {
    --wf-border: #d8dbe2;
    --wf-border-strong: #b8bdc7;
    --wf-surface: #ffffff;
    --wf-surface-soft: #f6f7f9;
    --wf-text: #20242a;
    --wf-muted: #667085;
    --wf-accent: #2f5ea8;
    --wf-accent-soft: #edf3fc;
    --wf-danger: #a61b2b;
    --wf-danger-soft: #fff4f5;
    --wf-radius: 8px;
    --wf-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
}


.wayfarer-builder-page {
    margin: 0;
    padding: 24px;
    background: #f3f4f6;
    color: var(--wf-text);
    font-family:
        -apple-system,
        BlinkMacSystemFont,
        "Segoe UI",
        Roboto,
        Arial,
        sans-serif;
    line-height: 1.45;
}


.wayfarer-builder-page > h1,
.wayfarer-builder-page > p,
.wayfarer-builder-page > nav,
.wayfarer-builder-page > .builder-workspace,
.wayfarer-builder-page > .builder-back-link {
    max-width: 1400px;
    margin-left: auto;
    margin-right: auto;
}


.wayfarer-builder-page > h1 {
    margin-bottom: 2px;
}


.wayfarer-builder-page > h1 + p {
    margin-top: 0;
    color: var(--wf-muted);
}


.wayfarer-builder-page > nav {
    margin-top: 18px;
    margin-bottom: 18px;
    padding: 10px 14px;
    background: var(--wf-surface);
    border: 1px solid var(--wf-border);
    border-radius: var(--wf-radius);
    box-shadow: var(--wf-shadow);
}


.wayfarer-builder-page > nav a,
.wayfarer-builder-page > nav strong {
    display: inline-block;
    margin-right: 18px;
}


.wayfarer-builder-page > hr {
    display: none;
}


/* ------------------------------------------------------------------
   MASTER / DETAIL
------------------------------------------------------------------ */

.builder-workspace {
    display: grid;
    grid-template-columns: minmax(260px, 340px) minmax(0, 1fr);
    gap: 18px;
    align-items: start;
}


.builder-collection-pane,
.builder-editor-pane {
    background: var(--wf-surface);
    border: 1px solid var(--wf-border);
    border-radius: var(--wf-radius);
    box-shadow: var(--wf-shadow);
}


.builder-collection-pane {
    position: sticky;
    top: 18px;
    max-height: calc(100vh - 36px);
    overflow: hidden;
}


.builder-collection-toolbar {
    padding: 14px;
    border-bottom: 1px solid var(--wf-border);
    background: var(--wf-surface-soft);
}


.builder-new-object {
    display: inline-block;
    padding: 8px 11px;
    border: 1px solid var(--wf-border-strong);
    border-radius: 6px;
    background: var(--wf-surface);
    text-decoration: none;
    font-weight: 600;
}


.builder-collection-scroll {
    overflow: auto;
    max-height: calc(100vh - 92px);
    padding: 14px;
}


.builder-collection-scroll > h2 {
    margin-top: 0;
    margin-bottom: 12px;
    font-size: 1.15rem;
}


.builder-collection-scroll ul {
    margin: 0;
    padding: 0;
    list-style: none;
}


.builder-collection-scroll li + li {
    margin-top: 4px;
}


.builder-collection-scroll li a {
    display: block;
    padding: 8px 9px;
    border-radius: 5px;
    text-decoration: none;
}


.builder-collection-scroll li a:hover {
    background: var(--wf-accent-soft);
}


.builder-collection-scroll table {
    width: 100%;
    border-collapse: collapse;
    font-size: 0.88rem;
}


.builder-collection-scroll th,
.builder-collection-scroll td {
    padding: 7px 6px;
    border: 1px solid var(--wf-border);
    text-align: left;
    vertical-align: top;
}


.builder-collection-scroll th button {
    border: 0;
    padding: 0;
    background: transparent;
    font: inherit;
    font-weight: 600;
    cursor: pointer;
}


.builder-editor-pane {
    min-width: 0;
    padding: 20px 24px 24px;
}


.builder-editor-pane > h2 {
    margin-top: 0;
    margin-bottom: 14px;
}


/* WAYFARER_OBJECT_CONTEXT_HEADING_V34 */
.builder-object-heading {
    display: flex;
    flex-wrap: wrap;
    align-items: baseline;
    gap: 0 8px;
}

.builder-object-context {
    color: var(--wf-muted);
    font-weight: 600;
}

.builder-object-context[hidden] {
    display: none;
}

.builder-object-context-separator {
    margin-right: 8px;
    color: var(--wf-border-strong);
}


/* ------------------------------------------------------------------
   TABBED OBJECT EDITOR
------------------------------------------------------------------ */

.builder-object-form {
    margin: 0;
}


.builder-editor-tabs {
    display: flex;
    gap: 4px;
    margin: 0 0 20px;
    padding: 0;
    border-bottom: 1px solid var(--wf-border);
}


.builder-editor-tab {
    position: relative;
    bottom: -1px;
    padding: 9px 14px;
    border: 1px solid transparent;
    border-bottom: 1px solid var(--wf-border);
    background: transparent;
    color: var(--wf-muted);
    font: inherit;
    font-weight: 600;
    cursor: pointer;
}


.builder-editor-tab:hover {
    color: var(--wf-text);
    background: var(--wf-surface-soft);
}


.builder-editor-tab.is-active {
    color: var(--wf-accent);
    background: var(--wf-surface);
    border-color:
        var(--wf-border)
        var(--wf-border)
        var(--wf-surface);
    border-radius: 6px 6px 0 0;
}


.builder-tab-panel[hidden] {
    display: none !important;
}


.builder-tab-panel > p:first-child {
    margin-top: 0;
}


/* ------------------------------------------------------------------
   EXISTING FIELD CONTROLS
------------------------------------------------------------------ */

.builder-editor-pane label {
    font-weight: 600;
}


.builder-editor-pane small {
    color: var(--wf-muted);
    font-weight: 400;
}


.builder-editor-pane input[type="text"],
.builder-editor-pane input[type="number"],
.builder-editor-pane input[type="file"],
.builder-editor-pane select,
.builder-editor-pane textarea {
    box-sizing: border-box;
    max-width: 100%;
    margin-top: 4px;
    padding: 7px 8px;
    border: 1px solid var(--wf-border-strong);
    border-radius: 5px;
    background: var(--wf-surface);
    color: var(--wf-text);
    font: inherit;
}


.builder-editor-pane input[type="text"],
.builder-editor-pane textarea {
    width: min(100%, 720px);
}


.builder-editor-pane textarea {
    resize: vertical;
}


.builder-editor-pane fieldset {
    margin: 0 0 16px;
    padding: 14px 16px;
    border: 1px solid var(--wf-border);
    border-radius: 7px;
}


.builder-editor-pane legend {
    padding: 0 6px;
}


.builder-editor-pane table {
    max-width: 100%;
    border-collapse: collapse;
}


.builder-editor-pane th,
.builder-editor-pane td {
    padding: 7px;
}


/* System settings stay visually inside Basics. */
.builder-editor-pane [data-system-trait-settings] {
    margin: 16px 0;
    padding: 14px 16px;
    border: 1px solid var(--wf-border);
    border-radius: 7px;
    background: var(--wf-surface-soft);
}


.builder-editor-pane [data-system-trait-settings] h3 {
    margin-top: 0;
}


/* ------------------------------------------------------------------
   SAVE / DELETE
------------------------------------------------------------------ */

.builder-save-bar {
    display: flex;
    justify-content: flex-end;
    margin: 22px -24px -24px;
    padding: 14px 24px;
    border-top: 1px solid var(--wf-border);
    background: var(--wf-surface-soft);
    border-radius: 0 0 var(--wf-radius) var(--wf-radius);
}


.builder-save-bar button {
    padding: 9px 16px;
    border: 1px solid #214b86;
    border-radius: 6px;
    background: var(--wf-accent);
    color: #fff;
    font: inherit;
    font-weight: 600;
    cursor: pointer;
}


.builder-editor-pane [data-builder-delete-form] {
    margin-top: 28px;
    padding: 16px;
    border: 1px solid #e8b8be;
    border-radius: 7px;
    background: var(--wf-danger-soft);
}


.builder-editor-pane [data-builder-delete-form] h3 {
    margin-top: 0;
    color: var(--wf-danger);
}


.builder-editor-pane [data-builder-delete-form] button {
    padding: 8px 12px;
    border: 1px solid var(--wf-danger);
    border-radius: 5px;
    background: #fff;
    color: var(--wf-danger) !important;
    font: inherit;
    font-weight: 600;
    cursor: pointer;
}


.builder-back-link {
    margin-top: 18px;
}


/* ------------------------------------------------------------------
   RESPONSIVE
------------------------------------------------------------------ */

@media (max-width: 900px) {

    .wayfarer-builder-page {
        padding: 14px;
    }

    .builder-workspace {
        grid-template-columns: 1fr;
    }

    .builder-collection-pane {
        position: static;
        max-height: none;
    }

    .builder-collection-scroll {
        max-height: 300px;
    }

    .builder-editor-pane {
        padding: 18px;
    }

    .builder-save-bar {
        margin-left: -18px;
        margin-right: -18px;
        margin-bottom: -18px;
        padding-left: 18px;
        padding-right: 18px;
    }

}


@media (max-width: 560px) {

    .builder-editor-tabs {
        overflow-x: auto;
    }

    .builder-editor-tab {
        white-space: nowrap;
    }

}


/*
|--------------------------------------------------------------------------
| REGION TICK EFFECTS v18
|--------------------------------------------------------------------------
*/

.builder-tick-effect-row {
    display: grid;
    grid-template-columns:
        minmax(220px, 2fr)
        minmax(130px, 1fr)
        minmax(110px, 1fr)
        auto;
    gap: 12px;
    align-items: end;
    margin: 0 0 12px;
    padding: 14px;
    border: 1px solid var(--wf-border);
    border-radius: 7px;
    background: var(--wf-surface-soft);
}

.builder-tick-effect-row > p {
    margin: 0;
}

.builder-tick-effect-row select,
.builder-tick-effect-row input {
    width: 100%;
    box-sizing: border-box;
}

.builder-tick-effect-remove {
    align-self: end;
}

@media (max-width: 760px) {

    .builder-tick-effect-row {
        grid-template-columns: 1fr;
    }

}

/*
|--------------------------------------------------------------------------
| TICK EFFECT RESULT BRANCHES v28
|--------------------------------------------------------------------------
| WAYFARER_TICK_EFFECT_BRANCHES_V28
*/

.builder-tick-effect-row {
    display: block;
    margin: 0 0 16px;
    padding: 16px;
}

.builder-tick-effect-header {
    display: grid;
    grid-template-columns: minmax(260px, 1fr) auto;
    gap: 16px;
    align-items: end;
    margin-bottom: 16px;
}

.builder-tick-effect-target select {
    display: block;
    width: 100%;
    margin-top: 6px;
}

.builder-tick-result-list {
    display: grid;
    gap: 12px;
}

.builder-tick-result-branch {
    padding: 14px;
    border: 1px solid var(--wf-border);
    border-radius: 7px;
    background: var(--wf-surface);
}

.builder-tick-result-branch.is-otherwise {
    background: var(--wf-surface-soft);
}

.builder-tick-result-heading {
    display: flex;
    justify-content: space-between;
    gap: 12px;
    align-items: center;
    margin-bottom: 12px;
}

.builder-tick-result-order {
    display: flex;
    gap: 6px;
    align-items: center;
}

.builder-tick-result-condition {
    margin-bottom: 10px;
}

.builder-tick-result-then {
    margin: 10px 0 8px;
}

.builder-tick-result-fields {
    display: grid;
    grid-template-columns:
        minmax(150px, 0.8fr)
        minmax(120px, 0.7fr)
        minmax(120px, 0.7fr)
        minmax(180px, 1fr);
    gap: 12px;
    align-items: end;
}

.builder-tick-result-fields select,
.builder-tick-result-fields input {
    display: block;
    width: 100%;
    margin-top: 6px;
}

.builder-tick-result-actions {
    display: flex;
    gap: 8px;
    flex-wrap: wrap;
    margin-top: 12px;
}

.builder-condition-group {
    padding: 10px;
    border: 1px solid var(--wf-border);
    border-radius: 6px;
    background: var(--wf-surface-soft);
}

.builder-condition-group-header,
.builder-condition-actions {
    display: flex;
    align-items: center;
    gap: 8px;
    flex-wrap: wrap;
}

.builder-condition-children {
    display: grid;
    gap: 8px;
    margin: 10px 0;
}

.builder-condition-row {
    display: grid;
    grid-template-columns:
        minmax(180px, 1.4fr)
        minmax(180px, 1fr)
        minmax(120px, 1fr)
        auto;
    gap: 8px;
    align-items: end;
}

.builder-condition-row select,
.builder-condition-row input,
.builder-condition-group-header select {
    width: 100%;
    box-sizing: border-box;
}

@media (max-width: 760px) {

    .builder-tick-effect-header,
    .builder-tick-result-fields,
    .builder-condition-row {
        grid-template-columns: 1fr;
    }

    .builder-tick-result-heading {
        align-items: flex-start;
        flex-direction: column;
    }
}

/* ------------------------------------------------------------------
   STARTING CHOICES
   WAYFARER_STARTING_CHOICES_V36
------------------------------------------------------------------ */

.builder-starting-choices-editor { margin-top: 24px; }

.builder-starting-choices-heading,
.builder-starting-choice-header,
.builder-starting-option-header,
.builder-starting-effects-heading {
    display: flex;
    align-items: flex-start;
    justify-content: space-between;
    gap: 12px;
}

.builder-starting-choices-heading h3 { margin: 0 0 4px; }
.builder-starting-choices-heading p { margin: 0; }

.builder-starting-choice {
    margin-top: 16px;
    padding: 16px;
    border: 1px solid var(--wf-border);
    border-radius: var(--wf-radius);
    background: var(--wf-surface-soft);
}

.builder-starting-choice-fields {
    display: grid;
    grid-template-columns: minmax(0, 1fr) 140px;
    gap: 12px;
    margin-top: 14px;
}

.builder-starting-choice-fields label,
.builder-starting-option-fields label,
.builder-starting-effect label {
    display: grid;
    gap: 5px;
    font-weight: 600;
}

.builder-starting-choice-fields input,
.builder-starting-choice-fields select,
.builder-starting-option-fields input,
.builder-starting-option-fields textarea,
.builder-starting-effect input,
.builder-starting-effect select {
    width: 100%;
    font: inherit;
}

.builder-starting-options {
    display: grid;
    gap: 12px;
    margin: 16px 0 12px;
}

.builder-starting-option {
    padding: 14px;
    border: 1px solid var(--wf-border);
    border-radius: 7px;
    background: var(--wf-surface);
}

.builder-starting-option-fields {
    display: grid;
    grid-template-columns: minmax(180px, 0.7fr) minmax(260px, 1.3fr);
    gap: 12px;
    margin-top: 12px;
}

.builder-starting-effects {
    margin-top: 14px;
    padding-top: 12px;
    border-top: 1px solid var(--wf-border);
}

.builder-starting-effects-heading { margin-bottom: 8px; }
.builder-starting-effects-heading small { color: var(--wf-muted); }

.builder-starting-effect {
    display: grid;
    grid-template-columns:
        minmax(180px, 1.4fr)
        minmax(110px, 0.65fr)
        minmax(110px, 0.65fr)
        minmax(110px, 0.65fr)
        minmax(180px, 1fr)
        auto;
    gap: 10px;
    align-items: end;
    margin-bottom: 8px;
}

@media (max-width: 800px) {
    .builder-starting-choice-fields,
    .builder-starting-option-fields,
    .builder-starting-effect {
        grid-template-columns: 1fr;
    }
}


/* ------------------------------------------------------------------
   ONE-TIME EFFECTS
   WAYFARER_ONE_TIME_EFFECTS_EDITOR_V42
------------------------------------------------------------------ */

.builder-effects-panel > hr {
    margin: 28px 0;
    border: 0;
    border-top: 1px solid var(--wf-border, #d8dbe2);
}

.builder-effects-list {
    display: grid;
    gap: 10px;
    margin: 14px 0;
}

.builder-effect-row {
    display: grid;
    grid-template-columns:
        minmax(220px, 1.5fr)
        minmax(130px, 0.7fr)
        minmax(110px, 0.6fr)
        auto;
    gap: 10px;
    align-items: end;
    padding: 12px;
    border: 1px solid var(--wf-border, #d8dbe2);
    border-radius: 8px;
    background: #ffffff;
}

.builder-effect-row label {
    display: grid;
    gap: 5px;
}

.builder-effect-row select,
.builder-effect-row input {
    width: 100%;
}

.builder-effect-remove {
    align-self: end;
}

@media (max-width: 850px) {

    .builder-effect-row {
        grid-template-columns: 1fr;
    }

    .builder-effect-remove {
        justify-self: start;
    }
}


/* ------------------------------------------------------------------
   GENERALIZED EFFECTS
   WAYFARER_GENERALIZED_EFFECT_EDITOR_V43
------------------------------------------------------------------ */

/*
 * v42 displayed an Effect as one horizontal operation row. v43 Effects own
 * ordered result branches, so use the same card language as Tick Effects.
 */
.builder-effect-row {
    display: block;
    grid-template-columns: none;
    padding: 14px;
}

.builder-effect-row .builder-tick-effect-header {
    margin-bottom: 12px;
}

.builder-effect-value-fields {
    display: grid;
    grid-template-columns:
        minmax(120px, 0.75fr)
        minmax(120px, 0.75fr)
        minmax(120px, 0.75fr);
    gap: 10px;
    align-items: end;
}

.builder-effect-random-range {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 8px;
}

.builder-effect-random-range > label {
    display: grid;
    gap: 5px;
}

[data-effect-fixed-wrap][hidden],
[data-effect-random-wrap][hidden],
[data-effect-value-mode-wrap][hidden] {
    display: none !important;
}

/* WAYFARER_DATATYPE_TARGET_UI_V58 */
[data-condition-value-input][hidden],
[data-condition-value-select][hidden],
[data-starting-value-mode-wrap][hidden],
[data-starting-fixed-wrap][hidden],
[data-starting-random-wrap][hidden],
[data-starting-fixed-input][hidden],
[data-starting-fixed-choice][hidden],
[data-tick-value-mode-wrap][hidden],
[data-tick-branch-value-wrap][hidden],
[data-tick-random-wrap][hidden],
[data-tick-fixed-choice][hidden],
[data-effect-fixed-choice][hidden] {
    display: none !important;
}

@media (max-width: 850px) {

    .builder-effect-value-fields {
        grid-template-columns: 1fr;
    }

    .builder-effect-random-range {
        grid-template-columns: 1fr;
    }
}


/* ------------------------------------------------------------------
   STORYLET BRANCHES
   WAYFARER_STORYLET_BUILDER_V56
------------------------------------------------------------------ */

.builder-storylet-branches {
    max-width: 100%;
    overflow-x: auto;
}

.builder-storylet-branches table {
    width: 100%;
    border-collapse: collapse;
}

.builder-storylet-branches th,
.builder-storylet-branches td {
    padding: 9px 10px;
    border: 1px solid var(--wf-border);
    text-align: left;
    vertical-align: top;
}

.builder-storylet-branches th {
    background: var(--wf-surface-soft);
}

/* ------------------------------------------------------------------
   STATUS LIFECYCLE
   WAYFARER_STATUS_LIFECYCLE_UI_V88
------------------------------------------------------------------ */
.wayfarer-status-lifecycle-heading,
.wayfarer-status-stage-heading,
.wayfarer-status-outcomes-heading {
    display: flex;
    align-items: flex-start;
    justify-content: space-between;
    gap: 12px;
}

.wayfarer-status-lifecycle-heading h4,
.wayfarer-status-outcomes-heading strong {
    margin: 0;
}

.wayfarer-status-stage {
    margin-top: 16px;
    padding: 16px;
    border: 1px solid var(--wf-border);
    border-radius: 8px;
    background: var(--wf-surface-soft);
}

.wayfarer-status-stage-actions {
    display: flex;
    flex-wrap: wrap;
    gap: 6px;
}

.wayfarer-status-stage-fields,
.wayfarer-status-outcome-fields {
    display: grid;
    gap: 12px;
    margin-top: 14px;
}

.wayfarer-status-stage-fields {
    grid-template-columns: minmax(180px, 1fr) repeat(4, minmax(130px, 0.7fr));
}

.wayfarer-status-outcome-fields {
    grid-template-columns:
        minmax(180px, 1fr)
        minmax(90px, 0.45fr)
        minmax(210px, 1fr)
        minmax(150px, 0.7fr)
        minmax(220px, 1fr);
}

.wayfarer-status-stage-fields label,
.wayfarer-status-outcome-fields label {
    display: grid;
    gap: 5px;
}

.wayfarer-status-stage-fields input,
.wayfarer-status-stage-fields select,
.wayfarer-status-outcome-fields input,
.wayfarer-status-outcome-fields select {
    width: 100%;
}

.wayfarer-status-outcomes-heading {
    margin-top: 18px;
    padding-top: 14px;
    border-top: 1px solid var(--wf-border);
}

.wayfarer-status-outcomes-heading small {
    display: block;
    margin-top: 2px;
}

.wayfarer-status-outcome {
    margin-top: 10px;
    padding: 12px;
    border: 1px solid var(--wf-border);
    border-radius: 7px;
    background: var(--wf-surface);
}

.wayfarer-status-outcome > button {
    margin-top: 10px;
}

.wayfarer-status-lifecycle-note {
    margin-top: 18px;
}

@media (max-width: 1050px) {
    .wayfarer-status-stage-fields,
    .wayfarer-status-outcome-fields {
        grid-template-columns: 1fr 1fr;
    }
}

@media (max-width: 700px) {
    .wayfarer-status-lifecycle-heading,
    .wayfarer-status-stage-heading,
    .wayfarer-status-outcomes-heading {
        flex-direction: column;
    }

    .wayfarer-status-stage-fields,
    .wayfarer-status-outcome-fields {
        grid-template-columns: 1fr;
    }
}



==============================================================================
FILE: assets/css/hierarchical-targets.css
==============================================================================

/*
 * Wayfarer Hierarchical Target Picker
 * WAYFARER_HIERARCHICAL_TARGETS_V80
 * WAYFARER_HIERARCHICAL_LAYOUT_V81
 */

.wayfarer-hierarchy-picker {
    display: grid;
    grid-template-columns: repeat(3, minmax(0, 1fr));
    gap: 12px;
    width: 100%;
    min-width: 0;
    margin-top: 6px;
}

.wayfarer-hierarchy-level {
    min-width: 0;
}

.wayfarer-hierarchy-label {
    display: block;
    margin-bottom: 4px;
    font-weight: 600;
}

.wayfarer-hierarchy-search,
.wayfarer-hierarchy-select {
    box-sizing: border-box;
    width: 100%;
    min-width: 0;
}

.wayfarer-hierarchy-search {
    margin-bottom: 5px;
}

.wayfarer-hierarchy-level[hidden] {
    display: none !important;
}

/*
 * The canonical target select stays in the form so all existing save/runtime
 * behavior remains unchanged. V81 moves the generated hierarchy outside its
 * original label, then hides that now-redundant source label.
 */
.wayfarer-hierarchy-canonical,
.wayfarer-hierarchy-source-label {
    display: none !important;
}

/*
 * CONDITIONS
 *
 * Row 1: Type -> Target -> Property hierarchy.
 * Row 2: Comparison | Value | Remove.
 *
 * A hidden Value control (for Location anchors, etc.) naturally collapses out
 * of the second row without changing the underlying Condition shape.
 */
.builder-condition-row.has-wayfarer-hierarchy {
    display: grid !important;
    grid-template-columns:
        minmax(180px, 1fr)
        minmax(180px, 1fr)
        auto !important;
    gap: 12px !important;
    align-items: end !important;
}

.builder-condition-row.has-wayfarer-hierarchy > .wayfarer-hierarchy-picker {
    grid-column: 1 / -1;
    margin-top: 0;
}

.builder-condition-row.has-wayfarer-hierarchy > label:not(.wayfarer-hierarchy-source-label) {
    min-width: 0;
}

.builder-condition-row.has-wayfarer-hierarchy > label:not(.wayfarer-hierarchy-source-label) > select,
.builder-condition-row.has-wayfarer-hierarchy > label:not(.wayfarer-hierarchy-source-label) > input {
    box-sizing: border-box;
    max-width: 100%;
}

.builder-condition-row.has-wayfarer-hierarchy > [data-remove-condition-node] {
    align-self: end;
}

/*
 * ONE-TIME EFFECTS / TICK EFFECTS
 *
 * The hierarchy gets the flexible column; Remove remains a compact action
 * column. This prevents the three hierarchy levels from fighting the old
 * single-select header width.
 */
.builder-tick-effect-header.has-wayfarer-hierarchy {
    display: grid !important;
    grid-template-columns: minmax(0, 1fr) auto !important;
    gap: 12px !important;
    align-items: end !important;
}

.builder-tick-effect-header.has-wayfarer-hierarchy > .wayfarer-hierarchy-picker {
    grid-column: 1;
    margin-top: 0;
}

.builder-tick-effect-header.has-wayfarer-hierarchy > [data-remove-effect],
.builder-tick-effect-header.has-wayfarer-hierarchy > [data-remove-tick-effect] {
    grid-column: 2;
    align-self: end;
}

@media (max-width: 900px) {
    .wayfarer-hierarchy-picker {
        grid-template-columns: 1fr;
    }

    .builder-condition-row.has-wayfarer-hierarchy,
    .builder-tick-effect-header.has-wayfarer-hierarchy {
        grid-template-columns: 1fr !important;
    }

    .builder-condition-row.has-wayfarer-hierarchy > .wayfarer-hierarchy-picker,
    .builder-tick-effect-header.has-wayfarer-hierarchy > .wayfarer-hierarchy-picker,
    .builder-tick-effect-header.has-wayfarer-hierarchy > [data-remove-effect],
    .builder-tick-effect-header.has-wayfarer-hierarchy > [data-remove-tick-effect] {
        grid-column: 1;
    }
}


==============================================================================
FILE: assets/css/status-subject-effects.css
==============================================================================

/* WAYFARER_STATUS_SUBJECT_EFFECTS_UI_V89 */
.wayfarer-status-stage-effects,
.wayfarer-status-outcome-effects {
    margin-top: 16px;
}

.wayfarer-status-effects-heading {
    display: flex;
    align-items: flex-start;
    justify-content: space-between;
    gap: 12px;
    margin-top: 14px;
    padding-top: 12px;
    border-top: 1px solid var(--wf-border);
}

.wayfarer-status-effects-heading small {
    display: block;
    margin-top: 2px;
}

.wayfarer-status-effect {
    display: grid;
    grid-template-columns:
        minmax(170px, 1fr)
        minmax(170px, 1fr)
        minmax(120px, 0.7fr)
        minmax(120px, 0.7fr)
        minmax(110px, 0.65fr)
        minmax(110px, 0.65fr)
        auto;
    gap: 10px;
    align-items: end;
    margin-top: 10px;
    padding: 11px;
    border: 1px solid var(--wf-border);
    border-radius: 7px;
    background: #fff;
}

.wayfarer-status-effect label {
    display: grid;
    gap: 5px;
    min-width: 0;
}

.wayfarer-status-effect select,
.wayfarer-status-effect input {
    width: 100%;
    min-width: 0;
}

.wayfarer-status-effect-inline-number {
    display: grid;
    grid-template-columns: minmax(70px, 1fr) auto;
    gap: 6px;
    align-items: center;
}

.wayfarer-status-effect > button {
    align-self: end;
}

@media (max-width: 1150px) {
    .wayfarer-status-effect {
        grid-template-columns: 1fr 1fr 1fr;
    }
}

@media (max-width: 700px) {
    .wayfarer-status-effects-heading {
        flex-direction: column;
    }

    .wayfarer-status-effect {
        grid-template-columns: 1fr;
    }
}



==============================================================================
FILE: assets/js/builder.js
==============================================================================

const wayfarerConditionData = window.wayfarerConditionData || {};

function updateConditionalConfigFields() {
    document
        .querySelectorAll('[data-config-field]')
        .forEach(function (container) {
            const relationshipName =
                container.dataset.conditionRelationship;

            const requiredValue =
                container.dataset.conditionEquals;

            if (!relationshipName) {
                container.style.display = '';
                return;
            }

            const relationshipSelect =
                document.querySelector(
                    '[data-relationship="' +
                    relationshipName +
                    '"]'
                );

            if (!relationshipSelect) {
                container.style.display = 'none';
                return;
            }

            const selectedId = relationshipSelect.value;
            const actualValue =
                wayfarerConditionData[relationshipName]?.[selectedId];

            container.style.display =
                actualValue === requiredValue
                    ? ''
                    : 'none';
        });
}


document
    .querySelectorAll('[data-relationship]')
    .forEach(function (select) {
        select.addEventListener(
            'change',
            updateConditionalConfigFields
        );
    });


// ================================================================
// SYSTEM TRAIT GROUPS
// ================================================================

function updateSystemTraitGroups(container) {
    const selectorField =
        container.dataset.selectorField;

    if (!selectorField) {
        return;
    }

    const selector =
        document.querySelector(
            '[name="' + selectorField + '"]'
        );

    if (!selector) {
        return;
    }

    const selectedGroup = selector.value;

    container
        .querySelectorAll('[data-system-trait-group]')
        .forEach(function (group) {
            const active =
                group.dataset.systemTraitGroup === selectedGroup;

            group.style.display =
                active ? '' : 'none';

            group
                .querySelectorAll('input, select, textarea')
                .forEach(function (input) {
                    input.disabled = !active;
                });
        });
}


document
    .querySelectorAll('[data-system-trait-settings]')
    .forEach(function (container) {
        const selectorField =
            container.dataset.selectorField;

        const selector =
            selectorField
                ? document.querySelector(
                    '[name="' + selectorField + '"]'
                )
                : null;

        if (selector) {
            selector.addEventListener(
                'change',
                function () {
                    updateSystemTraitGroups(container);
                }
            );
        }

        updateSystemTraitGroups(container);
    });


// ================================================================
// COLLECTION SORTING
// ================================================================

document
    .querySelectorAll('[data-sort-column]')
    .forEach(function (button) {
        button.addEventListener('click', function () {
            const table =
                button.closest('[data-collection-table]');

            if (!table) {
                return;
            }

            const tbody = table.querySelector('tbody');
            const columnName = button.dataset.sortColumn;
            const sortType = button.dataset.sortType || 'text';
            const currentDirection =
                button.dataset.sortDirection || 'none';

            const nextDirection =
                currentDirection === 'asc'
                    ? 'desc'
                    : 'asc';

            table
                .querySelectorAll('[data-sort-column]')
                .forEach(function (otherButton) {
                    otherButton.dataset.sortDirection = 'none';
                });

            button.dataset.sortDirection = nextDirection;

            const rows =
                Array.from(tbody.querySelectorAll('tr'));

            rows.sort(function (a, b) {
                const aCell =
                    a.querySelector(
                        '[data-column="' +
                        columnName +
                        '"]'
                    );

                const bCell =
                    b.querySelector(
                        '[data-column="' +
                        columnName +
                        '"]'
                    );

                const aValue = aCell?.dataset.sortValue ?? '';
                const bValue = bCell?.dataset.sortValue ?? '';

                let comparison = 0;

                if (sortType === 'number') {
                    const aNumber =
                        aValue === ''
                            ? Number.POSITIVE_INFINITY
                            : Number(aValue);

                    const bNumber =
                        bValue === ''
                            ? Number.POSITIVE_INFINITY
                            : Number(bValue);

                    comparison = aNumber - bNumber;
                } else {
                    comparison =
                        aValue.localeCompare(
                            bValue,
                            undefined,
                            {
                                numeric: true,
                                sensitivity: 'base'
                            }
                        );
                }

                return nextDirection === 'asc'
                    ? comparison
                    : -comparison;
            });

            rows.forEach(function (row) {
                tbody.appendChild(row);
            });
        });
    });


updateConditionalConfigFields();


// ================================================================
// MEDIA LIBRARY CONTROLS
// ================================================================

function updateBuilderMediaSlot(slotContainer) {

    const checkedAction =
        slotContainer.querySelector(
            'input[type="radio"][name^="media_action"]:checked'
        );

    const action =
        checkedAction
            ? checkedAction.value
            : 'none';

    const existingSelect =
        slotContainer.querySelector(
            '[data-media-existing]'
        );

    if (existingSelect) {
        existingSelect.disabled =
            action !== 'existing';
    }

    slotContainer
        .querySelectorAll(
            '[data-media-upload-fields] input'
        )
        .forEach(function (input) {
            input.disabled =
                action !== 'upload';
        });
}


document
    .querySelectorAll('[data-media-slot]')
    .forEach(function (slotContainer) {

        slotContainer
            .querySelectorAll(
                'input[type="radio"][name^="media_action"]'
            )
            .forEach(function (radio) {

                radio.addEventListener(
                    'change',
                    function () {
                        updateBuilderMediaSlot(
                            slotContainer
                        );
                    }
                );
            });

        updateBuilderMediaSlot(
            slotContainer
        );
    });


// ================================================================
// AUTHORED OBJECT CONTEXT HEADING
// WAYFARER_OBJECT_CONTEXT_HEADING_V34
// ================================================================

function initializeBuilderObjectContextHeading() {

    const editor =
        document.querySelector(
            '[data-builder-editor]'
        );

    if (!editor) {
        return;
    }

    const heading =
        editor.querySelector(
            '[data-builder-object-heading]'
        );

    if (!heading) {
        return;
    }

    const fieldName =
        heading.dataset.builderObjectLabelField ||
        'name';

    const form =
        editor.querySelector(
            'form'
        );

    if (!form) {
        return;
    }

    const field =
        Array
            .from(
                form.elements
            )
            .find(function (element) {
                return (
                    element &&
                    element.name === fieldName
                );
            });

    if (!field) {
        return;
    }

    const context =
        heading.querySelector(
            '[data-builder-object-context]'
        );

    const label =
        heading.querySelector(
            '[data-builder-object-context-label]'
        );

    if (!context || !label) {
        return;
    }

    function refreshContextHeading() {

        const value =
            String(
                field.value || ''
            ).trim();

        label.textContent =
            value;

        context.hidden =
            value === '';
    }

    field.addEventListener(
        'input',
        refreshContextHeading
    );

    field.addEventListener(
        'change',
        refreshContextHeading
    );

    refreshContextHeading();
}


initializeBuilderObjectContextHeading();

// ================================================================
// AUTHORED OBJECT EDITOR TABS
// ================================================================

function initializeBuilderEditorTabs() {

    const editor =
        document.querySelector(
            '[data-builder-editor]'
        );

    if (!editor) {
        return;
    }

    /*
     * The editor component has one primary save form. The separate delete
     * form, when present, lives later in the editor pane and is deliberately
     * left outside the tab system.
     */
    const form =
        Array
            .from(editor.children)
            .find(function (child) {
                return child.tagName === 'FORM';
            });

    if (
        !form ||
        form.dataset.builderTabbed === '1'
    ) {
        return;
    }

    form.dataset.builderTabbed = '1';
    form.classList.add(
        'builder-object-form'
    );

    /*
     * WAYFARER_ACTIVE_TAB_V20
     *
     * Persist the selected editor tab through POST/redirect/reload.
     */
    const activeTabInput =
        document.createElement(
            'input'
        );

    activeTabInput.type =
        'hidden';

    activeTabInput.name =
        'active_tab';

    const requestedTab =
        new URLSearchParams(
            window.location.search
        ).get(
            'tab'
        ) || 'basics';

    activeTabInput.value =
        requestedTab;

    form.appendChild(
        activeTabInput
    );

    const originalChildren =
        Array.from(
            form.children
        );

    const panels = {
        basics:
            document.createElement('div'),

        media:
            document.createElement('div'),

        traits:
            document.createElement('div'),

        /* WAYFARER_CONDITIONS_PANEL_V45_1 */
        conditions:
            document.createElement('div'),

        /* WAYFARER_LINEAR_TRAVEL_TAB_V72 */
        travel:
            document.createElement('div'),

        /* WAYFARER_STATUS_LIFECYCLE_TAB_V88 */
        progression:
            document.createElement('div'),

        tick_effects:
            document.createElement('div'),

        /* WAYFARER_STORYLET_BUILDER_V56 */
        /* WAYFARER_STORYLET_BRANCH_PANEL_KEY_V57 */
        branches:
            document.createElement('div')

    };

    panels.basics.className =
        'builder-tab-panel';

    panels.media.className =
        'builder-tab-panel';

    panels.traits.className =
        'builder-tab-panel';

    panels.conditions.className =
        'builder-tab-panel';

    panels.travel.className =
        'builder-tab-panel';

    panels.progression.className =
        'builder-tab-panel';

    panels.branches.className =
        'builder-tab-panel';

    panels.basics.dataset.builderPanel =
        'basics';

    panels.media.dataset.builderPanel =
        'media';

    panels.traits.dataset.builderPanel =
        'traits';

    panels.conditions.dataset.builderPanel =
        'conditions';

    panels.travel.dataset.builderPanel =
        'travel';

    panels.progression.dataset.builderPanel =
        'progression';

    panels.branches.dataset.builderPanel =
        'branches';

    panels.tick_effects.className =
        'builder-tab-panel';

    panels.tick_effects.dataset.builderPanel =
        'tick_effects';

    let section =
        'basics';

    let saveContainer =
        null;

    let hasMedia =
        false;

    let hasTraits =
        false;

    let hasConditions =
        false;

    let hasTravel =
        false;

    let hasProgression =
        false;

    let hasTickEffects =
        false;

    let hasBranches =
        false;

    originalChildren.forEach(
        function (child) {

            /*
             * Keep hidden record identifiers directly in the form.
             */
            if (
                child.tagName === 'INPUT' &&
                child.type === 'hidden'
            ) {
                return;
            }

            /*
             * Save becomes a stable footer beneath the tab panels.
             */
            const submitButton =
                child.querySelector
                    ? child.querySelector(
                        'button[type="submit"], input[type="submit"]'
                    )
                    : null;

            if (submitButton) {
                saveContainer =
                    child;

                return;
            }

            /*
             * Ignore the separator immediately before a tab heading.
             * Other HR elements are harmless but unnecessary inside the
             * cleaned-up editor.
             */
            if (child.tagName === 'HR') {
                child.remove();
                return;
            }

            if (child.tagName === 'H3') {

                const heading =
                    child.textContent
                        .trim()
                        .toLowerCase();

                if (heading === 'media') {
                    section =
                        'media';

                    hasMedia =
                        true;

                    child.remove();
                    return;
                }

                if (heading === 'traits') {
                    section =
                        'traits';

                    hasTraits =
                        true;

                    child.remove();
                    return;
                }
            }

            /*
             * WAYFARER_CONDITIONS_PANEL_V45_1
             *
             * Conditions answer whether an authored object is eligible;
             * Effects answer what changes when it triggers.
             */
            if (
                child.hasAttribute &&
                child.hasAttribute(
                    'data-builder-conditions-panel'
                )
            ) {
                section =
                    'conditions';

                hasConditions =
                    true;
            }


            /* WAYFARER_LINEAR_TRAVEL_TAB_V72 */
            if (
                child.hasAttribute &&
                child.hasAttribute(
                    'data-builder-travel-panel'
                )
            ) {
                section =
                    'travel';

                hasTravel =
                    true;
            }

            /* WAYFARER_STATUS_LIFECYCLE_TAB_V88 */
            if (
                child.hasAttribute &&
                child.hasAttribute(
                    'data-builder-status-lifecycle'
                )
            ) {
                section =
                    'progression';

                hasProgression =
                    true;
            }

            /*
             * WAYFARER_ONE_TIME_EFFECTS_EDITOR_V42
             *
             * Location Effects and Tick Effects share one Effects panel.
             */
            if (
                child.hasAttribute &&
                (
                    child.hasAttribute(
                        'data-builder-effects-panel'
                    ) ||
                    child.hasAttribute(
                        'data-builder-tick-effects'
                    )
                )
            ) {
                section =
                    'tick_effects';

                hasTickEffects =
                    true;
            }

            /* WAYFARER_STORYLET_BRANCHES_PANEL_V56 */
            if (
                child.hasAttribute &&
                child.hasAttribute(
                    'data-builder-branches-panel'
                )
            ) {
                section =
                    'branches';

                hasBranches =
                    true;
            }
            /*
             * WAYFARER_LINEAR_TRAVEL_TAB_V72
             *
             * Distance Label is existing Region travel configuration, so move
             * it into the Travel tab when that tab exists. Other config fields
             * retain the original Basics behavior.
             */
            if (
                child.hasAttribute &&
                child.hasAttribute(
                    'data-config-field'
                )
            ) {
                const configFieldName =
                    child.dataset.configField || '';

                const hasTravelEditor =
                    !!form.querySelector(
                        '[data-builder-travel-panel]'
                    );

                if (
                    configFieldName === 'distance_label' &&
                    hasTravelEditor
                ) {
                    section =
                        'travel';

                    hasTravel =
                        true;
                } else {
                    section =
                        'basics';
                }
            }

            /* Keep the existing Region HUD in Basics. */
            if (
                child.hasAttribute &&
                child.hasAttribute(
                    'data-region-hud-editor'
                )
            ) {
                section =
                    'basics';
            }

            /*
             * A Media fieldset is definitive even if future markup changes
             * around the Media heading.
             */
            if (
                child.hasAttribute &&
                child.hasAttribute(
                    'data-media-slot'
                )
            ) {
                section =
                    'media';

                hasMedia =
                    true;
            }

            panels[section]
                .appendChild(
                    child
                );
        }
    );

    /*
     * If Traits exist, anything moved after the Traits heading belongs there.
     * System traits do not use that heading and therefore stay in Basics.
     */
    if (
        panels.traits.children.length > 0
    ) {
        hasTraits =
            true;
    }

    if (
        panels.media.children.length > 0
    ) {
        hasMedia =
            true;
    }

    if (
        panels.conditions.children.length > 0
    ) {
        hasConditions =
            true;
    }

    if (
        panels.travel.children.length > 0
    ) {
        hasTravel =
            true;
    }

    if (
        panels.progression.children.length > 0
    ) {
        hasProgression =
            true;
    }

    if (
        panels.tick_effects.children.length > 0
    ) {
        hasTickEffects =
            true;
    }

    if (
        panels.branches.children.length > 0
    ) {
        hasBranches =
            true;
    }

    const tabBar =
        document.createElement(
            'div'
        );

    tabBar.className =
        'builder-editor-tabs';

    tabBar.setAttribute(
        'role',
        'tablist'
    );

    const availablePanels = [
        {
            key: 'basics',
            label: 'Basics',
            show: true
        },
        {
            key: 'media',
            label: 'Media',
            show: hasMedia
        },
        {
            key: 'traits',
            label: 'Traits',
            show: hasTraits
        },
        {
            key: 'travel',
            label: 'Travel',
            show: hasTravel
        },
        {
            key: 'progression',
            label: 'Progression',
            show: hasProgression
        },
        {
            key: 'conditions',
            label: 'Conditions',
            show: hasConditions
        },
        {
            key: 'tick_effects',
            label: 'Effects',
            show: hasTickEffects
        },
        {
            key: 'branches',
            label: 'Branches',
            show: hasBranches
        }
    ].filter(
        function (item) {
            return item.show;
        }
    );

    function activatePanel(panelKey) {

        activeTabInput.value =
            panelKey;

        tabBar
            .querySelectorAll(
                '[data-builder-tab]'
            )
            .forEach(
                function (button) {

                    const active =
                        button.dataset.builderTab ===
                        panelKey;

                    button.classList.toggle(
                        'is-active',
                        active
                    );

                    button.setAttribute(
                        'aria-selected',
                        active
                            ? 'true'
                            : 'false'
                    );
                }
            );

        Object
            .entries(panels)
            .forEach(
                function (entry) {

                    const key =
                        entry[0];

                    const panel =
                        entry[1];

                    panel.hidden =
                        key !== panelKey;
                }
            );
    }

    availablePanels.forEach(
        function (item) {

            const button =
                document.createElement(
                    'button'
                );

            button.type =
                'button';

            button.className =
                'builder-editor-tab';

            button.dataset.builderTab =
                item.key;

            button.setAttribute(
                'role',
                'tab'
            );

            button.textContent =
                item.label;

            button.addEventListener(
                'click',
                function () {
                    activatePanel(
                        item.key
                    );
                }
            );

            tabBar.appendChild(
                button
            );
        }
    );

    /*
     * Insert the new structure after hidden inputs so all form fields remain
     * part of the same form and submit exactly as before.
     */
    form.appendChild(
        tabBar
    );

    availablePanels.forEach(
        function (item) {
            form.appendChild(
                panels[item.key]
            );
        }
    );

    if (saveContainer) {

        saveContainer.classList.add(
            'builder-save-bar'
        );

        form.appendChild(
            saveContainer
        );
    }

    const initialPanelKey =
        availablePanels.some(
            function (item) {
                return item.key === requestedTab;
            }
        )
            ? requestedTab
            : 'basics';

    activatePanel(
        initialPanelKey
    );
}


initializeBuilderEditorTabs();



// ================================================================
// SHARED GAMEPLAY TICK EFFECTS CONTROLS v25
// WAYFARER_GAMEPLAY_MODULAR_V25
// ================================================================

function initializeTickEffects() {

    const editor =
        document.querySelector(
            '[data-builder-editor]'
        );

    if (!editor) {
        return;
    }

    const wrapper =
        editor.querySelector(
            '[data-builder-tick-effects]'
        );

    if (!wrapper) {
        return;
    }

    if (
        wrapper.dataset.tickEffectsReady ===
        '1'
    ) {
        return;
    }

    wrapper.dataset.tickEffectsReady =
        '1';


    // ------------------------------------------------------------
    // ROW ADD / REMOVE
    // ------------------------------------------------------------

    const list =
        wrapper.querySelector(
            '[data-tick-effects-list]'
        );

    const addButton =
        wrapper.querySelector(
            '[data-add-tick-effect]'
        );

    const template =
        wrapper.querySelector(
            '[data-tick-effect-template]'
        );

    let nextIndex = 0;

    wrapper
        .querySelectorAll(
            '[data-tick-effect-row]'
        )
        .forEach(
            function (row) {

                const index =
                    Number(
                        row.dataset.tickIndex
                    );

                if (
                    Number.isFinite(index) &&
                    index >= nextIndex
                ) {
                    nextIndex =
                        index + 1;
                }
            }
        );


    function updateLinearTargetAvailability() {

        const navigationSelect =
            editor.querySelector(
                'select[name="navigation_type"]'
            );

        const navigationType =
            navigationSelect
                ? navigationSelect.value
                : wrapper.dataset.navigationType;

        const linear =
            navigationType ===
            'linear';

        wrapper
            .querySelectorAll(
                '[data-linear-navigation-target]'
            )
            .forEach(
                function (option) {

                    option.disabled =
                        !linear;
                }
            );


        if (!linear) {

            wrapper
                .querySelectorAll(
                    '[data-tick-effect-target]'
                )
                .forEach(
                    function (select) {

                        if (
                            select.value ===
                            'navigation:position'
                        ) {
                            select.value =
                                '';
                        }
                    }
                );
        }
    }


    if (
        addButton &&
        list &&
        template
    ) {

        addButton.addEventListener(
            'click',
            function () {

                const html =
                    template.innerHTML.replace(
                        /__INDEX__/g,
                        String(
                            nextIndex++
                        )
                    );

                const temporary =
                    document.createElement(
                        'div'
                    );

                temporary.innerHTML =
                    html.trim();

                const row =
                    temporary.firstElementChild;

                if (!row) {
                    return;
                }

                list.appendChild(
                    row
                );

                updateLinearTargetAvailability();
            }
        );
    }


    wrapper.addEventListener(
        'click',
        function (event) {

            const removeButton =
                event.target.closest(
                    '[data-remove-tick-effect]'
                );

            if (!removeButton) {
                return;
            }

            const row =
                removeButton.closest(
                    '[data-tick-effect-row]'
                );

            if (row) {
                row.remove();
            }
        }
    );


    const navigationSelect =
        editor.querySelector(
            'select[name="navigation_type"]'
        );

    if (navigationSelect) {

        navigationSelect.addEventListener(
            'change',
            updateLinearTargetAvailability
        );
    }

    updateLinearTargetAvailability();


    /*
     * WAYFARER_EMBEDDED_TICK_EFFECTS_V33
     *
     * Game Settings already owns a Gameplay tab. In embedded mode we keep
     * this shared editor exactly where PHP rendered it while retaining the
     * normal Tick Effect, condition, and result-branch controls.
     */
    if (
        wrapper.hasAttribute(
            'data-tick-effects-embedded'
        )
    ) {
        return;
    }


    // ------------------------------------------------------------
    // MOVE THE SECTION INTO ITS OWN BUILDER TAB
    // ------------------------------------------------------------

    const form =
        wrapper.closest(
            'form'
        );

    if (!form) {
        return;
    }

    const tabBar =
        form.querySelector(
            '.builder-editor-tabs'
        );

    if (!tabBar) {

        /*
         * Builder without the v10 tab layout:
         * leave the Tick Effects section inline.
         */
        return;
    }


    if (
        form.querySelector(
            '[data-builder-panel="tick_effects"]'
        )
    ) {
        return;
    }


    const panel =
        document.createElement(
            'div'
        );

    panel.className =
        'builder-tab-panel';

    panel.dataset.builderPanel =
        'tick_effects';

    panel.hidden =
        true;

    panel.appendChild(
        wrapper
    );


    const saveBar =
        form.querySelector(
            '.builder-save-bar'
        );

    if (saveBar) {

        form.insertBefore(
            panel,
            saveBar
        );

    } else {

        form.appendChild(
            panel
        );
    }


    const button =
        document.createElement(
            'button'
        );

    button.type =
        'button';

    button.className =
        'builder-editor-tab';

    button.dataset.builderTab =
        'tick_effects';

    button.setAttribute(
        'role',
        'tab'
    );

    button.setAttribute(
        'aria-selected',
        'false'
    );

    /* WAYFARER_GAMEPLAY_TAB_LABEL_V25_1 */
    button.textContent =
        'Effects';

    tabBar.appendChild(
        button
    );


    function activateTickEffectsTab() {

        tabBar
            .querySelectorAll(
                '[data-builder-tab]'
            )
            .forEach(
                function (tabButton) {

                    const active =
                        tabButton ===
                        button;

                    tabButton.classList.toggle(
                        'is-active',
                        active
                    );

                    tabButton.setAttribute(
                        'aria-selected',
                        active
                            ? 'true'
                            : 'false'
                    );
                }
            );


        form
            .querySelectorAll(
                '[data-builder-panel]'
            )
            .forEach(
                function (tabPanel) {

                    tabPanel.hidden =
                        tabPanel.dataset.builderPanel !==
                        'tick_effects';
                }
            );
    }


    button.addEventListener(
        'click',
        activateTickEffectsTab
    );


    /*
     * The original tab controller does not know about the panel added
     * afterward, so explicitly hide our panel whenever an original tab
     * is clicked.
     */
    tabBar
        .querySelectorAll(
            '[data-builder-tab]:not([data-builder-tab="tick_effects"])'
        )
        .forEach(
            function (originalButton) {

                originalButton.addEventListener(
                    'click',
                    function () {

                        panel.hidden =
                            true;

                        button.classList.remove(
                            'is-active'
                        );

                        button.setAttribute(
                            'aria-selected',
                            'false'
                        );
                    }
                );
            }
        );
}


// ================================================================
// SHARED ONE-TIME EFFECTS CONTROLS
// WAYFARER_ONE_TIME_EFFECTS_EDITOR_V42
// WAYFARER_GENERALIZED_EFFECT_EDITOR_V43
// ================================================================

function wayfarerEffectConditionTargets(
    wrapper
) {

    const targetJson =
        wrapper.querySelector(
            '[data-effect-condition-targets-json]'
        );

    if (!targetJson) {
        return {};
    }

    try {

        return JSON.parse(
            targetJson.textContent ||
            '{}'
        );

    } catch (error) {

        return {};
    }
}


/* WAYFARER_DATATYPE_EFFECT_UI_V58 */
function wayfarerEffectTargetCatalog(
    wrapper
) {

    const targetJson =
        wrapper
            ? wrapper.querySelector(
                '[data-effect-target-catalog-json]'
            )
            : null;

    if (!targetJson) {
        return {};
    }

    try {
        return JSON.parse(
            targetJson.textContent ||
            '{}'
        );
    } catch (error) {
        return {};
    }
}


function wayfarerEffectTargetDefinition(
    branch
) {

    const effectRow =
        branch
            ? branch.closest(
                '[data-effect-row]'
            )
            : null;

    const wrapper =
        effectRow
            ? effectRow.closest(
                '[data-builder-effects]'
            )
            : null;

    const targetSelect =
        effectRow
            ? effectRow.querySelector(
                '[data-effect-target]'
            )
            : null;

    const catalog =
        wayfarerEffectTargetCatalog(
            wrapper
        );

    return targetSelect
        ? (catalog[targetSelect.value] || {})
        : {};
}


function wayfarerEffectEnsureChoiceSelect(
    fixedWrap,
    numberInput
) {

    if (!fixedWrap || !numberInput) {
        return null;
    }

    let select =
        fixedWrap.querySelector(
            '[data-effect-fixed-choice]'
        );

    if (!select) {
        select =
            document.createElement(
                'select'
            );

        select.dataset.effectFixedChoice =
            '1';

        select.name =
            numberInput.name;

        select.hidden =
            true;

        select.disabled =
            true;

        fixedWrap.appendChild(
            select
        );
    }

    return select;
}


function wayfarerEffectBuildConditionEditor(
    host,
    name,
    targets
) {

    const editor =
        document.createElement(
            'div'
        );

    editor.className =
        'builder-condition-editor';

    editor.dataset.conditionEditor =
        '1';

    editor.appendChild(
        wayfarerConditionCreateGroup(
            name,
            targets,
            null,
            true
        )
    );

    host.replaceWith(
        editor
    );

    wayfarerConditionInitializeEditor(
        editor,
        targets
    );
}


function wayfarerEffectUpdateResultFields(
    branch
) {

    const operation =
        branch.querySelector(
            '[data-effect-branch-operation]'
        );

    const modeWrap =
        branch.querySelector(
            '[data-effect-value-mode-wrap]'
        );

    const mode =
        branch.querySelector(
            '[data-effect-value-mode]'
        );

    const fixedWrap =
        branch.querySelector(
            '[data-effect-fixed-wrap]'
        );

    const randomWrap =
        branch.querySelector(
            '[data-effect-random-wrap]'
        );

    if (!operation) {
        return;
    }

    const definition =
        wayfarerEffectTargetDefinition(
            branch
        );

    let dataType =
        String(
            definition.data_type ||
            definition.trait_type ||
            'number'
        ).toLowerCase();

    if (dataType === 'binary') {
        dataType = 'boolean';
    }

    const semanticType =
        String(
            definition.semantic_type ||
            'trait'
        );

    const allowedOperations =
        Array.isArray(
            definition.effect_operations
        ) &&
        definition.effect_operations.length
            ? definition.effect_operations
            : (
                dataType === 'number'
                    ? ['set', 'add', 'subtract']
                    : ['set']
            );

    const supportsRandom =
        Object.prototype.hasOwnProperty.call(
            definition,
            'supports_random'
        )
            ? Boolean(
                definition.supports_random
            )
            : dataType === 'number';

    const operationLabels = {
        set: 'Set',
        add:
            semanticType === 'item_quantity'
                ? 'Add'
                : 'Add',
        subtract:
            semanticType === 'item_quantity'
                ? 'Subtract'
                : 'Subtract',
        none: 'No Change'
    };

    const previousOperation =
        operation.value;

    const resultOperations =
        allowedOperations.concat(
            ['none']
        );

    operation.innerHTML =
        '';

    resultOperations.forEach(
        function (operationValue) {

            const option =
                document.createElement(
                    'option'
                );

            option.value =
                operationValue;

            option.textContent =
                operationLabels[operationValue] ||
                operationValue;

            operation.appendChild(
                option
            );
        }
    );

    operation.value =
        resultOperations.includes(
            previousOperation
        )
            ? previousOperation
            : allowedOperations[0];

    const noChange =
        operation.value ===
        'none';

    let valueMode =
        mode
            ? mode.value
            : 'fixed';

    if (!supportsRandom) {
        valueMode =
            'fixed';

        if (mode) {
            mode.value =
                'fixed';
        }
    }

    if (modeWrap) {
        modeWrap.hidden =
            noChange ||
            !supportsRandom;

        modeWrap
            .querySelectorAll(
                'select, input'
            )
            .forEach(
                function (field) {
                    field.disabled =
                        noChange ||
                        !supportsRandom;
                }
            );
    }

    const showFixed =
        !noChange &&
        (
            !supportsRandom ||
            valueMode === 'fixed'
        );

    if (fixedWrap) {
        fixedWrap.hidden =
            !showFixed;

        const numberInput =
            fixedWrap.querySelector(
                'input[name]'
            );

        const choiceSelect =
            wayfarerEffectEnsureChoiceSelect(
                fixedWrap,
                numberInput
            );

        const valueOptions =
            definition.value_options &&
            typeof definition.value_options === 'object'
                ? definition.value_options
                : null;

        if (
            showFixed &&
            valueOptions &&
            numberInput &&
            choiceSelect
        ) {

            const previousValue =
                choiceSelect.hidden
                    ? numberInput.value
                    : choiceSelect.value;

            choiceSelect.innerHTML =
                '';

            Object
                .entries(valueOptions)
                .forEach(
                    function (entry) {

                        const option =
                            document.createElement(
                                'option'
                            );

                        option.value =
                            entry[0];

                        option.textContent =
                            entry[1];

                        choiceSelect.appendChild(
                            option
                        );
                    }
                );

            if (
                Object.prototype.hasOwnProperty.call(
                    valueOptions,
                    String(previousValue)
                )
            ) {
                choiceSelect.value =
                    String(previousValue);
            }

            choiceSelect.hidden =
                false;

            choiceSelect.disabled =
                false;

            numberInput.hidden =
                true;

            numberInput.disabled =
                true;

        } else {

            if (
                choiceSelect &&
                numberInput &&
                !choiceSelect.hidden
            ) {
                numberInput.value =
                    choiceSelect.value;
            }

            if (choiceSelect) {
                choiceSelect.hidden =
                    true;

                choiceSelect.disabled =
                    true;
            }

            if (numberInput) {
                numberInput.hidden =
                    !showFixed;

                numberInput.disabled =
                    !showFixed;

                numberInput.type =
                    dataType === 'number'
                        ? 'number'
                        : 'text';

                if (dataType === 'number') {
                    numberInput.step =
                        'any';
                } else {
                    numberInput.removeAttribute(
                        'step'
                    );
                }
            }
        }
    }

    if (randomWrap) {
        const showRandom =
            !noChange &&
            supportsRandom &&
            valueMode === 'random';

        randomWrap.hidden =
            !showRandom;

        randomWrap
            .querySelectorAll(
                'input'
            )
            .forEach(
                function (field) {
                    field.disabled =
                        !showRandom;
                }
            );
    }
}


function wayfarerEffectReindexBranches(
    effectRow
) {

    const effectIndex =
        effectRow.dataset.effectIndex;

    const list =
        effectRow.querySelector(
            '[data-effect-branch-list]'
        );

    if (
        effectIndex === undefined ||
        !list
    ) {
        return;
    }


    const branches =
        Array
            .from(
                list.children
            )
            .filter(
                function (child) {

                    return (
                        child.matches &&
                        child.matches(
                            '[data-effect-branch]'
                        )
                    );
                }
            );


    branches.forEach(
        function (
            branch,
            branchIndex
        ) {

            branch.dataset.branchIndex =
                String(
                    branchIndex
                );

            branch
                .querySelectorAll(
                    '[name]'
                )
                .forEach(
                    function (field) {

                        field.name =
                            field.name.replace(
                                /effects\[\d+\]\[branches\]\[\d+\]/,
                                'effects[' +
                                effectIndex +
                                '][branches][' +
                                branchIndex +
                                ']'
                            );
                    }
                );
        }
    );
}


function wayfarerEffectRefreshBranchControls(
    effectRow
) {

    const list =
        effectRow.querySelector(
            '[data-effect-branch-list]'
        );

    if (!list) {
        return;
    }


    const branches =
        Array
            .from(
                list.children
            )
            .filter(
                function (child) {

                    return (
                        child.matches &&
                        child.matches(
                            '[data-effect-branch]'
                        )
                    );
                }
            );


    const conditionals =
        branches.filter(
            function (branch) {

                return (
                    branch.dataset.branchKind ===
                    'conditional'
                );
            }
        );


    conditionals.forEach(
        function (
            branch,
            index
        ) {

            const up =
                branch.querySelector(
                    '[data-move-effect-branch-up]'
                );

            const down =
                branch.querySelector(
                    '[data-move-effect-branch-down]'
                );

            if (up) {
                up.disabled =
                    index === 0;
            }

            if (down) {

                down.disabled =
                    index ===
                    conditionals.length - 1;
            }
        }
    );


    const hasOtherwise =
        branches.some(
            function (branch) {

                return (
                    branch.dataset.branchKind ===
                    'otherwise'
                );
            }
        );


    const addOtherwise =
        effectRow.querySelector(
            '[data-add-effect-otherwise]'
        );

    if (addOtherwise) {
        addOtherwise.disabled =
            hasOtherwise;
    }


    branches.forEach(
        wayfarerEffectUpdateResultFields
    );


    wayfarerEffectReindexBranches(
        effectRow
    );
}


function initializeEffects() {

    document
        .querySelectorAll(
            '[data-builder-effects]'
        )
        .forEach(
            function (wrapper) {

                if (
                    wrapper.dataset.effectsReady ===
                    '1'
                ) {
                    return;
                }

                wrapper.dataset.effectsReady =
                    '1';


                const list =
                    wrapper.querySelector(
                        '[data-effects-list]'
                    );

                const addButton =
                    wrapper.querySelector(
                        '[data-add-effect]'
                    );

                const effectTemplate =
                    wrapper.querySelector(
                        '[data-effect-template]'
                    );

                const conditionalTemplate =
                    wrapper.querySelector(
                        '[data-effect-conditional-template]'
                    );

                const otherwiseTemplate =
                    wrapper.querySelector(
                        '[data-effect-otherwise-template]'
                    );

                const conditionTargets =
                    wayfarerEffectConditionTargets(
                        wrapper
                    );


                let nextIndex =
                    0;


                wrapper
                    .querySelectorAll(
                        '[data-effect-row]'
                    )
                    .forEach(
                        function (row) {

                            const index =
                                Number(
                                    row.dataset.effectIndex
                                );

                            if (
                                Number.isFinite(
                                    index
                                ) &&
                                index >=
                                    nextIndex
                            ) {

                                nextIndex =
                                    index + 1;
                            }


                            wayfarerEffectRefreshBranchControls(
                                row
                            );
                        }
                    );


                if (
                    addButton &&
                    list &&
                    effectTemplate
                ) {

                    addButton.addEventListener(
                        'click',
                        function () {

                            const effectIndex =
                                nextIndex++;

                            const html =
                                effectTemplate.innerHTML
                                    .replaceAll(
                                        '__EFFECT_INDEX__',
                                        String(
                                            effectIndex
                                        )
                                    );

                            const temporary =
                                document.createElement(
                                    'div'
                                );

                            temporary.innerHTML =
                                html.trim();

                            const row =
                                temporary.firstElementChild;

                            if (!row) {
                                return;
                            }


                            list.appendChild(
                                row
                            );


                            wayfarerEffectRefreshBranchControls(
                                row
                            );
                        }
                    );
                }


                wrapper.addEventListener(
                    'change',
                    function (event) {

                        const target =
                            event.target.closest(
                                '[data-effect-target]'
                            );

                        if (target) {
                            const effectRow =
                                target.closest(
                                    '[data-effect-row]'
                                );

                            if (effectRow) {
                                wayfarerEffectRefreshBranchControls(
                                    effectRow
                                );
                            }

                            return;
                        }

                        const operation =
                            event.target.closest(
                                '[data-effect-branch-operation]'
                            );

                        const valueMode =
                            event.target.closest(
                                '[data-effect-value-mode]'
                            );

                        if (
                            !operation &&
                            !valueMode
                        ) {
                            return;
                        }


                        const branch =
                            event.target.closest(
                                '[data-effect-branch]'
                            );

                        if (branch) {

                            wayfarerEffectUpdateResultFields(
                                branch
                            );
                        }
                    }
                );


                wrapper.addEventListener(
                    'click',
                    function (event) {

                        const effectRow =
                            event.target.closest(
                                '[data-effect-row]'
                            );


                        const removeEffect =
                            event.target.closest(
                                '[data-remove-effect]'
                            );

                        if (removeEffect) {

                            if (!effectRow) {
                                return;
                            }

                            if (
                                !window.confirm(
                                    'Remove this Effect?'
                                )
                            ) {
                                return;
                            }

                            effectRow.remove();

                            return;
                        }


                        if (!effectRow) {
                            return;
                        }


                        const addConditional =
                            event.target.closest(
                                '[data-add-effect-conditional]'
                            );

                        if (addConditional) {

                            if (!conditionalTemplate) {
                                return;
                            }


                            const branchList =
                                effectRow.querySelector(
                                    '[data-effect-branch-list]'
                                );

                            if (!branchList) {
                                return;
                            }


                            const effectIndex =
                                effectRow.dataset.effectIndex;

                            const branchIndex =
                                branchList
                                    .querySelectorAll(
                                        ':scope > [data-effect-branch]'
                                    )
                                    .length;


                            const html =
                                conditionalTemplate.innerHTML
                                    .replaceAll(
                                        '__EFFECT_INDEX__',
                                        effectIndex
                                    )
                                    .replaceAll(
                                        '__BRANCH_INDEX__',
                                        String(
                                            branchIndex
                                        )
                                    );


                            const temporary =
                                document.createElement(
                                    'div'
                                );

                            temporary.innerHTML =
                                html.trim();

                            const branch =
                                temporary.firstElementChild;

                            if (!branch) {
                                return;
                            }


                            const otherwise =
                                Array
                                    .from(
                                        branchList.children
                                    )
                                    .find(
                                        function (child) {

                                            return (
                                                child.dataset &&
                                                child.dataset.branchKind ===
                                                'otherwise'
                                            );
                                        }
                                    );


                            if (otherwise) {

                                branchList.insertBefore(
                                    branch,
                                    otherwise
                                );

                            } else {

                                branchList.appendChild(
                                    branch
                                );
                            }


                            wayfarerEffectReindexBranches(
                                effectRow
                            );


                            const newIndex =
                                branch.dataset.branchIndex;

                            const host =
                                branch.querySelector(
                                    '[data-new-effect-condition-editor]'
                                );


                            if (host) {

                                wayfarerEffectBuildConditionEditor(
                                    host,
                                    'effects[' +
                                    effectIndex +
                                    '][branches][' +
                                    newIndex +
                                    '][conditions]',
                                    conditionTargets
                                );
                            }


                            wayfarerEffectRefreshBranchControls(
                                effectRow
                            );

                            return;
                        }


                        const addOtherwise =
                            event.target.closest(
                                '[data-add-effect-otherwise]'
                            );

                        if (addOtherwise) {

                            if (!otherwiseTemplate) {
                                return;
                            }


                            const branchList =
                                effectRow.querySelector(
                                    '[data-effect-branch-list]'
                                );

                            if (
                                !branchList ||
                                branchList.querySelector(
                                    '[data-branch-kind="otherwise"]'
                                )
                            ) {
                                return;
                            }


                            const effectIndex =
                                effectRow.dataset.effectIndex;

                            const branchIndex =
                                branchList
                                    .querySelectorAll(
                                        ':scope > [data-effect-branch]'
                                    )
                                    .length;


                            const html =
                                otherwiseTemplate.innerHTML
                                    .replaceAll(
                                        '__EFFECT_INDEX__',
                                        effectIndex
                                    )
                                    .replaceAll(
                                        '__BRANCH_INDEX__',
                                        String(
                                            branchIndex
                                        )
                                    );


                            const temporary =
                                document.createElement(
                                    'div'
                                );

                            temporary.innerHTML =
                                html.trim();

                            const branch =
                                temporary.firstElementChild;

                            if (!branch) {
                                return;
                            }


                            branchList.appendChild(
                                branch
                            );


                            wayfarerEffectRefreshBranchControls(
                                effectRow
                            );

                            return;
                        }


                        const removeBranch =
                            event.target.closest(
                                '[data-remove-effect-branch]'
                            );

                        if (removeBranch) {

                            const branch =
                                removeBranch.closest(
                                    '[data-effect-branch]'
                                );

                            if (branch) {

                                branch.remove();

                                wayfarerEffectRefreshBranchControls(
                                    effectRow
                                );
                            }

                            return;
                        }


                        const moveUp =
                            event.target.closest(
                                '[data-move-effect-branch-up]'
                            );

                        const moveDown =
                            event.target.closest(
                                '[data-move-effect-branch-down]'
                            );


                        if (
                            !moveUp &&
                            !moveDown
                        ) {
                            return;
                        }


                        const branch =
                            event.target.closest(
                                '[data-effect-branch]'
                            );

                        const branchList =
                            effectRow.querySelector(
                                '[data-effect-branch-list]'
                            );


                        if (
                            !branch ||
                            !branchList ||
                            branch.dataset.branchKind !==
                                'conditional'
                        ) {
                            return;
                        }


                        const conditionals =
                            Array
                                .from(
                                    branchList.children
                                )
                                .filter(
                                    function (child) {

                                        return (
                                            child.dataset &&
                                            child.dataset.branchKind ===
                                            'conditional'
                                        );
                                    }
                                );


                        const index =
                            conditionals.indexOf(
                                branch
                            );


                        if (
                            moveUp &&
                            index > 0
                        ) {

                            branchList.insertBefore(
                                branch,
                                conditionals[
                                    index - 1
                                ]
                            );
                        }


                        if (
                            moveDown &&
                            index >= 0 &&
                            index <
                                conditionals.length - 1
                        ) {

                            const next =
                                conditionals[
                                    index + 1
                                ];

                            branchList.insertBefore(
                                next,
                                branch
                            );
                        }


                        wayfarerEffectRefreshBranchControls(
                            effectRow
                        );
                    }
                );
            }
        );
}


initializeEffects();


initializeTickEffects();initializeTickEffects();

// ================================================================
// REUSABLE CONDITION EDITOR v27
// WAYFARER_CONDITION_EDITOR_V27
// ================================================================

function wayfarerConditionEscape(value) {

    return String(value)
        .replaceAll('&', '&amp;')
        .replaceAll('<', '&lt;')
        .replaceAll('>', '&gt;')
        .replaceAll('"', '&quot;')
        .replaceAll("'", '&#039;');
}


function wayfarerConditionTargetOptions(
    targets
) {

    const groups = {};

    Object
        .entries(
            targets || {}
        )
        .forEach(
            function (entry) {

                const key =
                    entry[0];

                const target =
                    entry[1] || {};

                /*
                 * WAYFARER_LOCATION_CONDITION_TARGETS_V75
                 * WAYFARER_BUILDER_JS_REPAIR_V79
                 *
                 * Hidden compatibility targets are retained in JSON so an
                 * existing saved row can resolve its datatype, but they are
                 * not offered when the author adds a new Condition.
                 */
                if (target.condition_hidden) {
                    return;
                }

                const group =
                    target.group ||
                    'Targets';

                if (!groups[group]) {
                    groups[group] = [];
                }

                const helper =
                    String(
                        target.helper ||
                        ''
                    ).trim();

                const baseLabel =
                    target.label ||
                    key;

                groups[group].push({
                    key: key,
                    label:
                        helper !== ''
                            ? baseLabel + ' — ' + helper
                            : baseLabel
                });
            }
        );

    let html =
        '<option value="">Select target...</option>';

    Object
        .entries(groups)
        .forEach(
            function (entry) {

                html +=
                    '<optgroup label="' +
                    wayfarerConditionEscape(
                        entry[0]
                    ) +
                    '">';

                entry[1]
                    .forEach(
                        function (target) {

                            html +=
                                '<option value="' +
                                wayfarerConditionEscape(
                                    target.key
                                ) +
                                '">' +
                                wayfarerConditionEscape(
                                    target.label
                                ) +
                                '</option>';
                        }
                    );

                html +=
                    '</optgroup>';
            }
        );

    return html;
}


/* WAYFARER_DATATYPE_CONDITION_UI_V58 */
function wayfarerConditionOperatorLabel(
    operator
) {

    const labels = {
        equals: 'Equals',
        not_equals: 'Does not equal',
        greater_than: 'Greater than',
        greater_than_or_equal: 'Greater than or equal',
        less_than: 'Less than',
        less_than_or_equal: 'Less than or equal'
    };

    return labels[operator] || operator;
}


function wayfarerConditionUpdateRow(
    row,
    targets
) {

    if (!row) {
        return;
    }

    const targetSelect =
        row.querySelector(
            '[data-condition-target]'
        );

    const operatorSelect =
        row.querySelector(
            '[data-condition-operator]'
        );

    const valueInput =
        row.querySelector(
            '[data-condition-value-input]'
        );

    const valueSelect =
        row.querySelector(
            '[data-condition-value-select]'
        );

    const valueWrap =
        row.querySelector(
            '[data-condition-value-wrap]'
        );

    if (!targetSelect || !operatorSelect) {
        return;
    }

    const definition =
        (targets || {})[targetSelect.value] ||
        {};

    const dataType =
        String(
            definition.data_type ||
            definition.trait_type ||
            'text'
        ).toLowerCase() === 'binary'
            ? 'boolean'
            : String(
                definition.data_type ||
                definition.trait_type ||
                'text'
            ).toLowerCase();

    const allowedOperators =
        Array.isArray(
            definition.condition_operators
        ) &&
        definition.condition_operators.length
            ? definition.condition_operators
            : [
                'equals',
                'not_equals',
                'greater_than',
                'greater_than_or_equal',
                'less_than',
                'less_than_or_equal'
            ];

    const previousOperator =
        operatorSelect.value;

    operatorSelect.innerHTML =
        '';

    allowedOperators.forEach(
        function (operator) {

            const option =
                document.createElement(
                    'option'
                );

            option.value =
                operator;

            const operatorLabels =
                definition.condition_operator_labels &&
                typeof definition.condition_operator_labels === 'object'
                    ? definition.condition_operator_labels
                    : {};

            option.textContent =
                operatorLabels[operator] ||
                wayfarerConditionOperatorLabel(
                    operator
                );

            operatorSelect.appendChild(
                option
            );
        }
    );

    operatorSelect.value =
        allowedOperators.includes(
            previousOperator
        )
            ? previousOperator
            : allowedOperators[0];

    const valueOptions =
        definition.value_options &&
        typeof definition.value_options === 'object'
            ? definition.value_options
            : null;

    if (valueWrap) {
        valueWrap.hidden =
            Boolean(
                definition.condition_hide_value
            );
    }

    if (valueOptions && valueSelect) {

        const previousValue =
            valueSelect.hidden && valueInput
                ? valueInput.value
                : valueSelect.value;

        valueSelect.innerHTML =
            '';

        Object
            .entries(valueOptions)
            .forEach(
                function (entry) {

                    const option =
                        document.createElement(
                            'option'
                        );

                    option.value =
                        entry[0];

                    option.textContent =
                        entry[1];

                    valueSelect.appendChild(
                        option
                    );
                }
            );

        if (
            Object.prototype.hasOwnProperty.call(
                valueOptions,
                String(previousValue)
            )
        ) {
            valueSelect.value =
                String(previousValue);
        }

        valueSelect.hidden =
            false;

        valueSelect.disabled =
            false;

        if (valueInput) {
            valueInput.hidden =
                true;

            valueInput.disabled =
                true;
        }

        return;
    }

    if (
        valueSelect &&
        valueInput &&
        !valueSelect.hidden
    ) {
        valueInput.value =
            valueSelect.value;
    }

    if (valueSelect) {
        valueSelect.hidden =
            true;

        valueSelect.disabled =
            true;
    }

    if (valueInput) {
        valueInput.hidden =
            false;

        valueInput.disabled =
            false;

        valueInput.type =
            dataType === 'number'
                ? 'number'
                : 'text';

        if (dataType === 'number') {
            valueInput.step =
                'any';
        } else {
            valueInput.removeAttribute(
                'step'
            );
        }
    }
}


function wayfarerConditionNextChildIndex(
    group
) {

    let maxIndex = -1;

    const children =
        Array
            .from(
                group.children
            )
            .find(
                function (child) {
                    return child.hasAttribute(
                        'data-condition-children'
                    );
                }
            );

    if (children) {

        Array
            .from(
                children.children
            )
            .forEach(
                function (node) {

                    let index =
                        Number(
                            node.dataset.conditionChildIndex
                        );

                    if (!Number.isFinite(index)) {

                        const namedInput =
                            node.querySelector(
                                '[name]'
                            );

                        const match =
                            namedInput
                                ? namedInput.name.match(
                                    /\[children\]\[(\d+)\]/
                                )
                                : null;

                        index =
                            match
                                ? Number(match[1])
                                : -1;
                    }

                    if (
                        Number.isFinite(index) &&
                        index > maxIndex
                    ) {
                        maxIndex =
                            index;
                    }
                }
            );
    }

    return maxIndex + 1;
}


function wayfarerConditionCreateCondition(
    name,
    targets,
    childIndex
) {

    const row =
        document.createElement(
            'div'
        );

    row.className =
        'builder-condition-row';

    row.dataset.conditionNode =
        '1';

    row.dataset.conditionType =
        'condition';

    row.dataset.conditionChildIndex =
        String(childIndex);

    row.innerHTML =
        '<input type="hidden" name="' +
        wayfarerConditionEscape(name) +
        '[type]" value="condition">' +

        '<label>Target' +
        '<select name="' +
        wayfarerConditionEscape(name) +
        '[target]" data-condition-target>' +
        wayfarerConditionTargetOptions(
            targets
        ) +
        '</select></label>' +

        '<label>Comparison' +
        '<select name="' +
        wayfarerConditionEscape(name) +
        '[operator]" data-condition-operator>' +
        '<option value="equals">Equals</option>' +
        '<option value="not_equals">Does not equal</option>' +
        '<option value="greater_than">Greater than</option>' +
        '<option value="greater_than_or_equal">Greater than or equal</option>' +
        '<option value="less_than">Less than</option>' +
        '<option value="less_than_or_equal">Less than or equal</option>' +
        '</select></label>' +

        '<label data-condition-value-wrap>Value' +
        '<input type="text" name="' +
        wayfarerConditionEscape(name) +
        '[value]" data-condition-value-input>' +
        '<select name="' +
        wayfarerConditionEscape(name) +
        '[value]" data-condition-value-select hidden disabled></select>' +
        '</label>' +

        '<button type="button" class="secondary-button" ' +
        'data-remove-condition-node>Remove</button>';

    return row;
}


function wayfarerConditionCreateGroup(
    name,
    targets,
    childIndex,
    isRoot
) {

    const group =
        document.createElement(
            'div'
        );

    group.className =
        'builder-condition-group' +
        (
            isRoot
                ? ' builder-condition-group-root'
                : ''
        );

    group.dataset.conditionNode =
        '1';

    group.dataset.conditionType =
        'group';

    if (
        childIndex !== null &&
        childIndex !== undefined
    ) {
        group.dataset.conditionChildIndex =
            String(childIndex);
    }

    group.innerHTML =
        '<input type="hidden" name="' +
        wayfarerConditionEscape(name) +
        '[type]" value="group">' +

        '<div class="builder-condition-group-header">' +
        '<label>Match ' +
        '<select name="' +
        wayfarerConditionEscape(name) +
        '[mode]">' +
        '<option value="all">ALL</option>' +
        '<option value="any">ANY</option>' +
        '</select></label>' +
        '<span> of the following</span>' +
        (
            isRoot
                ? ''
                : '<button type="button" class="secondary-button" ' +
                  'data-remove-condition-node>Remove Group</button>'
        ) +
        '</div>' +

        '<div class="builder-condition-children" ' +
        'data-condition-children></div>' +

        '<div class="builder-condition-actions">' +
        '<button type="button" class="secondary-button" ' +
        'data-add-condition>+ Add Condition</button> ' +
        '<button type="button" class="secondary-button" ' +
        'data-add-condition-group>+ Add Group</button>' +
        '</div>';

    return group;
}


function wayfarerConditionInitializeEditor(
    editor,
    targets
) {

    if (
        !editor ||
        editor.dataset.conditionEditorReady ===
            '1'
    ) {
        return;
    }

    editor.dataset.conditionEditorReady =
        '1';

    editor.addEventListener(
        'change',
        function (event) {

            const targetSelect =
                event.target.closest(
                    '[data-condition-target]'
                );

            if (!targetSelect) {
                return;
            }

            wayfarerConditionUpdateRow(
                targetSelect.closest(
                    '[data-condition-type="condition"]'
                ),
                targets
            );
        }
    );

    editor
        .querySelectorAll(
            '[data-condition-type="condition"]'
        )
        .forEach(
            function (row) {
                wayfarerConditionUpdateRow(
                    row,
                    targets
                );
            }
        );

    editor.addEventListener(
        'click',
        function (event) {

            const removeButton =
                event.target.closest(
                    '[data-remove-condition-node]'
                );

            if (removeButton) {

                const node =
                    removeButton.closest(
                        '[data-condition-node]'
                    );

                if (node) {
                    node.remove();
                }

                return;
            }


            const addCondition =
                event.target.closest(
                    '[data-add-condition]'
                );

            const addGroup =
                event.target.closest(
                    '[data-add-condition-group]'
                );

            if (
                !addCondition &&
                !addGroup
            ) {
                return;
            }

            const group =
                event.target.closest(
                    '[data-condition-type="group"]'
                );

            if (!group) {
                return;
            }

            const children =
                Array
                    .from(
                        group.children
                    )
                    .find(
                        function (child) {
                            return child.hasAttribute(
                                'data-condition-children'
                            );
                        }
                    );

            if (!children) {
                return;
            }

            const groupTypeInput =
                Array
                    .from(
                        group.children
                    )
                    .find(
                        function (child) {
                            return (
                                child.tagName === 'INPUT' &&
                                child.type === 'hidden' &&
                                child.name.endsWith(
                                    '[type]'
                                )
                            );
                        }
                    );

            if (!groupTypeInput) {
                return;
            }

            const groupName =
                groupTypeInput.name.replace(
                    /\[type\]$/,
                    ''
                );

            const nextIndex =
                wayfarerConditionNextChildIndex(
                    group
                );

            const childName =
                groupName +
                '[children][' +
                nextIndex +
                ']';

            const newNode =
                addGroup
                    ? wayfarerConditionCreateGroup(
                        childName,
                        targets,
                        nextIndex,
                        false
                    )
                    : wayfarerConditionCreateCondition(
                        childName,
                        targets,
                        nextIndex
                    );

            children.appendChild(
                newNode
            );

            if (newNode.dataset.conditionType === 'condition') {
                wayfarerConditionUpdateRow(
                    newNode,
                    targets
                );
            }
        }
    );
}


function initializeConditionEditors() {

    /*
     * WAYFARER_GENERIC_CONDITION_INIT_V45_2
     *
     * The Condition Editor is shared infrastructure. It must work anywhere it
     * is rendered, not only when nested inside Tick Effects.
     *
     * Server-rendered editors carry their own allowed-target JSON. Dynamic
     * Tick Effect / Effect editors continue to initialize themselves through
     * their existing creation paths.
     */
    document
        .querySelectorAll(
            '[data-condition-editor]'
        )
        .forEach(
            function (editor) {

                let targets =
                    {};

                const targetJson =
                    editor.querySelector(
                        '[data-condition-editor-targets-json]'
                    );

                if (targetJson) {

                    try {

                        targets =
                            JSON.parse(
                                targetJson.textContent ||
                                '{}'
                            );

                    } catch (error) {

                        targets =
                            {};
                    }
                }


                wayfarerConditionInitializeEditor(
                    editor,
                    targets
                );
            }
        );


    /*
     * Tick Effects retain their observer because newly-created Tick Effect
     * rows are added after page load and are not server-rendered editors.
     */
    document
        .querySelectorAll(
            '[data-builder-tick-effects]'
        )
        .forEach(
            function (wrapper) {

                let targets = {};

                const targetJson =
                    wrapper.querySelector(
                        '[data-condition-targets-json]'
                    );

                if (targetJson) {

                    try {
                        targets =
                            JSON.parse(
                                targetJson.textContent ||
                                '{}'
                            );
                    } catch (error) {
                        targets = {};
                    }
                }

                wrapper
                    .querySelectorAll(
                        '[data-condition-editor]'
                    )
                    .forEach(
                        function (editor) {
                            wayfarerConditionInitializeEditor(
                                editor,
                                targets
                            );
                        }
                    );

                /*
                 * New Tick Effect rows are cloned from a template after page
                 * load, so convert their placeholder into a fresh root group.
                 */
                const list =
                    wrapper.querySelector(
                        '[data-tick-effects-list]'
                    );

                if (
                    list &&
                    !list.dataset.conditionObserverReady
                ) {

                    list.dataset.conditionObserverReady =
                        '1';

                    const observer =
                        new MutationObserver(
                            function (mutations) {

                                mutations.forEach(
                                    function (mutation) {

                                        mutation.addedNodes
                                            .forEach(
                                                function (addedNode) {

                                                    if (
                                                        !addedNode.querySelectorAll
                                                    ) {
                                                        return;
                                                    }

                                                    const row =
                                                        addedNode.matches &&
                                                        addedNode.matches(
                                                            '[data-tick-effect-row]'
                                                        )
                                                            ? addedNode
                                                            : addedNode.querySelector(
                                                                '[data-tick-effect-row]'
                                                            );

                                                    if (!row) {
                                                        return;
                                                    }

                                                    const host =
                                                        row.querySelector(
                                                            '[data-new-condition-editor]'
                                                        );

                                                    if (!host) {
                                                        return;
                                                    }

                                                    const index =
                                                        row.dataset.tickIndex;

                                                    const editor =
                                                        document.createElement(
                                                            'div'
                                                        );

                                                    editor.className =
                                                        'builder-condition-editor';

                                                    editor.dataset.conditionEditor =
                                                        '1';

                                                    editor.appendChild(
                                                        wayfarerConditionCreateGroup(
                                                            'tick_effects[' +
                                                            index +
                                                            '][conditions]',
                                                            targets,
                                                            null,
                                                            true
                                                        )
                                                    );

                                                    host.replaceWith(
                                                        editor
                                                    );

                                                    wayfarerConditionInitializeEditor(
                                                        editor,
                                                        targets
                                                    );
                                                }
                                            );
                                    }
                                );
                            }
                        );

                    observer.observe(
                        list,
                        {
                            childList: true,
                            subtree: true
                        }
                    );
                }
            }
        );
}


initializeConditionEditors();

// ================================================================
// TICK EFFECT RESULT BRANCHES v28
// WAYFARER_TICK_EFFECT_BRANCHES_V28
// ================================================================

function wayfarerTickEffectConditionTargets(
    wrapper
) {

    const targetJson =
        wrapper.querySelector(
            '[data-condition-targets-json]'
        );

    if (!targetJson) {
        return {};
    }

    try {
        return JSON.parse(
            targetJson.textContent ||
            '{}'
        );
    } catch (error) {
        return {};
    }
}


/* WAYFARER_DATATYPE_TICK_EFFECT_UI_V58 */
function wayfarerTickEffectTargetCatalog(
    wrapper
) {

    const targetJson =
        wrapper
            ? wrapper.querySelector(
                '[data-tick-target-catalog-json]'
            )
            : null;

    if (!targetJson) {
        return {};
    }

    try {
        return JSON.parse(
            targetJson.textContent ||
            '{}'
        );
    } catch (error) {
        return {};
    }
}


function wayfarerTickEffectTargetDefinition(
    branch
) {

    const effectRow =
        branch
            ? branch.closest(
                '[data-tick-effect-row]'
            )
            : null;

    const wrapper =
        effectRow
            ? effectRow.closest(
                '[data-builder-tick-effects]'
            )
            : null;

    const targetSelect =
        effectRow
            ? effectRow.querySelector(
                '[data-tick-effect-target]'
            )
            : null;

    const catalog =
        wayfarerTickEffectTargetCatalog(
            wrapper
        );

    return targetSelect
        ? (catalog[targetSelect.value] || {})
        : {};
}


function wayfarerTickEffectEnsureValueMode(
    branch,
    valueInput
) {

    if (!branch || !valueInput) {
        return null;
    }

    let wrap =
        branch.querySelector(
            '[data-tick-value-mode-wrap]'
        );

    if (!wrap) {
        wrap =
            document.createElement(
                'label'
            );

        wrap.dataset.tickValueModeWrap =
            '1';

        wrap.appendChild(
            document.createTextNode(
                'Value Type'
            )
        );

        const select =
            document.createElement(
                'select'
            );

        select.dataset.tickValueMode =
            '1';

        select.name =
            valueInput.name.replace(
                /\[value\]$/,
                '[value_mode]'
            );

        select.innerHTML =
            '<option value="fixed">Fixed</option>' +
            '<option value="random">Random</option>';

        const fields =
            valueInput.closest(
                '.builder-tick-result-fields'
            );

        if (
            fields &&
            fields.dataset.tickInitialValueMode === 'random'
        ) {
            select.value =
                'random';
        }

        wrap.appendChild(
            select
        );

        const valueWrap =
            branch.querySelector(
                '[data-tick-branch-value-wrap]'
            );

        if (valueWrap && valueWrap.parentNode) {
            valueWrap.parentNode.insertBefore(
                wrap,
                valueWrap
            );
        }
    }

    return wrap;
}


function wayfarerTickEffectEnsureChoiceSelect(
    valueWrap,
    valueInput
) {

    if (!valueWrap || !valueInput) {
        return null;
    }

    let select =
        valueWrap.querySelector(
            '[data-tick-fixed-choice]'
        );

    if (!select) {
        select =
            document.createElement(
                'select'
            );

        select.dataset.tickFixedChoice =
            '1';

        select.name =
            valueInput.name;

        select.hidden =
            true;

        select.disabled =
            true;

        valueWrap.appendChild(
            select
        );
    }

    return select;
}


function wayfarerTickEffectEnsureRandomWrap(
    branch,
    valueInput
) {

    if (!branch || !valueInput) {
        return null;
    }

    let wrap =
        branch.querySelector(
            '[data-tick-random-wrap]'
        );

    if (!wrap) {
        wrap =
            document.createElement(
                'div'
            );

        wrap.className =
            'builder-effect-random-range';

        wrap.dataset.tickRandomWrap =
            '1';

        const baseName =
            valueInput.name.replace(
                /\[value\]$/,
                ''
            );

        wrap.innerHTML =
            '<label>Min' +
            '<input type="number" step="any" name="' +
            wayfarerConditionEscape(baseName) +
            '[value_min]" data-tick-random-min></label>' +
            '<label>Max' +
            '<input type="number" step="any" name="' +
            wayfarerConditionEscape(baseName) +
            '[value_max]" data-tick-random-max></label>';

        const fields =
            valueInput.closest(
                '.builder-tick-result-fields'
            );

        if (fields) {
            const minInput =
                wrap.querySelector(
                    '[data-tick-random-min]'
                );

            const maxInput =
                wrap.querySelector(
                    '[data-tick-random-max]'
                );

            if (minInput) {
                minInput.value =
                    fields.dataset.tickInitialMin ||
                    '';
            }

            if (maxInput) {
                maxInput.value =
                    fields.dataset.tickInitialMax ||
                    '';
            }
        }

        const valueWrap =
            branch.querySelector(
                '[data-tick-branch-value-wrap]'
            );

        if (valueWrap && valueWrap.parentNode) {
            valueWrap.parentNode.insertBefore(
                wrap,
                valueWrap.nextSibling
            );
        }
    }

    return wrap;
}


function wayfarerTickEffectUpdateBranchValue(
    branch
) {

    const operation =
        branch.querySelector(
            '[data-tick-branch-operation]'
        );

    const valueWrap =
        branch.querySelector(
            '[data-tick-branch-value-wrap]'
        );

    if (
        !operation ||
        !valueWrap
    ) {
        return;
    }

    const input =
        valueWrap.querySelector(
            'input[name]'
        );

    if (!input) {
        return;
    }

    const definition =
        wayfarerTickEffectTargetDefinition(
            branch
        );

    let dataType =
        String(
            definition.data_type ||
            definition.trait_type ||
            'number'
        ).toLowerCase();

    if (dataType === 'binary') {
        dataType = 'boolean';
    }

    const allowedOperations =
        Array.isArray(
            definition.effect_operations
        ) &&
        definition.effect_operations.length
            ? definition.effect_operations
            : (
                dataType === 'number'
                    ? ['set', 'add', 'subtract']
                    : ['set']
            );

    const supportsRandom =
        Object.prototype.hasOwnProperty.call(
            definition,
            'supports_random'
        )
            ? Boolean(
                definition.supports_random
            )
            : dataType === 'number';

    const previousOperation =
        operation.value;

    const resultOperations =
        allowedOperations.concat(
            ['none']
        );

    operation.innerHTML =
        '';

    const operationLabels = {
        set: 'Set',
        add: 'Add',
        subtract: 'Subtract',
        none: 'No Change'
    };

    resultOperations.forEach(
        function (operationValue) {

            const option =
                document.createElement(
                    'option'
                );

            option.value =
                operationValue;

            option.textContent =
                operationLabels[operationValue] ||
                operationValue;

            operation.appendChild(
                option
            );
        }
    );

    operation.value =
        resultOperations.includes(
            previousOperation
        )
            ? previousOperation
            : allowedOperations[0];

    const noChange =
        operation.value ===
        'none';

    const modeWrap =
        wayfarerTickEffectEnsureValueMode(
            branch,
            input
        );

    const mode =
        modeWrap
            ? modeWrap.querySelector(
                '[data-tick-value-mode]'
            )
            : null;

    let valueMode =
        mode
            ? mode.value
            : 'fixed';

    if (!supportsRandom) {
        valueMode =
            'fixed';

        if (mode) {
            mode.value =
                'fixed';
        }
    }

    if (modeWrap) {
        modeWrap.hidden =
            noChange ||
            !supportsRandom;

        if (mode) {
            mode.disabled =
                noChange ||
                !supportsRandom;
        }
    }

    const showFixed =
        !noChange &&
        (
            !supportsRandom ||
            valueMode === 'fixed'
        );

    valueWrap.hidden =
        !showFixed;

    const choiceSelect =
        wayfarerTickEffectEnsureChoiceSelect(
            valueWrap,
            input
        );

    const valueOptions =
        definition.value_options &&
        typeof definition.value_options === 'object'
            ? definition.value_options
            : null;

    if (
        showFixed &&
        valueOptions &&
        choiceSelect
    ) {
        const previousValue =
            choiceSelect.hidden
                ? input.value
                : choiceSelect.value;

        choiceSelect.innerHTML =
            '';

        Object
            .entries(valueOptions)
            .forEach(
                function (entry) {

                    const option =
                        document.createElement(
                            'option'
                        );

                    option.value =
                        entry[0];

                    option.textContent =
                        entry[1];

                    choiceSelect.appendChild(
                        option
                    );
                }
            );

        if (
            Object.prototype.hasOwnProperty.call(
                valueOptions,
                String(previousValue)
            )
        ) {
            choiceSelect.value =
                String(previousValue);
        }

        choiceSelect.hidden =
            false;

        choiceSelect.disabled =
            false;

        input.hidden =
            true;

        input.disabled =
            true;

    } else {
        if (
            choiceSelect &&
            !choiceSelect.hidden
        ) {
            input.value =
                choiceSelect.value;
        }

        if (choiceSelect) {
            choiceSelect.hidden =
                true;

            choiceSelect.disabled =
                true;
        }

        input.hidden =
            !showFixed;

        input.disabled =
            !showFixed;

        input.type =
            dataType === 'number'
                ? 'number'
                : 'text';

        if (dataType === 'number') {
            input.step =
                'any';
        } else {
            input.removeAttribute(
                'step'
            );
        }
    }

    const randomWrap =
        wayfarerTickEffectEnsureRandomWrap(
            branch,
            input
        );

    if (randomWrap) {
        const showRandom =
            !noChange &&
            supportsRandom &&
            valueMode === 'random';

        randomWrap.hidden =
            !showRandom;

        randomWrap
            .querySelectorAll(
                'input'
            )
            .forEach(
                function (field) {
                    field.disabled =
                        !showRandom;
                }
            );
    }
}


function wayfarerTickEffectReindexBranches(
    effectRow
) {

    const effectIndex =
        effectRow.dataset.tickIndex;

    const list =
        effectRow.querySelector(
            '[data-tick-branch-list]'
        );

    if (
        effectIndex === undefined ||
        !list
    ) {
        return;
    }

    const branches =
        Array.from(
            list.children
        ).filter(
            function (child) {
                return (
                    child.matches &&
                    child.matches(
                        '[data-tick-effect-branch]'
                    )
                );
            }
        );

    branches.forEach(
        function (
            branch,
            branchIndex
        ) {

            branch.dataset.branchIndex =
                String(
                    branchIndex
                );

            branch
                .querySelectorAll(
                    '[name]'
                )
                .forEach(
                    function (field) {

                        field.name =
                            field.name.replace(
                                /tick_effects\[\d+\]\[branches\]\[\d+\]/,
                                'tick_effects[' +
                                effectIndex +
                                '][branches][' +
                                branchIndex +
                                ']'
                            );
                    }
                );
        }
    );
}


function wayfarerTickEffectRefreshBranchControls(
    effectRow
) {

    const list =
        effectRow.querySelector(
            '[data-tick-branch-list]'
        );

    if (!list) {
        return;
    }

    const branches =
        Array.from(
            list.children
        ).filter(
            function (child) {
                return (
                    child.matches &&
                    child.matches(
                        '[data-tick-effect-branch]'
                    )
                );
            }
        );

    const conditionalBranches =
        branches.filter(
            function (branch) {
                return (
                    branch.dataset.branchKind ===
                    'conditional'
                );
            }
        );

    conditionalBranches.forEach(
        function (
            branch,
            index
        ) {

            const up =
                branch.querySelector(
                    '[data-move-tick-branch-up]'
                );

            const down =
                branch.querySelector(
                    '[data-move-tick-branch-down]'
                );

            if (up) {
                up.disabled =
                    index === 0;
            }

            if (down) {
                down.disabled =
                    index ===
                    conditionalBranches.length - 1;
            }
        }
    );


    const hasOtherwise =
        branches.some(
            function (branch) {
                return (
                    branch.dataset.branchKind ===
                    'otherwise'
                );
            }
        );

    const addOtherwise =
        effectRow.querySelector(
            '[data-add-tick-otherwise-result]'
        );

    if (addOtherwise) {
        addOtherwise.disabled =
            hasOtherwise;
    }


    branches.forEach(
        wayfarerTickEffectUpdateBranchValue
    );

    wayfarerTickEffectReindexBranches(
        effectRow
    );
}


function wayfarerTickEffectBuildConditionEditor(
    host,
    name,
    targets
) {

    const editor =
        document.createElement(
            'div'
        );

    editor.className =
        'builder-condition-editor';

    editor.dataset.conditionEditor =
        '1';

    editor.appendChild(
        wayfarerConditionCreateGroup(
            name,
            targets,
            null,
            true
        )
    );

    host.replaceWith(
        editor
    );

    wayfarerConditionInitializeEditor(
        editor,
        targets
    );
}


function initializeTickEffectResultBranches() {

    document
        .querySelectorAll(
            '[data-builder-tick-effects]'
        )
        .forEach(
            function (wrapper) {

                if (
                    wrapper.dataset.tickBranchesReady ===
                    '1'
                ) {
                    return;
                }

                wrapper.dataset.tickBranchesReady =
                    '1';

                const conditionalTemplate =
                    wrapper.querySelector(
                        '[data-tick-conditional-branch-template]'
                    );

                const otherwiseTemplate =
                    wrapper.querySelector(
                        '[data-tick-otherwise-branch-template]'
                    );

                const conditionTargets =
                    wayfarerTickEffectConditionTargets(
                        wrapper
                    );


                wrapper
                    .querySelectorAll(
                        '[data-tick-effect-row]'
                    )
                    .forEach(
                        wayfarerTickEffectRefreshBranchControls
                    );


                wrapper.addEventListener(
                    'change',
                    function (event) {

                        const target =
                            event.target.closest(
                                '[data-tick-effect-target]'
                            );

                        if (target) {
                            const effectRow =
                                target.closest(
                                    '[data-tick-effect-row]'
                                );

                            if (effectRow) {
                                wayfarerTickEffectRefreshBranchControls(
                                    effectRow
                                );
                            }

                            return;
                        }

                        const operation =
                            event.target.closest(
                                '[data-tick-branch-operation]'
                            );

                        const valueMode =
                            event.target.closest(
                                '[data-tick-value-mode]'
                            );

                        if (!operation && !valueMode) {
                            return;
                        }

                        const branch =
                            event.target.closest(
                                '[data-tick-effect-branch]'
                            );

                        if (branch) {
                            wayfarerTickEffectUpdateBranchValue(
                                branch
                            );
                        }
                    }
                );


                wrapper.addEventListener(
                    'click',
                    function (event) {

                        const effectRow =
                            event.target.closest(
                                '[data-tick-effect-row]'
                            );

                        if (!effectRow) {
                            return;
                        }


                        const addConditional =
                            event.target.closest(
                                '[data-add-tick-conditional-result]'
                            );

                        if (addConditional) {

                            if (!conditionalTemplate) {
                                return;
                            }

                            const list =
                                effectRow.querySelector(
                                    '[data-tick-branch-list]'
                                );

                            if (!list) {
                                return;
                            }

                            const effectIndex =
                                effectRow.dataset.tickIndex;

                            const branchIndex =
                                list.querySelectorAll(
                                    ':scope > [data-tick-effect-branch]'
                                ).length;

                            const html =
                                conditionalTemplate.innerHTML
                                    .replaceAll(
                                        '__EFFECT_INDEX__',
                                        effectIndex
                                    )
                                    .replaceAll(
                                        '__BRANCH_INDEX__',
                                        String(
                                            branchIndex
                                        )
                                    );

                            const temporary =
                                document.createElement(
                                    'div'
                                );

                            temporary.innerHTML =
                                html.trim();

                            const branch =
                                temporary.firstElementChild;

                            if (!branch) {
                                return;
                            }

                            const otherwise =
                                Array
                                    .from(
                                        list.children
                                    )
                                    .find(
                                        function (child) {
                                            return (
                                                child.dataset &&
                                                child.dataset.branchKind ===
                                                'otherwise'
                                            );
                                        }
                                    );

                            if (otherwise) {
                                list.insertBefore(
                                    branch,
                                    otherwise
                                );
                            } else {
                                list.appendChild(
                                    branch
                                );
                            }

                            wayfarerTickEffectReindexBranches(
                                effectRow
                            );

                            const newIndex =
                                branch.dataset.branchIndex;

                            const host =
                                branch.querySelector(
                                    '[data-new-branch-condition-editor]'
                                );

                            if (host) {

                                wayfarerTickEffectBuildConditionEditor(
                                    host,
                                    'tick_effects[' +
                                    effectIndex +
                                    '][branches][' +
                                    newIndex +
                                    '][conditions]',
                                    conditionTargets
                                );
                            }

                            wayfarerTickEffectRefreshBranchControls(
                                effectRow
                            );

                            return;
                        }


                        const addOtherwise =
                            event.target.closest(
                                '[data-add-tick-otherwise-result]'
                            );

                        if (addOtherwise) {

                            if (!otherwiseTemplate) {
                                return;
                            }

                            const list =
                                effectRow.querySelector(
                                    '[data-tick-branch-list]'
                                );

                            if (!list) {
                                return;
                            }

                            if (
                                list.querySelector(
                                    '[data-branch-kind="otherwise"]'
                                )
                            ) {
                                return;
                            }

                            const effectIndex =
                                effectRow.dataset.tickIndex;

                            const branchIndex =
                                list.querySelectorAll(
                                    ':scope > [data-tick-effect-branch]'
                                ).length;

                            const html =
                                otherwiseTemplate.innerHTML
                                    .replaceAll(
                                        '__EFFECT_INDEX__',
                                        effectIndex
                                    )
                                    .replaceAll(
                                        '__BRANCH_INDEX__',
                                        String(
                                            branchIndex
                                        )
                                    );

                            const temporary =
                                document.createElement(
                                    'div'
                                );

                            temporary.innerHTML =
                                html.trim();

                            const branch =
                                temporary.firstElementChild;

                            if (!branch) {
                                return;
                            }

                            list.appendChild(
                                branch
                            );

                            wayfarerTickEffectRefreshBranchControls(
                                effectRow
                            );

                            return;
                        }


                        const removeBranch =
                            event.target.closest(
                                '[data-remove-tick-branch]'
                            );

                        if (removeBranch) {

                            const branch =
                                removeBranch.closest(
                                    '[data-tick-effect-branch]'
                                );

                            if (branch) {
                                branch.remove();

                                wayfarerTickEffectRefreshBranchControls(
                                    effectRow
                                );
                            }

                            return;
                        }


                        const moveUp =
                            event.target.closest(
                                '[data-move-tick-branch-up]'
                            );

                        const moveDown =
                            event.target.closest(
                                '[data-move-tick-branch-down]'
                            );

                        if (
                            !moveUp &&
                            !moveDown
                        ) {
                            return;
                        }

                        const branch =
                            event.target.closest(
                                '[data-tick-effect-branch]'
                            );

                        const list =
                            effectRow.querySelector(
                                '[data-tick-branch-list]'
                            );

                        if (
                            !branch ||
                            !list ||
                            branch.dataset.branchKind !==
                                'conditional'
                        ) {
                            return;
                        }

                        const conditionals =
                            Array.from(
                                list.children
                            ).filter(
                                function (child) {
                                    return (
                                        child.dataset &&
                                        child.dataset.branchKind ===
                                        'conditional'
                                    );
                                }
                            );

                        const index =
                            conditionals.indexOf(
                                branch
                            );

                        if (
                            moveUp &&
                            index > 0
                        ) {

                            list.insertBefore(
                                branch,
                                conditionals[index - 1]
                            );
                        }


                        if (
                            moveDown &&
                            index >= 0 &&
                            index <
                                conditionals.length - 1
                        ) {

                            const next =
                                conditionals[index + 1];

                            list.insertBefore(
                                next,
                                branch
                            );
                        }


                        wayfarerTickEffectRefreshBranchControls(
                            effectRow
                        );
                    }
                );


                /*
                 * Existing Tick Effect code creates whole effect rows from its
                 * template. Refresh branch controls after those rows appear.
                 */
                const list =
                    wrapper.querySelector(
                        '[data-tick-effects-list]'
                    );

                if (list) {

                    const observer =
                        new MutationObserver(
                            function (mutations) {

                                mutations.forEach(
                                    function (mutation) {

                                        mutation.addedNodes
                                            .forEach(
                                                function (node) {

                                                    if (
                                                        !node.matches ||
                                                        !node.matches(
                                                            '[data-tick-effect-row]'
                                                        )
                                                    ) {
                                                        return;
                                                    }

                                                    wayfarerTickEffectRefreshBranchControls(
                                                        node
                                                    );
                                                }
                                            );
                                    }
                                );
                            }
                        );

                    observer.observe(
                        list,
                        {
                            childList: true
                        }
                    );
                }
            }
        );
}


initializeTickEffectResultBranches();



==============================================================================
FILE: assets/js/game-endings.js
==============================================================================

/*
|--------------------------------------------------------------------------
| Game Endings Editor
| WAYFARER_GAME_ENDINGS_V45
|--------------------------------------------------------------------------
*/

(function () {
    'use strict';

    const editor =
        document.querySelector(
            '[data-game-endings-editor]'
        );

    if (!editor) {
        return;
    }


    const list =
        editor.querySelector(
            '[data-game-endings-list]'
        );

    const template =
        editor.querySelector(
            '[data-game-ending-template]'
        );

    const addButton =
        editor.querySelector(
            '[data-add-game-ending]'
        );

    const targetJson =
        editor.querySelector(
            '[data-game-ending-condition-targets]'
        );


    let targets =
        {};

    if (targetJson) {

        try {

            targets =
                JSON.parse(
                    targetJson.textContent ||
                    '{}'
                );

        } catch (error) {

            targets =
                {};
        }
    }


    function reindex() {

        if (!list) {
            return;
        }


        Array
            .from(
                list.querySelectorAll(
                    ':scope > [data-game-ending]'
                )
            )
            .forEach(
                function (
                    ending,
                    index
                ) {

                    ending.dataset.endingIndex =
                        String(index);


                    ending
                        .querySelectorAll(
                            '[name]'
                        )
                        .forEach(
                            function (field) {

                                field.name =
                                    field.name.replace(
                                        /endings\[\d+\]/,
                                        'endings[' +
                                        index +
                                        ']'
                                    );
                            }
                        );
                }
            );
    }


    if (
        addButton &&
        list &&
        template
    ) {

        addButton.addEventListener(
            'click',
            function () {

                const index =
                    list.querySelectorAll(
                        ':scope > [data-game-ending]'
                    ).length;

                const html =
                    template.innerHTML.replaceAll(
                        '__INDEX__',
                        String(index)
                    );

                const temporary =
                    document.createElement(
                        'div'
                    );

                temporary.innerHTML =
                    html.trim();

                const ending =
                    temporary.firstElementChild;

                if (!ending) {
                    return;
                }


                list.appendChild(
                    ending
                );


                const host =
                    ending.querySelector(
                        '[data-new-ending-condition-editor]'
                    );

                if (
                    host &&
                    typeof wayfarerConditionCreateGroup ===
                        'function' &&
                    typeof wayfarerConditionInitializeEditor ===
                        'function'
                ) {

                    const conditionEditor =
                        document.createElement(
                            'div'
                        );

                    conditionEditor.className =
                        'builder-condition-editor';

                    conditionEditor.dataset.conditionEditor =
                        '1';

                    conditionEditor.appendChild(
                        wayfarerConditionCreateGroup(
                            'endings[' +
                            index +
                            '][conditions]',
                            targets,
                            null,
                            true
                        )
                    );

                    host.replaceWith(
                        conditionEditor
                    );

                    wayfarerConditionInitializeEditor(
                        conditionEditor,
                        targets
                    );
                }


                reindex();
            }
        );
    }


    editor.addEventListener(
        'click',
        function (event) {

            const removeButton =
                event.target.closest(
                    '[data-remove-game-ending]'
                );

            if (!removeButton) {
                return;
            }


            const ending =
                removeButton.closest(
                    '[data-game-ending]'
                );

            if (!ending) {
                return;
            }


            if (
                !window.confirm(
                    'Remove this Ending?'
                )
            ) {
                return;
            }


            ending.remove();

            reindex();
        }
    );


    reindex();

})();


==============================================================================
FILE: assets/js/game-travel.js
==============================================================================

/*
 * WAYFARER_GAME_TRAVEL_MODIFIERS_JS_V73
 * WAYFARER_GENERIC_TRAVEL_MODIFIER_COPY_V74
 * Dynamic Game Settings Travel Modifier cards.
 */
(function () {
    'use strict';

    const host =
        document.querySelector(
            '[data-game-travel-modifiers]'
        );

    if (!host) {
        return;
    }

    const list =
        host.querySelector(
            '[data-game-travel-modifier-list]'
        );

    const addButton =
        host.querySelector(
            '[data-add-game-travel-modifier]'
        );

    const targetJson =
        host.querySelector(
            '[data-game-travel-targets-json]'
        );

    if (!list || !addButton) {
        return;
    }

    let targets = {};

    if (targetJson) {
        try {
            targets =
                JSON.parse(
                    targetJson.textContent ||
                    '{}'
                );
        } catch (error) {
            targets = {};
        }
    }

    function nextIndex() {
        const current =
            Number(
                host.dataset.nextIndex ||
                0
            );

        const index =
            Number.isFinite(current)
                ? current
                : 0;

        host.dataset.nextIndex =
            String(index + 1);

        return index;
    }

    function refreshLegend(card) {
        const legend =
            card.querySelector(
                '[data-game-travel-modifier-legend]'
            );

        const name =
            card.querySelector(
                '[data-game-travel-modifier-name]'
            );

        if (!legend || !name) {
            return;
        }

        const value =
            String(
                name.value ||
                ''
            ).trim();

        legend.textContent =
            value !== ''
                ? value
                : 'Travel Modifier';
    }

    host.addEventListener(
        'input',
        function (event) {
            const name =
                event.target.closest(
                    '[data-game-travel-modifier-name]'
                );

            if (!name) {
                return;
            }

            const card =
                name.closest(
                    '[data-game-travel-modifier]'
                );

            if (card) {
                refreshLegend(card);
            }
        }
    );

    host.addEventListener(
        'click',
        function (event) {
            const removeButton =
                event.target.closest(
                    '[data-remove-game-travel-modifier]'
                );

            if (!removeButton) {
                return;
            }

            const card =
                removeButton.closest(
                    '[data-game-travel-modifier]'
                );

            if (
                card &&
                window.confirm(
                    'Remove this Travel Modifier?'
                )
            ) {
                card.remove();
            }
        }
    );

    addButton.addEventListener(
        'click',
        function () {
            const index =
                nextIndex();

            const card =
                document.createElement(
                    'fieldset'
                );

            card.dataset.gameTravelModifier =
                '1';

            card.dataset.travelModifierIndex =
                String(index);

            card.innerHTML =
                '<legend data-game-travel-modifier-legend>Travel Modifier</legend>' +
                '<input type="hidden" name="travel_modifiers[' + index + '][id]" value="">' +
                '<p><label>Name<br>' +
                '<input type="text" name="travel_modifiers[' + index + '][name]" ' +
                'placeholder="Car" data-game-travel-modifier-name>' +
                '</label></p>' +
                '<p><label>Adjustment<br>' +
                '<select name="travel_modifiers[' + index + '][operation]">' +
                '<option value="add">Add</option>' +
                '<option value="subtract">Subtract</option>' +
                '</select> ' +
                '<input type="number" name="travel_modifiers[' + index + '][value]" ' +
                'min="0.000001" step="any" placeholder="5">' +
                '</label><br><small>Applied to the current Region\'s Base Distance Per Tick.</small></p>' +
                '<h3>Apply when</h3>' +
                '<p><small>No Conditions means this modifier always applies during dedicated Linear Travel.</small></p>' +
                '<div class="builder-condition-editor" data-condition-editor></div>' +
                '<p><button type="button" class="secondary-button" ' +
                'data-remove-game-travel-modifier>Remove Travel Modifier</button></p>';

            const conditionEditor =
                card.querySelector(
                    '[data-condition-editor]'
                );

            if (
                conditionEditor &&
                typeof window.wayfarerConditionCreateGroup ===
                    'function'
            ) {
                conditionEditor.appendChild(
                    window.wayfarerConditionCreateGroup(
                        'travel_modifiers[' +
                        index +
                        '][conditions]',
                        targets,
                        null,
                        true
                    )
                );

                if (
                    typeof window.wayfarerConditionInitializeEditor ===
                    'function'
                ) {
                    window.wayfarerConditionInitializeEditor(
                        conditionEditor,
                        targets
                    );
                }
            }

            list.appendChild(
                card
            );
        }
    );
})();


==============================================================================
FILE: assets/js/hierarchical-targets.js
==============================================================================

/*
 * Wayfarer Hierarchical Target Picker
 * WAYFARER_HIERARCHICAL_TARGETS_V80
 *
 * Progressive enhancement:
 * - The existing canonical <select> remains the submitted value.
 * - This component hides that flat list and presents:
 *       Type -> Target -> Property
 * - Every level has its own search box.
 * - Existing builder.js continues to read and react to the canonical select.
 * - MutationObserver support means newly-added Conditions/Effects are upgraded.
 *
 * Future target systems may provide:
 *   hierarchy: [
 *     { key: 'status', label: 'Status' },
 *     { key: 'scourge', label: 'Scourge Infection' },
 *     { key: 'active', label: 'Active' }
 *   ]
 *
 * No hierarchy UI rewrite is required when those target providers are added.
 */

(() => {
    'use strict';

    const VERSION = '85';

    function loadStyles() {
        if (
            document.querySelector(
                'link[data-wayfarer-hierarchy-style]'
            )
        ) {
            return;
        }

        const link =
            document.createElement(
                'link'
            );

        link.rel =
            'stylesheet';

        link.href =
            '/wayfarer/assets/css/hierarchical-targets.css?v=' +
            VERSION;

        link.dataset.wayfarerHierarchyStyle =
            VERSION;

        document.head.appendChild(
            link
        );
    }


    function parseJsonScript(script) {
        if (!script) {
            return null;
        }

        try {
            const parsed =
                JSON.parse(
                    script.textContent ||
                    '{}'
                );

            return (
                parsed &&
                typeof parsed === 'object'
            )
                ? parsed
                : null;

        } catch (error) {
            return null;
        }
    }


    function directJsonScript(
        host,
        selector
    ) {
        if (!host) {
            return null;
        }

        const children =
            Array.from(
                host.children ||
                []
            );

        for (const child of children) {
            if (
                child.matches &&
                child.matches(selector)
            ) {
                return child;
            }
        }

        return null;
    }


    function catalogFromFlatSelect(select) {
        const catalog = {};

        Array
            .from(
                select.options ||
                []
            )
            .forEach(
                function (option) {

                    if (!option.value) {
                        return;
                    }

                    const parent =
                        option.parentElement;

                    catalog[option.value] = {
                        label:
                            String(
                                option.textContent ||
                                option.value
                            ).trim(),
                        group:
                            parent &&
                            parent.tagName === 'OPTGROUP'
                                ? String(
                                    parent.label ||
                                    'Targets'
                                )
                                : 'Targets'
                    };
                }
            );

        return catalog;
    }


    function targetCatalog(select) {

        if (
            select.matches(
                '[data-condition-target]'
            )
        ) {
            const editor =
                select.closest(
                    '[data-condition-editor]'
                );

            let script =
                directJsonScript(
                    editor,
                    'script[data-condition-editor-targets-json]'
                );

            if (!script) {
                const effects =
                    select.closest(
                        '[data-builder-effects]'
                    );

                if (effects) {
                    script =
                        effects.querySelector(
                            'script[data-effect-condition-targets-json]'
                        );
                }
            }

            if (!script) {
                const ticks =
                    select.closest(
                        '[data-builder-tick-effects]'
                    );

                if (ticks) {
                    script =
                        ticks.querySelector(
                            'script[data-condition-targets-json]'
                        );
                }
            }

            const parsed =
                parseJsonScript(
                    script
                );

            if (parsed) {
                return parsed;
            }
        }


        if (
            select.matches(
                '[data-effect-target]'
            )
        ) {
            const wrapper =
                select.closest(
                    '[data-builder-effects]'
                );

            const parsed =
                parseJsonScript(
                    wrapper
                        ? wrapper.querySelector(
                            'script[data-effect-target-catalog-json]'
                        )
                        : null
                );

            if (parsed) {
                return parsed;
            }
        }


        if (
            select.matches(
                '[data-tick-effect-target]'
            )
        ) {
            const wrapper =
                select.closest(
                    '[data-builder-tick-effects]'
                );

            const parsed =
                parseJsonScript(
                    wrapper
                        ? wrapper.querySelector(
                            'script[data-tick-target-catalog-json]'
                        )
                        : null
                );

            if (parsed) {
                return parsed;
            }
        }


        return catalogFromFlatSelect(
            select
        );
    }


    function splitLabel(label) {
        const text =
            String(
                label ||
                ''
            ).trim();

        const marker =
            '→';

        const position =
            text.indexOf(
                marker
            );

        if (position < 0) {
            return [
                text,
                ''
            ];
        }

        return [
            text
                .slice(
                    0,
                    position
                )
                .trim(),
            text
                .slice(
                    position + marker.length
                )
                .trim()
        ];
    }


    function level(
        key,
        label
    ) {
        return {
            key:
                String(
                    key ||
                    label ||
                    ''
                ),
            label:
                String(
                    label ||
                    key ||
                    ''
                )
        };
    }


    function explicitHierarchy(definition) {
        if (
            !definition ||
            !Array.isArray(
                definition.hierarchy
            ) ||
            definition.hierarchy.length < 3
        ) {
            return null;
        }

        return definition
            .hierarchy
            .slice(0, 3)
            .map(
                function (entry, index) {

                    if (
                        entry &&
                        typeof entry === 'object'
                    ) {
                        return level(
                            entry.key ||
                                entry.id ||
                                ('level_' + index),
                            entry.label ||
                                entry.name ||
                                entry.key ||
                                entry.id
                        );
                    }

                    return level(
                        'level_' +
                            index +
                            ':' +
                            String(entry),
                        entry
                    );
                }
            );
    }


    function inferredHierarchy(
        key,
        definition
    ) {
        const explicit =
            explicitHierarchy(
                definition
            );

        if (explicit) {
            return explicit;
        }

        const scope =
            String(
                definition.target_scope ||
                definition.scope ||
                ''
            );

        const targetType =
            String(
                definition.target_type ||
                ''
            );

        const targetId =
            String(
                definition.target_id ||
                ''
            );

        const group =
            String(
                definition.group ||
                ''
            );

        const semantic =
            String(
                definition.semantic_type ||
                ''
            );

        const rawLabel =
            String(
                definition.label ||
                key
            );

        const labelParts =
            splitLabel(
                rawLabel
            );

        let ownerLabel =
            labelParts[0] ||
            rawLabel;

        let propertyLabel =
            labelParts[1] ||
            '';

        let typeKey =
            'other';

        let typeLabel =
            'Other';

        let ownerKey =
            scope ||
            group ||
            key;


        if (scope === 'game') {
            typeKey = 'game';
            typeLabel = 'Game';
            ownerKey = 'game';
            ownerLabel = 'Game';

        } else if (
            /^player:[0-9]+$/.test(scope)
        ) {
            typeKey = 'player';
            typeLabel = 'Player Character';

        } else if (
            /^region:[1-9][0-9]*$/.test(scope) ||
            scope === 'region'
        ) {
            typeKey = 'region';
            typeLabel = 'Region';

        } else if (
            /^location:[1-9][0-9]*$/.test(scope)
        ) {
            typeKey = 'location';
            typeLabel = 'Location';

        } else if (
            /^entity:[1-9][0-9]*$/.test(scope)
        ) {
            if (
                /^items?$/i.test(group)
            ) {
                typeKey = 'item';
                typeLabel = 'Item';

            } else if (
                /^characters?$/i.test(group)
            ) {
                typeKey = 'character';
                typeLabel = 'Character';

            } else {
                typeKey = 'entity';
                typeLabel = 'Entity';
            }

        } else if (
            scope === 'navigation' ||
            /^navigation:/.test(scope)
        ) {
            typeKey = 'navigation';
            typeLabel = 'Navigation';

            if (
                semantic ===
                'navigation_region_position'
            ) {
                ownerKey =
                    scope;

                ownerLabel =
                    rawLabel;

                propertyLabel =
                    'Position';

            } else if (
                semantic ===
                'navigation_location_anchor'
            ) {
                ownerKey =
                    'location:' +
                    targetId;

                ownerLabel =
                    rawLabel;

                propertyLabel =
                    'Location Anchor';

            } else {
                ownerKey =
                    scope ||
                    'navigation';

                ownerLabel =
                    group
                        .replace(
                            /^Navigation\s*[—-]\s*/i,
                            ''
                        )
                        .trim() ||
                    'Navigation';
            }

        } else if (scope === 'time') {
            typeKey = 'time';
            typeLabel = 'Time';
            ownerKey = 'game_clock';
            ownerLabel = 'Game Clock';
        }


        if (!propertyLabel) {
            if (targetType === 'trait') {
                propertyLabel =
                    targetId ||
                    'Trait';

            } else if (targetType === 'position') {
                propertyLabel =
                    'Position';

            } else if (targetType === 'location') {
                propertyLabel =
                    'Location';

            } else if (targetId) {
                propertyLabel =
                    targetId;

            } else {
                propertyLabel =
                    rawLabel;
            }
        }


        return [
            level(
                typeKey,
                typeLabel
            ),
            level(
                ownerKey,
                ownerLabel
            ),
            level(
                targetType +
                    ':' +
                    targetId,
                propertyLabel
            )
        ];
    }


    function buildEntries(
        select,
        catalog
    ) {
        const current =
            String(
                select.value ||
                ''
            );

        const entries = [];

        Object
            .entries(
                catalog ||
                {}
            )
            .forEach(
                function (pair) {

                    const key =
                        pair[0];

                    const definition =
                        (
                            pair[1] &&
                            typeof pair[1] === 'object'
                        )
                            ? pair[1]
                            : {};

                    const conditionTarget =
                        select.matches(
                            '[data-condition-target]'
                        );

                    const effectTarget =
                        select.matches(
                            '[data-effect-target], [data-tick-effect-target]'
                        );

                    if (
                        conditionTarget &&
                        definition.condition_hidden &&
                        key !== current
                    ) {
                        return;
                    }

                    if (
                        effectTarget &&
                        definition.effect_hidden &&
                        key !== current
                    ) {
                        return;
                    }

                    entries.push({
                        key: key,
                        definition: definition,
                        hierarchy:
                            inferredHierarchy(
                                key,
                                definition
                            )
                    });
                }
            );

        return entries;
    }


    function uniqueLevels(
        entries,
        hierarchyIndex
    ) {
        const found =
            new Map();

        entries.forEach(
            function (entry) {
                const item =
                    entry.hierarchy[
                        hierarchyIndex
                    ];

                if (
                    !item ||
                    found.has(
                        item.key
                    )
                ) {
                    return;
                }

                found.set(
                    item.key,
                    item
                );
            }
        );

        return Array.from(
            found.values()
        ).sort(
            function (a, b) {
                return a.label.localeCompare(
                    b.label,
                    undefined,
                    {
                        numeric: true,
                        sensitivity: 'base'
                    }
                );
            }
        );
    }


    function selectedEntry(
        entries,
        key
    ) {
        return entries.find(
            function (entry) {
                return entry.key === key;
            }
        ) || null;
    }


    function makeLevelControl(
        title,
        searchPlaceholder
    ) {
        const field =
            document.createElement(
                'div'
            );

        field.className =
            'wayfarer-hierarchy-level';

        const labelNode =
            document.createElement(
                'label'
            );

        labelNode.className =
            'wayfarer-hierarchy-label';

        labelNode.textContent =
            title;

        const search =
            document.createElement(
                'input'
            );

        search.type =
            'search';

        search.placeholder =
            searchPlaceholder;

        search.autocomplete =
            'off';

        search.className =
            'wayfarer-hierarchy-search';

        const select =
            document.createElement(
                'select'
            );

        select.className =
            'wayfarer-hierarchy-select';

        field.appendChild(
            labelNode
        );

        field.appendChild(
            search
        );

        field.appendChild(
            select
        );

        return {
            field: field,
            search: search,
            select: select
        };
    }


    function renderOptions(
        select,
        options,
        placeholder,
        selectedKey,
        query
    ) {
        const filter =
            String(
                query ||
                ''
            )
                .trim()
                .toLowerCase();

        select.innerHTML =
            '';

        const blank =
            document.createElement(
                'option'
            );

        blank.value =
            '';

        blank.textContent =
            placeholder;

        select.appendChild(
            blank
        );

        let selectedStillVisible =
            false;

        options.forEach(
            function (option) {

                const matches =
                    filter === '' ||
                    option.label
                        .toLowerCase()
                        .includes(
                            filter
                        ) ||
                    option.key
                        .toLowerCase()
                        .includes(
                            filter
                        );

                if (
                    !matches &&
                    option.key !== selectedKey
                ) {
                    return;
                }

                const node =
                    document.createElement(
                        'option'
                    );

                node.value =
                    option.key;

                node.textContent =
                    option.label;

                select.appendChild(
                    node
                );

                if (
                    option.key === selectedKey
                ) {
                    selectedStillVisible =
                        true;
                }
            }
        );

        if (
            selectedKey &&
            selectedStillVisible
        ) {
            select.value =
                selectedKey;
        } else {
            select.value =
                '';
        }
    }


    function dispatchCanonicalChange(
        canonical
    ) {
        canonical.dispatchEvent(
            new Event(
                'change',
                {
                    bubbles: true
                }
            )
        );
    }


    function enhanceSelect(
        canonical
    ) {
        if (
            !canonical ||
            canonical.dataset
                .wayfarerHierarchyEnhanced ===
                VERSION
        ) {
            return;
        }

        const catalog =
            targetCatalog(
                canonical
            );

        const entries =
            buildEntries(
                canonical,
                catalog
            );

        if (!entries.length) {
            return;
        }

        canonical.dataset
            .wayfarerHierarchyEnhanced =
            VERSION;

        canonical.classList.add(
            'wayfarer-hierarchy-canonical'
        );

        canonical.hidden =
            true;

        const host =
            document.createElement(
                'div'
            );

        host.className =
            'wayfarer-hierarchy-picker';

        host.dataset
            .wayfarerHierarchyPicker =
            VERSION;

        const type =
            makeLevelControl(
                'Type',
                'Search types…'
            );

        const target =
            makeLevelControl(
                'Target',
                'Search targets…'
            );

        const property =
            makeLevelControl(
                'Property',
                'Search properties…'
            );

        host.appendChild(
            type.field
        );

        host.appendChild(
            target.field
        );

        host.appendChild(
            property.field
        );

        /* WAYFARER_HIERARCHICAL_LAYOUT_V81 */
        const sourceLabel =
            canonical.closest(
                'label'
            );

        const conditionRow =
            canonical.closest(
                '.builder-condition-row'
            );

        const effectHeader =
            canonical.closest(
                '.builder-tick-effect-header'
            );

        if (conditionRow) {
            conditionRow.classList.add(
                'has-wayfarer-hierarchy'
            );
        }

        if (effectHeader) {
            effectHeader.classList.add(
                'has-wayfarer-hierarchy'
            );
        }

        /*
         * V80 inserted the picker immediately after the canonical <select>.
         * Because that select lives inside the original Target <label>, the
         * generated Type/Target/Property labels became nested labels. Move the
         * picker outside that source label and hide only the obsolete wrapper.
         * The canonical select remains present and submits exactly as before.
         */
        if (
            sourceLabel &&
            sourceLabel.contains(
                canonical
            )
        ) {
            sourceLabel.classList.add(
                'wayfarer-hierarchy-source-label'
            );

            sourceLabel.insertAdjacentElement(
                'afterend',
                host
            );
        } else {
            canonical.insertAdjacentElement(
                'afterend',
                host
            );
        }

        let typeKey = '';
        let targetKey = '';
        let propertyKey = '';


        function matchingEntries() {
            return entries.filter(
                function (entry) {
                    return (
                        (!typeKey ||
                            entry.hierarchy[0].key ===
                                typeKey) &&
                        (!targetKey ||
                            entry.hierarchy[1].key ===
                                targetKey)
                    );
                }
            );
        }


        function renderType() {
            renderOptions(
                type.select,
                uniqueLevels(
                    entries,
                    0
                ),
                'Select type…',
                typeKey,
                type.search.value
            );
        }


        function renderTarget() {
            const candidates =
                typeKey
                    ? entries.filter(
                        function (entry) {
                            return (
                                entry.hierarchy[0].key ===
                                typeKey
                            );
                        }
                    )
                    : [];

            target.field.hidden =
                !typeKey;

            if (!typeKey) {
                target.select.innerHTML =
                    '';
                return;
            }

            renderOptions(
                target.select,
                uniqueLevels(
                    candidates,
                    1
                ),
                'Select target…',
                targetKey,
                target.search.value
            );
        }


        function renderProperty() {
            const candidates =
                (
                    typeKey &&
                    targetKey
                )
                    ? matchingEntries()
                    : [];

            property.field.hidden =
                !typeKey ||
                !targetKey;

            if (
                !typeKey ||
                !targetKey
            ) {
                property.select.innerHTML =
                    '';
                return;
            }

            renderOptions(
                property.select,
                uniqueLevels(
                    candidates,
                    2
                ),
                'Select property…',
                propertyKey,
                property.search.value
            );
        }


        function clearCanonical() {
            if (
                canonical.value !==
                ''
            ) {
                canonical.value =
                    '';

                dispatchCanonicalChange(
                    canonical
                );
            }
        }


        function applyCanonical() {
            if (
                !typeKey ||
                !targetKey ||
                !propertyKey
            ) {
                clearCanonical();
                return;
            }

            const match =
                entries.find(
                    function (entry) {
                        return (
                            entry.hierarchy[0].key ===
                                typeKey &&
                            entry.hierarchy[1].key ===
                                targetKey &&
                            entry.hierarchy[2].key ===
                                propertyKey
                        );
                    }
                );

            const next =
                match
                    ? match.key
                    : '';

            if (
                canonical.value !==
                next
            ) {
                canonical.value =
                    next;

                dispatchCanonicalChange(
                    canonical
                );
            }
        }


        type.search.addEventListener(
            'input',
            renderType
        );

        target.search.addEventListener(
            'input',
            renderTarget
        );

        property.search.addEventListener(
            'input',
            renderProperty
        );


        type.select.addEventListener(
            'change',
            function () {
                typeKey =
                    type.select.value;

                targetKey =
                    '';

                propertyKey =
                    '';

                target.search.value =
                    '';

                property.search.value =
                    '';

                clearCanonical();
                renderTarget();
                renderProperty();
            }
        );


        target.select.addEventListener(
            'change',
            function () {
                targetKey =
                    target.select.value;

                propertyKey =
                    '';

                property.search.value =
                    '';

                clearCanonical();
                renderProperty();
            }
        );


        property.select.addEventListener(
            'change',
            function () {
                propertyKey =
                    property.select.value;

                applyCanonical();
            }
        );


        const initial =
            selectedEntry(
                entries,
                String(
                    canonical.value ||
                    ''
                )
            );

        if (initial) {
            typeKey =
                initial.hierarchy[0].key;

            targetKey =
                initial.hierarchy[1].key;

            propertyKey =
                initial.hierarchy[2].key;
        }

        renderType();
        renderTarget();
        renderProperty();
    }


    function syncStoryletTransitionEffectRow(
        canonical
    ) {
        if (
            !canonical ||
            !canonical.matches ||
            !canonical.matches(
                'select[data-effect-target]'
            )
        ) {
            return;
        }

        const wrapper =
            canonical.closest(
                '[data-builder-effects]'
            );

        const script =
            wrapper
                ? wrapper.querySelector(
                    'script[data-effect-target-catalog-json]'
                )
                : null;

        const catalog =
            parseJsonScript(
                script
            ) || {};

        const definition =
            catalog[
                canonical.value
            ] || {};

        const isTransition =
            String(
                definition.semantic_type ||
                ''
            ) ===
                'storylet_transition';

        const row =
            canonical.closest(
                '[data-effect-row]'
            );

        if (!row) {
            return;
        }

        row.classList.toggle(
            'is-storylet-transition-effect',
            isTransition
        );

        row.querySelectorAll(
            '[data-effect-branch]'
        ).forEach(
            function (branch) {
                const operation =
                    branch.querySelector(
                        '[data-effect-branch-operation]'
                    );

                const modeWrap =
                    branch.querySelector(
                        '[data-effect-value-mode-wrap]'
                    );

                const fixedWrap =
                    branch.querySelector(
                        '[data-effect-fixed-wrap]'
                    );

                const randomWrap =
                    branch.querySelector(
                        '[data-effect-random-wrap]'
                    );

                if (!isTransition) {
                    return;
                }

                if (operation) {
                    const continueOption =
                        Array.from(
                            operation.options ||
                            []
                        ).find(
                            function (option) {
                                return option.value ===
                                    'continue';
                            }
                        );

                    if (continueOption) {
                        continueOption.textContent =
                            'Continue';
                    }

                    if (
                        operation.value !== 'none'
                    ) {
                        operation.value =
                            'continue';
                    }
                }

                [
                    modeWrap,
                    fixedWrap,
                    randomWrap
                ].forEach(
                    function (container) {
                        if (!container) {
                            return;
                        }

                        container.hidden =
                            true;

                        container
                            .querySelectorAll(
                                'input, select'
                            )
                            .forEach(
                                function (field) {
                                    field.disabled =
                                        true;
                                }
                            );
                    }
                );
            }
        );
    }


    function syncStoryletTransitionWithin(
        root
    ) {
        if (!root) {
            return;
        }

        if (
            root.matches &&
            root.matches(
                'select[data-effect-target]'
            )
        ) {
            syncStoryletTransitionEffectRow(
                root
            );
        }

        if (!root.querySelectorAll) {
            return;
        }

        root.querySelectorAll(
            'select[data-effect-target]'
        ).forEach(
            syncStoryletTransitionEffectRow
        );
    }


    function enhanceWithin(root) {
        if (!root) {
            return;
        }

        if (
            root.matches &&
            root.matches(
                'select[data-condition-target], ' +
                'select[data-effect-target], ' +
                'select[data-tick-effect-target]'
            )
        ) {
            enhanceSelect(
                root
            );
        }

        if (!root.querySelectorAll) {
            return;
        }

        root.querySelectorAll(
            'select[data-condition-target], ' +
            'select[data-effect-target], ' +
            'select[data-tick-effect-target]'
        ).forEach(
            enhanceSelect
        );

        syncStoryletTransitionWithin(
            root
        );
    }


    function start() {
        loadStyles();

        enhanceWithin(
            document
        );

        document.addEventListener(
            'change',
            function (event) {
                if (
                    event.target &&
                    event.target.matches &&
                    event.target.matches(
                        'select[data-effect-target]'
                    )
                ) {
                    window.setTimeout(
                        function () {
                            syncStoryletTransitionEffectRow(
                                event.target
                            );
                        },
                        0
                    );
                }

                if (
                    event.target &&
                    event.target.matches &&
                    event.target.matches(
                        '[data-effect-branch-operation]'
                    )
                ) {
                    const row =
                        event.target.closest(
                            '[data-effect-row]'
                        );

                    const target =
                        row
                            ? row.querySelector(
                                'select[data-effect-target]'
                            )
                            : null;

                    if (target) {
                        window.setTimeout(
                            function () {
                                syncStoryletTransitionEffectRow(
                                    target
                                );
                            },
                            0
                        );
                    }
                }
            }
        );

        const observer =
            new MutationObserver(
                function (mutations) {

                    mutations.forEach(
                        function (mutation) {

                            mutation.addedNodes
                                .forEach(
                                    function (node) {
                                        if (
                                            node.nodeType ===
                                            Node.ELEMENT_NODE
                                        ) {
                                            enhanceWithin(
                                                node
                                            );
                                        }
                                    }
                                );
                        }
                    );
                }
            );

        observer.observe(
            document.body,
            {
                childList: true,
                subtree: true
            }
        );
    }


    if (
        document.readyState ===
        'loading'
    ) {
        document.addEventListener(
            'DOMContentLoaded',
            start,
            {
                once: true
            }
        );
    } else {
        start();
    }

})();


==============================================================================
FILE: assets/js/starting-choices.js
==============================================================================

/*
|--------------------------------------------------------------------------
| Starting Choices Editor
|--------------------------------------------------------------------------
| WAYFARER_STARTING_CHOICES_V36
|--------------------------------------------------------------------------
*/

(function () {

    const editor =
        document.querySelector(
            '[data-starting-choices-editor]'
        );

    if (!editor) {
        return;
    }

    const list =
        editor.querySelector(
            '[data-starting-choices-list]'
        );

    const choiceTemplate =
        editor.querySelector(
            '[data-starting-choice-template]'
        );

    const optionTemplate =
        editor.querySelector(
            '[data-starting-option-template]'
        );

    const effectTemplate =
        editor.querySelector(
            '[data-starting-effect-template]'
        );

    /* WAYFARER_STARTING_CHOICE_DATATYPE_UI_V58 */
    let runtimeTargets = {};

    const runtimeTargetsJson =
        editor.querySelector(
            '[data-starting-runtime-targets-json]'
        );

    if (runtimeTargetsJson) {
        try {
            runtimeTargets =
                JSON.parse(
                    runtimeTargetsJson.textContent ||
                    '{}'
                );
        } catch (error) {
            runtimeTargets = {};
        }
    }


    function ensureChoiceSelect(
        fixedWrap,
        fixedInput
    ) {

        if (!fixedWrap || !fixedInput) {
            return null;
        }

        let select =
            fixedWrap.querySelector(
                '[data-starting-fixed-choice]'
            );

        if (!select) {
            select =
                document.createElement(
                    'select'
                );

            select.dataset.startingFixedChoice =
                '1';

            select.dataset.startingEffectField =
                'value';

            select.name =
                fixedInput.name;

            select.hidden =
                true;

            select.disabled =
                true;

            fixedWrap.appendChild(
                select
            );
        }

        select.name =
            fixedInput.name;

        return select;
    }


    function updateStartingEffect(
        effect
    ) {

        if (!effect) {
            return;
        }

        const target =
            effect.querySelector(
                '[data-starting-effect-target]'
            );

        const operation =
            effect.querySelector(
                '[data-starting-effect-operation]'
            );

        const modeWrap =
            effect.querySelector(
                '[data-starting-value-mode-wrap]'
            );

        const mode =
            effect.querySelector(
                '[data-starting-value-mode]'
            );

        const fixedWrap =
            effect.querySelector(
                '[data-starting-fixed-wrap]'
            );

        const fixedInput =
            effect.querySelector(
                '[data-starting-fixed-input]'
            );

        const randomWrap =
            effect.querySelector(
                '[data-starting-random-wrap]'
            );

        if (!target || !operation) {
            return;
        }

        const definition =
            runtimeTargets[target.value] ||
            {};

        let dataType =
            String(
                definition.data_type ||
                definition.trait_type ||
                'number'
            ).toLowerCase();

        if (dataType === 'binary') {
            dataType = 'boolean';
        }

        const allowedOperations =
            Array.isArray(
                definition.effect_operations
            ) &&
            definition.effect_operations.length
                ? definition.effect_operations
                : (
                    dataType === 'number'
                        ? ['set', 'add', 'subtract']
                        : ['set']
                );

        const supportsRandom =
            Object.prototype.hasOwnProperty.call(
                definition,
                'supports_random'
            )
                ? Boolean(
                    definition.supports_random
                )
                : dataType === 'number';

        const previousOperation =
            operation.value;

        operation.innerHTML =
            '';

        const operationLabels = {
            set: 'Set',
            add: 'Add',
            subtract: 'Subtract'
        };

        allowedOperations.forEach(
            function (operationValue) {

                const option =
                    document.createElement(
                        'option'
                    );

                option.value =
                    operationValue;

                option.textContent =
                    operationLabels[operationValue] ||
                    operationValue;

                operation.appendChild(
                    option
                );
            }
        );

        operation.value =
            allowedOperations.includes(
                previousOperation
            )
                ? previousOperation
                : allowedOperations[0];

        let valueMode =
            mode
                ? mode.value
                : 'fixed';

        if (!supportsRandom) {
            valueMode =
                'fixed';

            if (mode) {
                mode.value =
                    'fixed';
            }
        }

        if (modeWrap) {
            modeWrap.hidden =
                !supportsRandom;

            if (mode) {
                mode.disabled =
                    !supportsRandom;
            }
        }

        const showFixed =
            !supportsRandom ||
            valueMode === 'fixed';

        if (fixedWrap) {
            fixedWrap.hidden =
                !showFixed;
        }

        const choiceSelect =
            ensureChoiceSelect(
                fixedWrap,
                fixedInput
            );

        const valueOptions =
            definition.value_options &&
            typeof definition.value_options === 'object'
                ? definition.value_options
                : null;

        if (
            showFixed &&
            valueOptions &&
            fixedInput &&
            choiceSelect
        ) {
            const previousValue =
                choiceSelect.hidden
                    ? fixedInput.value
                    : choiceSelect.value;

            choiceSelect.innerHTML =
                '';

            Object
                .entries(valueOptions)
                .forEach(
                    function (entry) {

                        const option =
                            document.createElement(
                                'option'
                            );

                        option.value =
                            entry[0];

                        option.textContent =
                            entry[1];

                        choiceSelect.appendChild(
                            option
                        );
                    }
                );

            if (
                Object.prototype.hasOwnProperty.call(
                    valueOptions,
                    String(previousValue)
                )
            ) {
                choiceSelect.value =
                    String(previousValue);
            }

            choiceSelect.hidden =
                false;

            choiceSelect.disabled =
                false;

            fixedInput.hidden =
                true;

            fixedInput.disabled =
                true;

        } else {
            if (
                choiceSelect &&
                fixedInput &&
                !choiceSelect.hidden
            ) {
                fixedInput.value =
                    choiceSelect.value;
            }

            if (choiceSelect) {
                choiceSelect.hidden =
                    true;

                choiceSelect.disabled =
                    true;
            }

            if (fixedInput) {
                fixedInput.hidden =
                    !showFixed;

                fixedInput.disabled =
                    !showFixed;

                fixedInput.type =
                    dataType === 'number'
                        ? 'number'
                        : 'text';

                if (dataType === 'number') {
                    fixedInput.step =
                        'any';
                } else {
                    fixedInput.removeAttribute(
                        'step'
                    );
                }
            }
        }

        if (randomWrap) {
            const showRandom =
                supportsRandom &&
                valueMode === 'random';

            randomWrap.hidden =
                !showRandom;

            randomWrap
                .querySelectorAll(
                    'input'
                )
                .forEach(
                    function (field) {
                        field.disabled =
                            !showRandom;
                    }
                );
        }
    }


    function cloneTemplate(template) {

        if (!template) {
            return null;
        }

        const fragment =
            template.content.cloneNode(
                true
            );

        return fragment.firstElementChild;
    }


    function reindex() {

        if (!list) {
            return;
        }

        Array
            .from(
                list.querySelectorAll(
                    ':scope > [data-starting-choice]'
                )
            )
            .forEach(
                function (
                    choice,
                    choiceIndex
                ) {

                    choice
                        .querySelectorAll(
                            '[data-starting-choice-field]'
                        )
                        .forEach(
                            function (field) {
                                field.name =
                                    'setup_choices[' +
                                    choiceIndex +
                                    '][' +
                                    field.dataset.startingChoiceField +
                                    ']';
                            }
                        );

                    Array
                        .from(
                            choice.querySelectorAll(
                                ':scope > [data-starting-options-list] > [data-starting-option]'
                            )
                        )
                        .forEach(
                            function (
                                option,
                                optionIndex
                            ) {

                                option
                                    .querySelectorAll(
                                        '[data-starting-option-field]'
                                    )
                                    .forEach(
                                        function (field) {
                                            field.name =
                                                'setup_choices[' +
                                                choiceIndex +
                                                '][options][' +
                                                optionIndex +
                                                '][' +
                                                field.dataset.startingOptionField +
                                                ']';
                                        }
                                    );

                                Array
                                    .from(
                                        option.querySelectorAll(
                                            ':scope .builder-starting-effects > [data-starting-effects-list] > [data-starting-effect]'
                                        )
                                    )
                                    .forEach(
                                        function (
                                            effect,
                                            effectIndex
                                        ) {

                                            effect
                                                .querySelectorAll(
                                                    '[data-starting-effect-field]'
                                                )
                                                .forEach(
                                                    function (field) {
                                                        field.name =
                                                            'setup_choices[' +
                                                            choiceIndex +
                                                            '][options][' +
                                                            optionIndex +
                                                            '][effects][' +
                                                            effectIndex +
                                                            '][' +
                                                            field.dataset.startingEffectField +
                                                            ']';
                                                    }
                                                );
                                        }
                                    );
                            }
                        );
                }
            );
    }


    const addChoice =
        editor.querySelector(
            '[data-add-starting-choice]'
        );

    if (addChoice && list) {

        addChoice.addEventListener(
            'click',
            function () {

                const choice =
                    cloneTemplate(
                        choiceTemplate
                    );

                if (!choice) {
                    return;
                }

                list.appendChild(
                    choice
                );

                const optionList =
                    choice.querySelector(
                        '[data-starting-options-list]'
                    );

                const firstOption =
                    cloneTemplate(
                        optionTemplate
                    );

                if (
                    optionList &&
                    firstOption
                ) {
                    optionList.appendChild(
                        firstOption
                    );
                }

                reindex();

                const prompt =
                    choice.querySelector(
                        '[data-starting-choice-field="prompt"]'
                    );

                if (prompt) {
                    prompt.focus();
                }
            }
        );
    }


    editor.addEventListener(
        'click',
        function (event) {

            const removeChoice =
                event.target.closest(
                    '[data-remove-starting-choice]'
                );

            if (removeChoice) {

                const choice =
                    removeChoice.closest(
                        '[data-starting-choice]'
                    );

                if (
                    choice &&
                    window.confirm(
                        'Remove this Starting Choice?'
                    )
                ) {
                    choice.remove();
                    reindex();
                }

                return;
            }


            const addOption =
                event.target.closest(
                    '[data-add-starting-option]'
                );

            if (addOption) {

                const choice =
                    addOption.closest(
                        '[data-starting-choice]'
                    );

                const optionList =
                    choice
                        ? choice.querySelector(
                            '[data-starting-options-list]'
                        )
                        : null;

                const option =
                    cloneTemplate(
                        optionTemplate
                    );

                if (
                    optionList &&
                    option
                ) {
                    optionList.appendChild(
                        option
                    );

                    reindex();

                    const label =
                        option.querySelector(
                            '[data-starting-option-field="label"]'
                        );

                    if (label) {
                        label.focus();
                    }
                }

                return;
            }


            const removeOption =
                event.target.closest(
                    '[data-remove-starting-option]'
                );

            if (removeOption) {

                const option =
                    removeOption.closest(
                        '[data-starting-option]'
                    );

                if (
                    option &&
                    window.confirm(
                        'Remove this option?'
                    )
                ) {
                    option.remove();
                    reindex();
                }

                return;
            }


            const addEffect =
                event.target.closest(
                    '[data-add-starting-effect]'
                );

            if (addEffect) {

                const option =
                    addEffect.closest(
                        '[data-starting-option]'
                    );

                const effectsList =
                    option
                        ? option.querySelector(
                            '[data-starting-effects-list]'
                        )
                        : null;

                const effect =
                    cloneTemplate(
                        effectTemplate
                    );

                if (
                    effectsList &&
                    effect
                ) {
                    effectsList.appendChild(
                        effect
                    );
                    reindex();
                    updateStartingEffect(
                        effect
                    );
                }

                return;
            }


            const removeEffect =
                event.target.closest(
                    '[data-remove-starting-effect]'
                );

            if (removeEffect) {

                const effect =
                    removeEffect.closest(
                        '[data-starting-effect]'
                    );

                if (effect) {
                    effect.remove();
                    reindex();
                }
            }
        }
    );


    editor.addEventListener(
        'change',
        function (event) {

            const relevant =
                event.target.closest(
                    '[data-starting-effect-target], ' +
                    '[data-starting-effect-operation], ' +
                    '[data-starting-value-mode]'
                );

            if (!relevant) {
                return;
            }

            updateStartingEffect(
                relevant.closest(
                    '[data-starting-effect]'
                )
            );
        }
    );


    reindex();

    editor
        .querySelectorAll(
            '[data-starting-effect]'
        )
        .forEach(
            updateStartingEffect
        );

})();



==============================================================================
FILE: assets/js/status-lifecycle.js
==============================================================================

/* WAYFARER_STATUS_LIFECYCLE_UI_V88 */
(function () {
    'use strict';

    function randomKey(prefix) {
        const random = Math.random().toString(36).slice(2, 10);
        const time = Date.now().toString(36);
        return prefix + '_' + time + '_' + random;
    }

    function initializeStatusLifecycle() {
        const host = document.querySelector('[data-builder-status-lifecycle]');
        if (!host || host.dataset.statusLifecycleReady === '1') {
            return;
        }

        host.dataset.statusLifecycleReady = '1';

        const mode = host.querySelector('[data-status-lifecycle-mode]');
        const stagesWrap = host.querySelector('[data-status-lifecycle-stages-wrap]');
        const stagesList = host.querySelector('[data-status-stages-list]');
        const stageTemplate = host.querySelector('[data-status-stage-template]');
        const outcomeTemplate = host.querySelector('[data-status-outcome-template]');
        const addStageButton = host.querySelector('[data-add-status-stage]');

        if (!mode || !stagesWrap || !stagesList || !stageTemplate || !outcomeTemplate) {
            return;
        }

        function stageRows() {
            return Array.from(stagesList.children).filter(function (node) {
                return node.matches && node.matches('[data-status-stage]');
            });
        }

        function outcomeRows(stage) {
            const list = stage.querySelector('[data-status-outcomes-list]');
            if (!list) {
                return [];
            }
            return Array.from(list.children).filter(function (node) {
                return node.matches && node.matches('[data-status-outcome]');
            });
        }

        function refreshDuration(stage) {
            const selector = stage.querySelector('[data-status-duration-mode]');
            const modeValue = selector ? selector.value : 'fixed';

            stage.querySelectorAll('[data-status-duration-fixed]').forEach(function (node) {
                node.hidden = modeValue !== 'fixed';
                node.querySelectorAll('input, select, textarea').forEach(function (field) {
                    field.disabled = modeValue !== 'fixed';
                });
            });

            stage.querySelectorAll('[data-status-duration-random]').forEach(function (node) {
                node.hidden = modeValue !== 'random';
                node.querySelectorAll('input, select, textarea').forEach(function (field) {
                    field.disabled = modeValue !== 'random';
                });
            });
        }

        function refreshPresentation(outcome) {
            const selector = outcome.querySelector('[data-status-outcome-presentation]');
            const storylet = outcome.querySelector('[data-status-outcome-storylet]');
            const isStorylet = selector && selector.value === 'storylet';

            if (storylet) {
                storylet.hidden = !isStorylet;
                storylet.querySelectorAll('select, input, textarea').forEach(function (field) {
                    field.disabled = !isStorylet;
                });
            }
        }

        function stageCatalog() {
            return stageRows().map(function (stage, index) {
                const keyField = stage.querySelector('[data-status-stage-key]');
                const nameField = stage.querySelector('[data-status-stage-name]');
                return {
                    key: keyField ? String(keyField.value || '') : '',
                    name: nameField && String(nameField.value || '').trim() !== ''
                        ? String(nameField.value).trim()
                        : 'Stage ' + (index + 1)
                };
            }).filter(function (row) {
                return row.key !== '';
            });
        }

        function refreshOutcomeResults() {
            const catalog = stageCatalog();

            stageRows().forEach(function (stage) {
                outcomeRows(stage).forEach(function (outcome) {
                    const select = outcome.querySelector('[data-status-outcome-result]');
                    if (!select) {
                        return;
                    }

                    const previous = select.value || 'inactive';
                    select.innerHTML = '';

                    const inactive = document.createElement('option');
                    inactive.value = 'inactive';
                    inactive.textContent = 'End Status (Inactive)';
                    select.appendChild(inactive);

                    const stay = document.createElement('option');
                    stay.value = 'stay';
                    stay.textContent = 'Stay in this Stage / Restart Timer';
                    select.appendChild(stay);

                    catalog.forEach(function (row) {
                        const option = document.createElement('option');
                        option.value = 'stage:' + row.key;
                        option.textContent = 'Go to Stage: ' + row.name;
                        select.appendChild(option);
                    });

                    const exists = Array.from(select.options).some(function (option) {
                        return option.value === previous;
                    });
                    select.value = exists ? previous : 'inactive';
                });
            });
        }

        function reindex() {
            const stages = stageRows();

            stages.forEach(function (stage, stageIndex) {
                stage.dataset.stageIndex = String(stageIndex);

                const heading = stage.querySelector('[data-status-stage-heading]') ||
                    stage.querySelector('.wayfarer-status-stage-heading > strong');
                if (heading) {
                    heading.textContent = 'Stage ' + (stageIndex + 1) +
                        (stageIndex === 0 ? ' — Initial' : '');
                }

                stage.querySelectorAll('[data-status-field]').forEach(function (field) {
                    const key = field.dataset.statusField;
                    if (key) {
                        field.name = 'status_lifecycle[stages][' + stageIndex + '][' + key + ']';
                    }
                });

                outcomeRows(stage).forEach(function (outcome, outcomeIndex) {
                    outcome.dataset.outcomeIndex = String(outcomeIndex);

                    outcome.querySelectorAll('[data-status-outcome-field]').forEach(function (field) {
                        const key = field.dataset.statusOutcomeField;
                        if (key) {
                            field.name = 'status_lifecycle[stages][' + stageIndex + '][outcomes][' + outcomeIndex + '][' + key + ']';
                        }
                    });

                    refreshPresentation(outcome);
                });

                const up = stage.querySelector('[data-move-status-stage-up]');
                const down = stage.querySelector('[data-move-status-stage-down]');
                if (up) {
                    up.disabled = stageIndex === 0;
                }
                if (down) {
                    down.disabled = stageIndex === stages.length - 1;
                }

                refreshDuration(stage);
            });

            refreshOutcomeResults();
        }

        function addOutcome(stage) {
            const list = stage.querySelector('[data-status-outcomes-list]');
            if (!list) {
                return;
            }

            const fragment = outcomeTemplate.content.cloneNode(true);
            const outcome = fragment.querySelector('[data-status-outcome]');
            if (!outcome) {
                return;
            }

            const key = outcome.querySelector('[data-status-outcome-key]');
            if (key) {
                key.value = randomKey('outcome');
            }

            list.appendChild(outcome);
            reindex();
        }

        function addStage() {
            const fragment = stageTemplate.content.cloneNode(true);
            const stage = fragment.querySelector('[data-status-stage]');
            if (!stage) {
                return;
            }

            const key = stage.querySelector('[data-status-stage-key]');
            if (key) {
                key.value = randomKey('stage');
            }

            stagesList.appendChild(stage);
            addOutcome(stage);
            reindex();
        }

        function refreshMode() {
            const progression = mode.value === 'progression';
            stagesWrap.hidden = !progression;

            stagesWrap.querySelectorAll('input, select, textarea, button').forEach(function (field) {
                field.disabled = !progression;
            });

            if (progression) {
                if (stageRows().length === 0) {
                    addStage();
                }
                reindex();
            }
        }

        mode.addEventListener('change', refreshMode);

        if (addStageButton) {
            addStageButton.addEventListener('click', addStage);
        }

        host.addEventListener('click', function (event) {
            const addOutcomeButton = event.target.closest('[data-add-status-outcome]');
            if (addOutcomeButton) {
                const stage = addOutcomeButton.closest('[data-status-stage]');
                if (stage) {
                    addOutcome(stage);
                }
                return;
            }

            const removeOutcomeButton = event.target.closest('[data-remove-status-outcome]');
            if (removeOutcomeButton) {
                const outcome = removeOutcomeButton.closest('[data-status-outcome]');
                if (outcome && window.confirm('Remove this Status Outcome?')) {
                    outcome.remove();
                    reindex();
                }
                return;
            }

            const removeStageButton = event.target.closest('[data-remove-status-stage]');
            if (removeStageButton) {
                const stage = removeStageButton.closest('[data-status-stage]');
                if (stage && window.confirm('Remove this Status Stage and its Outcomes?')) {
                    stage.remove();
                    reindex();
                }
                return;
            }

            const upButton = event.target.closest('[data-move-status-stage-up]');
            if (upButton) {
                const stage = upButton.closest('[data-status-stage]');
                if (stage && stage.previousElementSibling) {
                    stagesList.insertBefore(stage, stage.previousElementSibling);
                    reindex();
                }
                return;
            }

            const downButton = event.target.closest('[data-move-status-stage-down]');
            if (downButton) {
                const stage = downButton.closest('[data-status-stage]');
                if (stage && stage.nextElementSibling) {
                    stagesList.insertBefore(stage.nextElementSibling, stage);
                    reindex();
                }
            }
        });

        host.addEventListener('change', function (event) {
            const stage = event.target.closest('[data-status-stage]');
            const outcome = event.target.closest('[data-status-outcome]');

            if (event.target.matches('[data-status-duration-mode]') && stage) {
                refreshDuration(stage);
            }

            if (event.target.matches('[data-status-outcome-presentation]') && outcome) {
                refreshPresentation(outcome);
            }

            if (
                event.target.matches('[data-status-stage-name]') ||
                event.target.matches('[data-status-stage-key]')
            ) {
                refreshOutcomeResults();
            }
        });

        reindex();
        refreshMode();
    }

    initializeStatusLifecycle();
})();



==============================================================================
FILE: assets/js/status-subject-effects.js
==============================================================================

/* WAYFARER_STATUS_SUBJECT_EFFECTS_UI_V89 */
(function () {
    'use strict';

    function randomKey(prefix) {
        const random = Math.random().toString(36).slice(2, 10);
        const time = Date.now().toString(36);
        return prefix + '_' + time + '_' + random;
    }

    const host = document.querySelector('[data-builder-status-lifecycle]');
    if (!host || host.dataset.statusSubjectEffectsReady === '1') {
        return;
    }

    host.dataset.statusSubjectEffectsReady = '1';

    const stagesList = host.querySelector('[data-status-stages-list]');
    const effectTemplate = host.querySelector('[data-status-effect-template]');
    const recurringEffectTemplate = host.querySelector('[data-status-recurring-effect-template]');

    if (!stagesList || !effectTemplate || !recurringEffectTemplate) {
        return;
    }

    function stageRows() {
        return Array.from(stagesList.children).filter(function (node) {
            return node.matches && node.matches('[data-status-stage]');
        });
    }

    function outcomeRows(stage) {
        const list = stage.querySelector('[data-status-outcomes-list]');
        return list
            ? Array.from(list.children).filter(function (node) {
                return node.matches && node.matches('[data-status-outcome]');
            })
            : [];
    }

    function effectRows(list) {
        return list
            ? Array.from(list.children).filter(function (node) {
                return node.matches && node.matches('[data-status-effect]');
            })
            : [];
    }

    function selectedTraitType(effect) {
        const target = effect.querySelector('[data-status-effect-target]');
        const option = target && target.options[target.selectedIndex];
        return option && option.dataset.statusTraitType === 'boolean'
            ? 'boolean'
            : 'number';
    }

    function setControlVisible(container, visible) {
        if (!container) {
            return;
        }

        container.hidden = !visible;
        container.querySelectorAll('input, select, textarea').forEach(function (field) {
            field.disabled = !visible;
        });
    }

    function refreshEffect(effect) {
        const dataType = selectedTraitType(effect);
        const operation = effect.querySelector('[data-status-effect-operation]');
        const valueMode = effect.querySelector('[data-status-effect-value-mode]');
        const modeWrap = effect.querySelector('[data-status-effect-value-mode-wrap]');
        const fixedNumber = effect.querySelector('[data-status-effect-fixed-number]');
        const fixedBoolean = effect.querySelector('[data-status-effect-fixed-boolean]');
        const randomMin = effect.querySelector('[data-status-effect-random-min]');
        const randomMax = effect.querySelector('[data-status-effect-random-max]');

        if (operation) {
            Array.from(operation.options).forEach(function (option) {
                const numberOnly = option.hasAttribute('data-status-number-operation');
                const allowed = dataType === 'number' || !numberOnly;
                option.disabled = !allowed;
                option.hidden = !allowed;
            });

            const selected = operation.options[operation.selectedIndex];
            if (dataType === 'boolean' && selected && selected.hasAttribute('data-status-number-operation')) {
                operation.value = 'set';
            }
        }

        if (dataType === 'boolean') {
            if (valueMode) {
                valueMode.value = 'fixed';
            }
            setControlVisible(modeWrap, false);
            setControlVisible(fixedNumber, false);
            setControlVisible(fixedBoolean, true);
            setControlVisible(randomMin, false);
            setControlVisible(randomMax, false);
            return;
        }

        setControlVisible(modeWrap, true);
        setControlVisible(fixedBoolean, false);

        const random = valueMode && valueMode.value === 'random';
        setControlVisible(fixedNumber, !random);
        setControlVisible(randomMin, random);
        setControlVisible(randomMax, random);
    }

    function reindexEffectList(list, prefix) {
        effectRows(list).forEach(function (effect, effectIndex) {
            effect.querySelectorAll('[data-status-effect-field]').forEach(function (field) {
                const key = field.dataset.statusEffectField;
                if (key) {
                    field.name = prefix + '[' + effectIndex + '][' + key + ']';
                }
            });
            refreshEffect(effect);
        });
    }

    function reindexEffects() {
        stageRows().forEach(function (stage, stageIndex) {
            reindexEffectList(
                stage.querySelector('[data-status-entry-effects-list]'),
                'status_lifecycle[stages][' + stageIndex + '][entry_effects]'
            );

            reindexEffectList(
                stage.querySelector('[data-status-tick-effects-list]'),
                'status_lifecycle[stages][' + stageIndex + '][tick_effects]'
            );

            outcomeRows(stage).forEach(function (outcome, outcomeIndex) {
                reindexEffectList(
                    outcome.querySelector('[data-status-outcome-effects-list]'),
                    'status_lifecycle[stages][' + stageIndex + '][outcomes][' + outcomeIndex + '][effects]'
                );
            });
        });
    }

    function addEffect(list, recurring) {
        if (!list) {
            return;
        }

        const template = recurring ? recurringEffectTemplate : effectTemplate;
        const fragment = template.content.cloneNode(true);
        const effect = fragment.querySelector('[data-status-effect]');
        if (!effect) {
            return;
        }

        const key = effect.querySelector('[data-status-effect-key]');
        if (key) {
            key.value = randomKey('effect');
        }

        list.appendChild(effect);
        reindexEffects();
    }

    host.addEventListener('click', function (event) {
        const addEntry = event.target.closest('[data-add-status-entry-effect]');
        if (addEntry) {
            const stage = addEntry.closest('[data-status-stage]');
            if (stage) {
                addEffect(stage.querySelector('[data-status-entry-effects-list]'), false);
            }
            return;
        }

        const addTick = event.target.closest('[data-add-status-tick-effect]');
        if (addTick) {
            const stage = addTick.closest('[data-status-stage]');
            if (stage) {
                addEffect(stage.querySelector('[data-status-tick-effects-list]'), true);
            }
            return;
        }

        const addOutcome = event.target.closest('[data-add-status-outcome-effect]');
        if (addOutcome) {
            const outcome = addOutcome.closest('[data-status-outcome]');
            if (outcome) {
                addEffect(outcome.querySelector('[data-status-outcome-effects-list]'), false);
            }
            return;
        }

        const remove = event.target.closest('[data-remove-status-effect]');
        if (remove) {
            const effect = remove.closest('[data-status-effect]');
            if (effect && window.confirm('Remove this Status Effect?')) {
                effect.remove();
                reindexEffects();
            }
            return;
        }

        /*
         * V88 owns Stage/Outcome add, remove, and move actions. Its listener is
         * registered first, so this bubble-phase listener runs afterward and
         * refreshes Effect field names for the new Stage/Outcome ordering.
         */
        if (
            event.target.closest('[data-add-status-stage], [data-add-status-outcome], ' +
                '[data-remove-status-stage], [data-remove-status-outcome], ' +
                '[data-move-status-stage-up], [data-move-status-stage-down]')
        ) {
            window.setTimeout(reindexEffects, 0);
        }
    });

    host.addEventListener('change', function (event) {
        const effect = event.target.closest('[data-status-effect]');
        if (
            effect &&
            (
                event.target.matches('[data-status-effect-target]') ||
                event.target.matches('[data-status-effect-operation]') ||
                event.target.matches('[data-status-effect-value-mode]')
            )
        ) {
            refreshEffect(effect);
        }

        if (event.target.matches('[data-status-lifecycle-mode]')) {
            window.setTimeout(reindexEffects, 0);
        }
    });

    reindexEffects();
})();



==============================================================================
FILE: assets/js/target-search.js
==============================================================================

/*
 * WAYFARER_TARGET_SEARCH_V54
 * WAYFARER_TARGET_SEARCH_V54_2
 *
 * Searchable Target picker for Wayfarer authoring controls.
 *
 * The native <select> remains the canonical form field. Search results are
 * rendered as normal HTML buttons because Chromium/native select menus do not
 * reliably honor hidden <option> filtering.
 */
(function () {
    'use strict';

    const targetSelector = [
        'select[data-wayfarer-target-select]',
        'select[data-starting-effect-field="target"]',
        'select[data-tick-effect-target]',
        '.builder-effect-row select[name$="[target]"]',
        '.builder-condition-row select[name$="[target]"]'
    ].join(',');

    const MAX_VISIBLE_RESULTS = 30;

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

    function escapeHtml(value) {
        return String(value || '')
            .replace(/&/g, '&amp;')
            .replace(/</g, '&lt;')
            .replace(/>/g, '&gt;')
            .replace(/"/g, '&quot;')
            .replace(/'/g, '&#039;');
    }

    function readOptions(select) {
        const options = [];

        Array
            .from(
                select.options
            )
            .forEach(
                function (option) {
                    if (!option.value) {
                        return;
                    }

                    const parent =
                        option.parentElement;

                    const group =
                        parent &&
                        parent.tagName === 'OPTGROUP'
                            ? parent.label
                            : '';

                    const label =
                        String(
                            option.textContent ||
                            option.label ||
                            option.value
                        ).trim();

                    options.push({
                        value: option.value,
                        label: label,
                        group: group,
                        haystack: normalize(
                            group +
                            ' ' +
                            label +
                            ' ' +
                            option.value
                        )
                    });
                }
            );

        return options;
    }

    function enhance(select) {
        if (
            !select ||
            select.dataset.wayfarerTargetSearchReady === '1'
        ) {
            return;
        }

        select.dataset.wayfarerTargetSearchReady =
            '1';

        const options =
            readOptions(
                select
            );

        if (options.length === 0) {
            return;
        }

        const wrapper =
            document.createElement(
                'div'
            );

        wrapper.className =
            'wayfarer-target-search-wrap';

        wrapper.style.position =
            'relative';

        wrapper.style.display =
            'block';

        wrapper.style.width =
            '100%';

        wrapper.style.margin =
            '4px 0 6px';

        const search =
            document.createElement(
                'input'
            );

        search.type =
            'search';

        search.placeholder =
            'Search targets…';

        search.autocomplete =
            'off';

        search.className =
            'wayfarer-target-search';

        search.setAttribute(
            'aria-label',
            'Search available targets'
        );

        search.setAttribute(
            'aria-expanded',
            'false'
        );

        search.style.width =
            '100%';

        search.style.minWidth =
            '190px';

        search.style.boxSizing =
            'border-box';

        const results =
            document.createElement(
                'div'
            );

        results.className =
            'wayfarer-target-search-results';

        results.setAttribute(
            'role',
            'listbox'
        );

        results.hidden =
            true;

        results.style.position =
            'absolute';

        results.style.zIndex =
            '1000';

        results.style.left =
            '0';

        results.style.right =
            '0';

        results.style.top =
            '100%';

        results.style.maxHeight =
            '260px';

        results.style.overflowY =
            'auto';

        results.style.background =
            'var(--panel-bg, #fff)';

        results.style.border =
            '1px solid rgba(0,0,0,.22)';

        results.style.borderRadius =
            '6px';

        results.style.boxShadow =
            '0 8px 24px rgba(0,0,0,.16)';

        results.style.padding =
            '4px';

        const status =
            document.createElement(
                'div'
            );

        status.className =
            'wayfarer-target-search-status';

        status.style.fontSize =
            '12px';

        status.style.opacity =
            '.72';

        status.style.padding =
            '5px 7px';

        wrapper.appendChild(
            search
        );

        wrapper.appendChild(
            results
        );

        select.parentNode.insertBefore(
            wrapper,
            select
        );

        let activeIndex =
            -1;

        let currentMatches =
            [];

        function closeResults() {
            results.hidden =
                true;

            search.setAttribute(
                'aria-expanded',
                'false'
            );

            activeIndex =
                -1;
        }

        function resultButtons() {
            return Array.from(
                results.querySelectorAll(
                    '[data-wayfarer-target-result]'
                )
            );
        }

        function updateActiveResult() {
            const buttons =
                resultButtons();

            buttons.forEach(
                function (button, index) {
                    const active =
                        index === activeIndex;

                    button.style.outline =
                        active
                            ? '2px solid currentColor'
                            : 'none';

                    button.setAttribute(
                        'aria-selected',
                        active
                            ? 'true'
                            : 'false'
                    );
                }
            );

            if (
                activeIndex >= 0 &&
                buttons[activeIndex]
            ) {
                buttons[activeIndex].scrollIntoView({
                    block: 'nearest'
                });
            }
        }

        function choose(match) {
            if (!match) {
                return;
            }

            const matchingOption =
                Array
                    .from(
                        select.options
                    )
                    .find(
                        function (option) {
                            return option.value ===
                                match.value;
                        }
                    );

            if (!matchingOption) {
                return;
            }

            select.value =
                match.value;

            select.dispatchEvent(
                new Event(
                    'input',
                    {
                        bubbles: true
                    }
                )
            );

            select.dispatchEvent(
                new Event(
                    'change',
                    {
                        bubbles: true
                    }
                )
            );

            search.value =
                '';

            closeResults();

            select.focus();
        }

        function render() {
            const query =
                normalize(
                    search.value
                );

            results.innerHTML =
                '';

            activeIndex =
                -1;

            if (query === '') {
                currentMatches =
                    [];

                closeResults();
                return;
            }

            currentMatches =
                options.filter(
                    function (option) {
                        return option.haystack.includes(
                            query
                        );
                    }
                );

            if (currentMatches.length === 0) {
                status.textContent =
                    'No matching targets.';

                results.appendChild(
                    status
                );

                results.hidden =
                    false;

                search.setAttribute(
                    'aria-expanded',
                    'true'
                );

                return;
            }

            const visibleMatches =
                currentMatches.slice(
                    0,
                    MAX_VISIBLE_RESULTS
                );

            visibleMatches.forEach(
                function (match, index) {
                    const button =
                        document.createElement(
                            'button'
                        );

                    button.type =
                        'button';

                    button.dataset.wayfarerTargetResult =
                        String(index);

                    button.setAttribute(
                        'role',
                        'option'
                    );

                    button.style.display =
                        'block';

                    button.style.width =
                        '100%';

                    button.style.textAlign =
                        'left';

                    button.style.border =
                        '0';

                    button.style.borderRadius =
                        '4px';

                    button.style.padding =
                        '7px 9px';

                    button.style.background =
                        'transparent';

                    button.style.cursor =
                        'pointer';

                    const group =
                        match.group !== ''
                            ? match.group + ' — '
                            : '';

                    button.innerHTML =
                        (
                            match.group !== ''
                                ? '<strong>' +
                                  escapeHtml(
                                      group
                                  ) +
                                  '</strong>'
                                : ''
                        ) +
                        escapeHtml(
                            match.label
                        );

                    button.addEventListener(
                        'mouseenter',
                        function () {
                            activeIndex =
                                index;

                            updateActiveResult();
                        }
                    );

                    button.addEventListener(
                        'mousedown',
                        function (event) {
                            /*
                             * Prevent the search input from losing focus before
                             * the click can select the target.
                             */
                            event.preventDefault();
                        }
                    );

                    button.addEventListener(
                        'click',
                        function () {
                            choose(
                                match
                            );
                        }
                    );

                    results.appendChild(
                        button
                    );
                }
            );

            if (
                currentMatches.length >
                visibleMatches.length
            ) {
                const more =
                    document.createElement(
                        'div'
                    );

                more.style.fontSize =
                    '12px';

                more.style.opacity =
                    '.72';

                more.style.padding =
                    '5px 7px';

                more.textContent =
                    'Showing ' +
                    visibleMatches.length +
                    ' of ' +
                    currentMatches.length +
                    ' matches. Keep typing to narrow the list.';

                results.appendChild(
                    more
                );
            }

            results.hidden =
                false;

            search.setAttribute(
                'aria-expanded',
                'true'
            );
        }

        search.addEventListener(
            'input',
            render
        );

        search.addEventListener(
            'search',
            render
        );

        search.addEventListener(
            'keydown',
            function (event) {
                const buttons =
                    resultButtons();

                if (
                    event.key === 'Escape'
                ) {
                    closeResults();
                    return;
                }

                if (
                    event.key === 'ArrowDown'
                ) {
                    if (buttons.length === 0) {
                        return;
                    }

                    event.preventDefault();

                    activeIndex =
                        Math.min(
                            activeIndex + 1,
                            buttons.length - 1
                        );

                    updateActiveResult();
                    return;
                }

                if (
                    event.key === 'ArrowUp'
                ) {
                    if (buttons.length === 0) {
                        return;
                    }

                    event.preventDefault();

                    activeIndex =
                        activeIndex <= 0
                            ? 0
                            : activeIndex - 1;

                    updateActiveResult();
                    return;
                }

                if (
                    event.key === 'Enter' &&
                    activeIndex >= 0 &&
                    currentMatches[
                        activeIndex
                    ]
                ) {
                    event.preventDefault();

                    choose(
                        currentMatches[
                            activeIndex
                        ]
                    );
                }
            }
        );

        search.addEventListener(
            'focus',
            function () {
                if (
                    normalize(
                        search.value
                    ) !== ''
                ) {
                    render();
                }
            }
        );

        document.addEventListener(
            'mousedown',
            function (event) {
                if (
                    !wrapper.contains(
                        event.target
                    )
                ) {
                    closeResults();
                }
            }
        );
    }

    function scan(root) {
        if (!root) {
            return;
        }

        if (
            root.matches &&
            root.matches(
                targetSelector
            )
        ) {
            enhance(
                root
            );
        }

        if (!root.querySelectorAll) {
            return;
        }

        root
            .querySelectorAll(
                targetSelector
            )
            .forEach(
                enhance
            );
    }

    scan(
        document
    );

    const observer =
        new MutationObserver(
            function (mutations) {
                mutations.forEach(
                    function (mutation) {
                        mutation.addedNodes
                            .forEach(
                                function (node) {
                                    if (
                                        node.nodeType ===
                                        Node.ELEMENT_NODE
                                    ) {
                                        scan(
                                            node
                                        );
                                    }
                                }
                            );
                    }
                );
            }
        );

    observer.observe(
        document.body,
        {
            childList: true,
            subtree: true
        }
    );
})();


==============================================================================
FILE: assets/js/trait-display.js
==============================================================================

/*
 * Wayfarer Trait Status Display controls
 * WAYFARER_STATUS_TRAIT_DISPLAY_V86
 *
 * Adds/maintains the Status Display selector for dynamically-added Trait rows.
 * Bar/Both are available only for bounded numeric Traits.
 */
(() => {
    'use strict';

    function allowedSurfaces(editor) {
        try {
            const value = JSON.parse(
                editor.dataset.traitSurfaces || '[]'
            );

            return Array.isArray(value)
                ? value
                : [];
        } catch (error) {
            return [];
        }
    }

    function rowForIndex(editor, index) {
        return editor.querySelector(
            '.trait-row[data-trait-index="' + index + '"]'
        );
    }

    function statusDisplayControl(editor, notesRow) {
        if (
            !allowedSurfaces(editor).includes('status') ||
            !notesRow
        ) {
            return null;
        }

        const display =
            notesRow.querySelector(
                '.trait-player-display'
            );

        if (!display) {
            return null;
        }

        let select =
            display.querySelector(
                '[data-trait-status-display]'
            );

        if (select) {
            return select;
        }

        const index =
            String(
                notesRow.dataset.traitIndex || ''
            );

        const fieldName =
            String(
                editor.dataset.traitFieldName || 'traits'
            );

        if (index === '') {
            return null;
        }

        const label =
            document.createElement('label');

        label.className =
            'trait-status-display-control';

        const text =
            document.createElement('span');

        text.textContent =
            'Status Display:';

        select =
            document.createElement('select');

        select.name =
            fieldName +
            '[' + index + ']' +
            '[status_display]';

        select.dataset.traitStatusDisplay =
            '1';

        [
            ['number', 'Number'],
            ['bar', 'Bar'],
            ['both', 'Both'],
        ].forEach(
            function (entry) {
                const option =
                    document.createElement('option');

                option.value = entry[0];
                option.textContent = entry[1];
                select.appendChild(option);
            }
        );

        label.appendChild(text);
        label.appendChild(select);

        const primaryHelp =
            display.querySelector(
                '.trait-player-display-help'
            );

        if (primaryHelp) {
            display.insertBefore(
                label,
                primaryHelp
            );
        } else {
            display.appendChild(label);
        }

        let help =
            display.querySelector(
                '[data-trait-status-display-help]'
            );

        if (!help) {
            help =
                document.createElement('small');

            help.className =
                'trait-status-display-help';

            help.dataset.traitStatusDisplayHelp =
                '1';

            help.textContent =
                'Bars require a Number Trait with both Minimum and Maximum. ' +
                'True / False Traits always display their value.';

            if (primaryHelp) {
                display.insertBefore(
                    help,
                    primaryHelp
                );
            } else {
                display.appendChild(help);
            }
        }

        return select;
    }

    function updateAvailability(
        editor,
        notesRow,
        select
    ) {
        if (!select || !notesRow) {
            return;
        }

        const index =
            String(
                notesRow.dataset.traitIndex || ''
            );

        const row =
            rowForIndex(
                editor,
                index
            );

        if (!row) {
            return;
        }

        const type =
            row.querySelector(
                '.trait-type'
            );

        const min =
            row.querySelector(
                'input[name$="[min]"]'
            );

        const max =
            row.querySelector(
                'input[name$="[max]"]'
            );

        const isNumber =
            !type ||
            type.value === 'number';

        const minValue =
            min && min.value.trim() !== ''
                ? Number(min.value)
                : NaN;

        const maxValue =
            max && max.value.trim() !== ''
                ? Number(max.value)
                : NaN;

        const barAvailable =
            isNumber &&
            Number.isFinite(minValue) &&
            Number.isFinite(maxValue) &&
            maxValue > minValue;

        Array.from(select.options).forEach(
            function (option) {
                if (
                    option.value === 'bar' ||
                    option.value === 'both'
                ) {
                    option.disabled =
                        !barAvailable;
                }
            }
        );

        if (
            !barAvailable &&
            select.value !== 'number'
        ) {
            select.value = 'number';
        }
    }

    function scanEditor(editor) {
        editor
            .querySelectorAll(
                '.trait-notes-row[data-trait-index]'
            )
            .forEach(
                function (notesRow) {
                    const select =
                        statusDisplayControl(
                            editor,
                            notesRow
                        );

                    updateAvailability(
                        editor,
                        notesRow,
                        select
                    );
                }
            );
    }

    function bindEditor(editor) {
        scanEditor(editor);

        editor.addEventListener(
            'input',
            function (event) {
                if (
                    event.target.matches(
                        '.trait-type, ' +
                        'input[name$="[min]"], ' +
                        'input[name$="[max]"]'
                    )
                ) {
                    scanEditor(editor);
                }
            }
        );

        editor.addEventListener(
            'change',
            function (event) {
                if (
                    event.target.matches(
                        '.trait-type, ' +
                        'input[name$="[min]"], ' +
                        'input[name$="[max]"]'
                    )
                ) {
                    scanEditor(editor);
                }
            }
        );

        const container =
            editor.querySelector(
                '[data-traits-container]'
            );

        if (container) {
            const observer =
                new MutationObserver(
                    function () {
                        scanEditor(editor);
                    }
                );

            observer.observe(
                container,
                {
                    childList: true,
                    subtree: true,
                }
            );
        }
    }

    function boot() {
        document
            .querySelectorAll(
                '[data-wayfarer-trait-editor]'
            )
            .forEach(bindEditor);
    }

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


==============================================================================
FILE: assets/js/traits.js
==============================================================================

/*
 * Wayfarer reusable Trait editor
 * WAYFARER_MULTI_TRAIT_EDITOR_V52
 */
(function () {
    'use strict';

    function parseSurfaces(editor) {
        try {
            const parsed = JSON.parse(
                editor.dataset.traitSurfaces || '[]'
            );
            return Array.isArray(parsed)
                ? parsed.filter(function (surface) {
                    return surface === 'inventory' || surface === 'status';
                })
                : [];
        } catch (error) {
            return [];
        }
    }

    function surfaceLabel(surface) {
        return surface === 'inventory'
            ? 'Inventory'
            : 'Status';
    }

    function escapeHtml(value) {
        return String(value)
            .replace(/&/g, '&amp;')
            .replace(/</g, '&lt;')
            .replace(/>/g, '&gt;')
            .replace(/"/g, '&quot;')
            .replace(/'/g, '&#039;');
    }

    function updateTraitFields(traitRow) {
        if (!traitRow) {
            return;
        }

        const typeSelect = traitRow.querySelector('.trait-type');
        const numberInitial = traitRow.querySelector('.trait-number-initial');
        const booleanInitial = traitRow.querySelector('.trait-boolean-initial');

        if (!typeSelect || !numberInitial || !booleanInitial) {
            return;
        }

        const isBoolean = typeSelect.value === 'boolean';

        traitRow.querySelectorAll('.trait-number-fields')
            .forEach(function (field) {
                field.style.display = isBoolean ? 'none' : '';
            });

        traitRow.querySelectorAll('.trait-not-applicable')
            .forEach(function (field) {
                field.style.display = isBoolean ? '' : 'none';
            });

        numberInitial.style.display = isBoolean ? 'none' : '';
        booleanInitial.style.display = isBoolean ? '' : 'none';
    }

    function nextIndex(editor) {
        let max = -1;

        editor.querySelectorAll('.trait-row[data-trait-index]')
            .forEach(function (row) {
                const value = Number(row.dataset.traitIndex);
                if (Number.isInteger(value) && value > max) {
                    max = value;
                }
            });

        return max + 1;
    }

    function createTrait(editor) {
        const container = editor.querySelector('[data-traits-container]');
        if (!container) {
            return;
        }

        const fieldName = editor.dataset.traitFieldName || 'traits';
        const index = nextIndex(editor);
        const safeFieldName = escapeHtml(fieldName);
        const surfaces = parseSurfaces(editor);

        const row = document.createElement('tr');
        row.className = 'trait-row';
        row.dataset.traitIndex = String(index);
        row.innerHTML = `
            <td class="trait-name">
                <input type="hidden" name="${safeFieldName}[${index}][id]" value="">
                <input type="text" name="${safeFieldName}[${index}][name]">
            </td>
            <td>
                <select name="${safeFieldName}[${index}][type]" class="trait-type">
                    <option value="number">Number</option>
                    <option value="boolean">True / False</option>
                </select>
            </td>
            <td class="trait-number">
                <span class="trait-number-fields">
                    <input type="number" step="any" name="${safeFieldName}[${index}][min]">
                </span>
                <span class="trait-not-applicable">&mdash;</span>
            </td>
            <td class="trait-number">
                <span class="trait-number-fields">
                    <input type="number" step="any" name="${safeFieldName}[${index}][max]">
                </span>
                <span class="trait-not-applicable">&mdash;</span>
            </td>
            <td>
                <span class="trait-number-initial">
                    <input type="number" step="any" name="${safeFieldName}[${index}][initial_number]">
                </span>
                <span class="trait-boolean-initial">
                    <select name="${safeFieldName}[${index}][initial_boolean]">
                        <option value="0">False</option>
                        <option value="1">True</option>
                    </select>
                </span>
            </td>
            <td>
                <select name="${safeFieldName}[${index}][active]">
                    <option value="1">Active</option>
                    <option value="0">Inactive</option>
                </select>
            </td>
            <td class="trait-actions">
                <button type="button" class="remove-trait">Remove</button>
            </td>
        `;

        const notesRow = document.createElement('tr');
        notesRow.className = 'trait-notes-row';
        notesRow.dataset.traitIndex = String(index);

        const surfaceControls = surfaces.map(function (surface) {
            return `
                <label>
                    <input
                        type="checkbox"
                        name="${safeFieldName}[${index}][display_surfaces][]"
                        value="${escapeHtml(surface)}"
                    >
                    ${surfaceLabel(surface)}
                </label>
            `;
        }).join('');

        notesRow.innerHTML = `
            <td colspan="7">
                <label>
                    <strong>Notes:</strong>
                    <input
                        type="text"
                        name="${safeFieldName}[${index}][notes]"
                        placeholder="Optional notes about how this trait is used"
                        style="width: calc(100% - 70px);"
                    >
                </label>
                <input
                    type="hidden"
                    name="${safeFieldName}[${index}][display_surfaces_present]"
                    value="1"
                >
                ${surfaceControls !== '' ? `
                    <div class="trait-player-display">
                        <strong>Show to Player:</strong>
                        ${surfaceControls}
                        <small class="trait-player-display-help">
                            Controls where this trait is displayed to the player.
                            Unchecked traits remain available to gameplay logic.
                        </small>
                    </div>
                ` : ''}
            </td>
        `;

        container.appendChild(row);
        container.appendChild(notesRow);
        updateTraitFields(row);

        const nameInput = row.querySelector('input[type="text"]');
        if (nameInput) {
            nameInput.focus();
        }
    }

    function initializeEditor(editor) {
        if (!editor || editor.dataset.traitEditorReady === '1') {
            return;
        }

        editor.dataset.traitEditorReady = '1';

        editor.querySelectorAll('.trait-row')
            .forEach(updateTraitFields);

        editor.addEventListener('change', function (event) {
            if (event.target.classList.contains('trait-type')) {
                updateTraitFields(event.target.closest('.trait-row'));
            }
        });

        editor.addEventListener('click', function (event) {
            const addButton = event.target.closest('[data-add-trait]');
            if (addButton) {
                createTrait(editor);
                return;
            }

            const removeButton = event.target.closest('.remove-trait');
            if (!removeButton) {
                return;
            }

            const traitRow = removeButton.closest('.trait-row');
            if (!traitRow) {
                return;
            }

            const index = traitRow.dataset.traitIndex;
            const notesRow = editor.querySelector(
                '.trait-notes-row[data-trait-index="' + index + '"]'
            );

            if (notesRow) {
                notesRow.remove();
            }

            traitRow.remove();
        });
    }

    function initializeAll() {
        document.querySelectorAll('[data-wayfarer-trait-editor]')
            .forEach(initializeEditor);
    }

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


==============================================================================
FILE: config/builder-types.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Wayfarer Builder Types
|--------------------------------------------------------------------------
|
| Defines the types of authored objects that the generic builder can edit.
|
| The builder handles the CRUD machinery.
| This file describes the data.
|
*/

$builderTypes = [

    'regions' => [

        'label'      => 'Regions',
        'singular'   => 'Region',
        'table'      => 'wf_regions',
        'list_field' => 'name',
        'traits'     => true,

                /*
         * Permanent deletion is available from the edit screen.
         * A Region cannot be deleted while Locations still belong to it.
         */
        'delete' => [
            'enabled' => true,

            'dependencies' => [
                [
                    'table'       => 'wf_locations',
                    'foreign_key' => 'region_id',
                    'label'       => 'Locations'
                ]
            ]
        ],

'scope' => [
            'type'  => 'game',
            'field' => 'game_id'
        ],

        'fields' => [

            'name' => [
                'label'    => 'Name',
                'type'     => 'text',
                'required' => true
            ],

            'description' => [
                'label' => 'Description',
                'type'  => 'textarea'
            ],

            'navigation_type' => [
                'label'    => 'Navigation Type',
                'type'     => 'select',
                'required' => true,

                'options' => [
                    'linear'   => 'Linear',
                    'grid'     => 'Grid',
                    'freeform' => 'Freeform'
                ]
            ],

            'status' => [
                'label'    => 'Status',
                'type'     => 'select',
                'required' => true,
                'default'  => 'draft',

                'options' => [
                    'draft'    => 'Draft',
                    'active'   => 'Active',
                    'inactive' => 'Inactive'
                ]
            ]

        ],

        /* WAYFARER_LINEAR_DISTANCE_LABEL_V61 */
        'config_fields' => [
            'distance_label' => [
                'label' => 'Distance Label',
                'type' => 'text',
                'default' => 'units',
                'help' =>
                    'Player-facing unit used for Linear travel distance, such as miles, km, leagues, or units.'
            ]
        ]
    ],


    'locations' => [

        'label'      => 'Locations',
        'singular'   => 'Location',
        'table'      => 'wf_locations',
        'list_field' => 'name',
        'traits'     => true,

        'list_columns' => [

            'name' => [
                'label'    => 'Name',
                'source'   => 'field',
                'field'    => 'name',
                'sortable' => true
            ],

            'region' => [
                'label'        => 'Region',
                'source'       => 'relationship',
                'relationship' => 'region_id',
                'sortable'     => true
            ],

            'position' => [
                'label'    => 'Position',
                'source'   => 'config',
                'field'    => 'position',
                'type'     => 'number',
                'sortable' => true
            ]

        ],

                /*
         * Permanent deletion is available from the edit screen.
         */
        'delete' => [
            'enabled' => true
        ],

'scope' => [
            'type'        => 'region',
            'field'       => 'region_id',
            'scope_table' => 'wf_regions',
            'scope_key'   => 'id',
            'game_field'  => 'game_id'
        ],

        'relationships' => [

            'region_id' => [
                'label'       => 'Region',
                'type'        => 'select_record',
                'table'       => 'wf_regions',
                'value_field' => 'id',
                'label_field' => 'name',
                'game_field'  => 'game_id',
                'required'    => true
            ]

        ],

        'fields' => [

            'name' => [
                'label'    => 'Name',
                'type'     => 'text',
                'required' => true
            ],

            'description' => [
                'label' => 'Description',
                'type'  => 'textarea'
            ],

            'status' => [
                'label'    => 'Status',
                'type'     => 'select',
                'required' => true,
                'default'  => 'draft',

                'options' => [
                    'draft'    => 'Draft',
                    'active'   => 'Active',
                    'inactive' => 'Inactive'
                ]
            ]

        ],

        'config_fields' => [

            'position' => [
                'label'    => 'Position',
                'type'     => 'number',
                'min'      => 0,
                'required' => true,

                'condition' => [
                    'relationship' => 'region_id',
                    'source_table'  => 'wf_regions',
                    'source_key'    => 'id',
                    'source_field'  => 'navigation_type',
                    'equals'        => 'linear'
                ]
            ]

        ]
    ],


    'entities' => [

        'label'      => 'Entities',
        'singular'   => 'Entity',
        'table'      => 'wf_entities',
        'list_field' => 'name',
        'traits'     => true,

                /*
         * Permanent deletion is available from the edit screen.
         * Additional dependency rules can be added here later as
         * Storylets and other authored objects begin referencing Entities.
         */
        'delete' => [
            'enabled' => true
        ],

'scope' => [
            'type'  => 'game',
            'field' => 'game_id'
        ],

        'fields' => [

            'name' => [
                'label'    => 'Name',
                'type'     => 'text',
                'required' => true
            ],

            'description' => [
                'label' => 'Description',
                'type'  => 'textarea'
            ],

            'entity_type' => [
                'label'    => 'Entity Type',
                'type'     => 'select',
                'required' => true,
                'default'  => 'item',

                'options' => [
                    'item'      => 'Item',
                    'character' => 'Character'
                ]
            ],

            'status' => [
                'label'    => 'Status',
                'type'     => 'select',
                'required' => true,
                'default'  => 'draft',

                'options' => [
                    'draft'    => 'Draft',
                    'active'   => 'Active',
                    'inactive' => 'Inactive'
                ]
            ]

        ],

        /*
         * System traits use the same stored config.traits collection as
         * author-created traits. They are locked in the authoring UI.
         */

        'system_traits' => [

            'selector_field' => 'entity_type',
            'after_field'    => 'entity_type',

            'groups' => [

                'item' => [

                    'label' => 'Item Settings',

                    'help' =>
                        'These are required Item properties used by Wayfarer. ' .
                        'They cannot be removed or renamed.',

                    'traits' => [

                        'quantity' => [
                            /*
                             * WAYFARER_ITEM_QUANTITY_CONTEXT_V44
                             */
                            'label'            => 'Starting Quantity',
                            'type'             => 'number',
                            'default'          => 0,
                            'min'              => 0,
                            'required'         => true,

                            /*
                             * The minimum is a Wayfarer system rule, not an
                             * author-editable gameplay setting.
                             */
                            'show_system_min'  => true,
                            'min_label'        => 'Minimum Quantity',
                            'min_help'         =>
                                'Wayfarer Item quantities cannot fall below 0.',

                            'allow_author_max' => true,
                            'max_label'        => 'Maximum Quantity',
                            'max_help'         =>
                                'The maximum quantity the player can hold during gameplay. ' .
                                'Leave blank for no maximum.',

                            'help' =>
                                'Sets the quantity of this Item when gameplay is initialized. ' .
                                'Effects may increase or decrease the quantity during play. ' .
                                'A Starting Quantity of 0 means the player begins without this Item.'
                        ],

                        'inventory_visibility' => [
                            'label'    => 'Inventory Visibility',
                            'type'     => 'select',
                            'default'  => 'while_possessed',
                            'required' => true,

                            'options' => [
                                'while_possessed' => 'Only while possessed',
                                'once_discovered' => 'Once discovered',
                                'always'          => 'Always',
                                'never'           => 'Never'
                            ],

                            'help' =>
                                'Controls when this item appears in the player inventory. ' .
                                '"Only while possessed" hides the item whenever its quantity ' .
                                'is 0. "Once discovered" hides it until the player first ' .
                                'obtains or discovers it, then keeps it visible even if its ' .
                                'quantity later returns to 0. "Always" shows the item from ' .
                                'the beginning of the game. "Never" keeps the item hidden ' .
                                'from the player inventory while still allowing gameplay ' .
                                'conditions and effects to use it.'
                        ]

                    ]
                ],


                'character' => [

                    'label' => 'Character Settings',

                    'help' =>
                        'These are required Character properties used by Wayfarer. ' .
                        'They cannot be removed or renamed.',

                    'traits' => [

                        'party_member' => [

                            'label'    => 'Starts in Party',
                            'type'     => 'binary',
                            'default'  => 0,
                            'required' => true,

                            'help' =>
                                'Determines whether this character begins the game ' .
                                'as a member of the player party. No stores 0; ' .
                                'Yes stores 1. Storylets can later change this ' .
                                'state to add or remove the character from the party.'
                        ]

                    ]
                ]

            ]
        ]

    ],


    /* WAYFARER_STATUSES_V87 */
    'statuses' => [

        'label'      => 'Statuses',
        'singular'   => 'Status',
        'table'      => 'wf_statuses',
        'list_field' => 'name',

        'list_columns' => [
            'name' => [
                'label'    => 'Name',
                'source'   => 'field',
                'field'    => 'name',
                'sortable' => true
            ],
            'status' => [
                'label'    => 'Status',
                'source'   => 'field',
                'field'    => 'status',
                'sortable' => true
            ]
        ],

        'scope' => [
            'type'  => 'game',
            'field' => 'game_id'
        ],

        'fields' => [
            'name' => [
                'label'    => 'Name',
                'type'     => 'text',
                'required' => true,
                'help'     =>
                    'Author-facing and player-facing name of this persistent Status.'
            ],

            'description' => [
                'label' => 'Description',
                'type'  => 'textarea',
                'help'  =>
                    'Optional player-facing description shown while this Status is active.'
            ],

            'status' => [
                'label'    => 'Status',
                'type'     => 'select',
                'required' => true,
                'default'  => 'draft',
                'options'  => [
                    'draft'    => 'Draft',
                    'active'   => 'Active',
                    'inactive' => 'Inactive'
                ],
                'help' =>
                    'Only Active Status definitions are available to gameplay Conditions and Effects.'
            ]
        ],

        'config_fields' => [
            'show_to_player' => [
                'label'    => 'Show to Player',
                'type'     => 'select',
                'default'  => '1',
                'required' => true,
                'options'  => [
                    '1' => 'Yes',
                    '0' => 'No'
                ],
                'help' =>
                    'If Yes, the Status appears beneath the affected party member on the player Status screen.'
            ],

            /* WAYFARER_STATUS_LIFECYCLE_DISPLAY_V88 */
            'show_stage_to_player' => [
                'label'    => 'Show Current Stage to Player',
                'type'     => 'select',
                'default'  => '1',
                'required' => true,
                'options'  => [
                    '1' => 'Yes',
                    '0' => 'No'
                ],
                'help' =>
                    'If Yes, a timed Status may show its current Stage beneath the Status name.'
            ],

            'show_time_remaining' => [
                'label'    => 'Show Time Remaining to Player',
                'type'     => 'select',
                'default'  => '0',
                'required' => true,
                'options'  => [
                    '1' => 'Yes',
                    '0' => 'No'
                ],
                'help' =>
                    'If Yes, a timed Status may show how many ticks remain before its next Outcome check.'
            ]
        ]
    ],


    /* WAYFARER_STORYLET_BUILDER_V56 */
    'storylets' => [

        'label'      => 'Storylets',
        'singular'   => 'Storylet',
        'table'      => 'wf_storylets',
        'list_field' => 'name',

        'list_columns' => [

            'name' => [
                'label'    => 'Name',
                'source'   => 'field',
                'field'    => 'name',
                'sortable' => true
            ],

            'parent' => [
                'label'        => 'Parent',
                'source'       => 'relationship',
                'relationship' => 'parent_storylet_id',
                'sortable'     => true
            ],

            'trigger' => [
                'label'    => 'Trigger',
                'source'   => 'field',
                'field'    => 'trigger_type',
                'sortable' => true
            ],

            'status' => [
                'label'    => 'Status',
                'source'   => 'field',
                'field'    => 'status',
                'sortable' => true
            ]
        ],

        /*
         * A Storylet with children cannot be permanently removed until its
         * Branch Storylets have been detached or deleted.
         */
        'delete' => [
            'enabled' => true,
            'dependencies' => [
                [
                    'table'       => 'wf_storylets',
                    'foreign_key' => 'parent_storylet_id',
                    'label'       => 'Branch Storylets'
                ]
            ]
        ],

        'scope' => [
            'type'  => 'game',
            'field' => 'game_id'
        ],

        'relationships' => [

            'parent_storylet_id' => [
                'label'           => 'Parent Storylet',
                'type'            => 'select_record',
                'table'           => 'wf_storylets',
                'value_field'     => 'id',
                'label_field'     => 'name',
                'game_field'      => 'game_id',
                'required'        => false,
                'exclude_current' => true,
                'help'            =>
                    'Leave blank for a root Storylet. Select a parent to make ' .
                    'this Storylet one of that Storylet\'s player Branches.'
            ]
        ],

        'fields' => [

            'name' => [
                'label'    => 'Name',
                'type'     => 'text',
                'required' => true,
                'help'     =>
                    'Author-facing Storylet name and default player-facing title.'
            ],

            'description' => [
                'label' => 'Narrative / Description',
                'type'  => 'textarea',
                'help'  =>
                    'Narrative shown when this Storylet opens. It may also be ' .
                    'used as preview text when the Storylet is offered.'
            ],

            'branch_label' => [
                'label' => 'Branch Label',
                'type'  => 'text',
                'help'  =>
                    'Used when this Storylet appears as a child Branch. Leave ' .
                    'blank to use the Storylet Name.'
            ],

            'branch_sort_order' => [
                'label'   => 'Branch Order',
                'type'    => 'number',
                'min'     => 0,
                'default' => 0,
                'help'    =>
                    'Lower numbers appear first among sibling Branches. Ignored ' .
                    'for root Storylets.'
            ],

            'trigger_type' => [
                'label'    => 'Trigger Type',
                'type'     => 'select',
                'required' => true,
                'default'  => 'manual',

                'options' => [
                    'manual'    => 'Manual',
                    'automatic' => 'Automatic',
                    'chance'    => 'Chance',
                    /* WAYFARER_EVENT_STORYLETS_V88 */
                    'event'     => 'Event / Linked Only'
                ],

                'help' =>
                    'Manual: offer while eligible. Automatic: fire when it becomes ' .
                    'eligible. Chance: while eligible, roll the base chance each tick. ' .
                    'Event / Linked Only: never offer as a normal Action; open it from ' .
                    'a Status Outcome or another linked gameplay event.'
            ],

            'max_occurrences' => [
                'label' => 'Maximum Occurrences',
                'type'  => 'number',
                'min'   => 1,

                'help' =>
                    'Leave blank for unlimited occurrences.'
            ],

            'status' => [
                'label'    => 'Status',
                'type'     => 'select',
                'required' => true,
                'default'  => 'draft',

                'options' => [
                    'draft'    => 'Draft',
                    'active'   => 'Active',
                    'inactive' => 'Inactive'
                ]
            ]
        ],

        'config_fields' => [

            'priority' => [
                'label'   => 'Priority',
                'type'    => 'number',
                'default' => 100,
                'help'    =>
                    'Author-controlled gameplay order for competing Storylets. ' .
                    'Lower numbers are evaluated first.'
            ],

            'tick_cost' => [
                'label'   => 'Tick Cost',
                'type'    => 'number',
                'min'     => 0,
                'default' => 0,
                'help'    =>
                    'How many normal gameplay ticks resolving this Storylet consumes. ' .
                    '0 consumes no time; 1 or more runs the normal tick pipeline.'
            ],

            'chance_percent' => [
                'label' => 'Base Chance %',
                'type'  => 'number',
                'min'   => 0,
                'max'   => 100,
                'step'  => 0.01,
                'help'  =>
                    'Used only by Chance Storylets. Eligibility is checked first; ' .
                    'then this percentage is rolled on each gameplay tick.'
            ],

            'interrupts_travel' => [
                'label'   => 'Interrupts Travel',
                'type'    => 'select',
                'default' => '0',
                'options' => [
                    '0' => 'No',
                    '1' => 'Yes'
                ],
                'help' =>
                    'Used by Automatic and Chance Storylets. If Yes, firing the ' .
                    'Storylet stops the current travel activity. Manual Storylets ' .
                    'are selected by the player and do not use this setting.'
            ]
        ]
    ]
];



==============================================================================
FILE: includes/builder/collection-table.php
==============================================================================

<?php
/**
 * Generic collection renderer.
 * Expected variables: $records, $listColumns, $listField, $definition,
 * $gameId, $type, $builderPage
 */
?>
<h2><?= builderEscape($definition['label']) ?></h2>

<?php if (empty($records)): ?>
    <p>
        No <?= strtolower(builderEscape($definition['label'])) ?>
        have been created yet.
    </p>

<?php elseif (!empty($listColumns)): ?>
    <table
        border="1"
        cellpadding="6"
        cellspacing="0"
        data-collection-table
    >
        <thead>
            <tr>
                <?php foreach ($listColumns as $columnName => $column): ?>
                    <th>
                        <?php if (!empty($column['sortable'])): ?>
                            <button
                                type="button"
                                data-sort-column="<?= builderEscape($columnName) ?>"
                                data-sort-type="<?= builderEscape($column['type'] ?? 'text') ?>"
                            >
                                <?= builderEscape($column['label'] ?? $columnName) ?>
                            </button>
                        <?php else: ?>
                            <?= builderEscape($column['label'] ?? $columnName) ?>
                        <?php endif; ?>
                    </th>
                <?php endforeach; ?>
            </tr>
        </thead>

        <tbody>
            <?php foreach ($records as $item): ?>
                <tr>
                    <?php foreach ($listColumns as $columnName => $column): ?>
                        <?php
                        $displayValue = $item['_list'][$columnName] ?? '';
                        $sortValue = $displayValue;
                        ?>

                        <td
                            data-column="<?= builderEscape($columnName) ?>"
                            data-sort-value="<?= builderEscape($sortValue) ?>"
                        >
                            <?php if ($columnName === array_key_first($listColumns)): ?>
                                <a href="<?= builderEscape($builderPage) ?>?game=<?= $gameId ?>&amp;type=<?= urlencode($type) ?>&amp;id=<?= (int)$item['id'] ?>">
                                    <?= builderEscape($displayValue) ?>
                                </a>
                            <?php else: ?>
                                <?= builderEscape($displayValue) ?>
                            <?php endif; ?>
                        </td>
                    <?php endforeach; ?>
                </tr>
            <?php endforeach; ?>
        </tbody>
    </table>

<?php else: ?>
    <ul>
        <?php foreach ($records as $item): ?>
            <li>
                <a href="<?= builderEscape($builderPage) ?>?game=<?= $gameId ?>&amp;type=<?= urlencode($type) ?>&amp;id=<?= (int)$item['id'] ?>">
                    <?= builderEscape($item[$listField]) ?>
                </a>
            </li>
        <?php endforeach; ?>
    </ul>
<?php endif; ?>



==============================================================================
FILE: includes/builder/collection.php
==============================================================================

<?php

/**
 * Loads the collection plus relationship/condition data required by the UI.
 */
function loadBuilderCollection(
    PDO $pdo,
    array $definition,
    int $gameId
): array {
    $table         = $definition['table'];
    $listField     = $definition['list_field'];
    $listColumns   = $definition['list_columns'] ?? [];
    $relationships = $definition['relationships'] ?? [];
    $configFields  = $definition['config_fields'] ?? [];

    $scopeQuery = buildScopeQuery($definition);

    if (!empty($listColumns)) {
        $sql = "
            SELECT `$table`.*
            FROM {$scopeQuery['from']}
            WHERE {$scopeQuery['where']}
            ORDER BY `$table`.`$listField`
        ";
    } else {
        $sql = "
            SELECT
                `$table`.`id`,
                `$table`.`$listField`
            FROM {$scopeQuery['from']}
            WHERE {$scopeQuery['where']}
            ORDER BY `$table`.`$listField`
        ";
    }

    $stmt = $pdo->prepare($sql);
    $stmt->execute([$gameId]);
    $records = $stmt->fetchAll();

    // ------------------------------------------------------------
    // BUILD COLLECTION DISPLAY VALUES
    // ------------------------------------------------------------

    if (!empty($listColumns)) {
        // Preload relationship labels so the collection does not issue one
        // query per row/cell.
        $relationshipLabelMaps = [];

        foreach ($relationships as $relationshipName => $relationship) {
            $options = getRelationshipOptions(
                $pdo,
                $relationship,
                $gameId
            );

            foreach ($options as $option) {
                $relationshipLabelMaps[$relationshipName][
                    (string)$option['option_value']
                ] = $option['option_label'];
            }
        }

        foreach ($records as &$item) {
            $item['_list'] = [];
            $itemConfig = [];

            if (!empty($item['config'])) {
                $decoded = json_decode($item['config'], true);

                if (is_array($decoded)) {
                    $itemConfig = $decoded;
                }
            }

            foreach ($listColumns as $columnName => $column) {
                $source = $column['source'] ?? 'field';

                if ($source === 'field') {
                    $fieldName = $column['field'] ?? $columnName;
                    $item['_list'][$columnName] = $item[$fieldName] ?? '';
                }

                elseif ($source === 'config') {
                    $configField = $column['field'] ?? $columnName;
                    $item['_list'][$columnName] = $itemConfig[$configField] ?? '';
                }

                elseif ($source === 'relationship') {
                    $relationshipName = $column['relationship'] ?? '';
                    $item['_list'][$columnName] = '';

                    if (
                        $relationshipName !== '' &&
                        isset($relationships[$relationshipName])
                    ) {
                        $relationshipId = $item[$relationshipName] ?? null;

                        if ($relationshipId !== null && $relationshipId !== '') {
                            $item['_list'][$columnName] =
                                $relationshipLabelMaps[$relationshipName][
                                    (string)$relationshipId
                                ] ?? '';
                        }
                    }
                }
            }
        }

        unset($item);
    }

    // ------------------------------------------------------------
    // RELATIONSHIP OPTIONS
    // ------------------------------------------------------------

    $relationshipOptions = [];

    foreach ($relationships as $fieldName => $relationship) {
        $relationshipOptions[$fieldName] = getRelationshipOptions(
            $pdo,
            $relationship,
            $gameId
        );
    }

    // ------------------------------------------------------------
    // CONDITION DATA FOR BROWSER
    // ------------------------------------------------------------

    $conditionData = [];

    foreach ($configFields as $fieldName => $field) {
        if (empty($field['condition'])) {
            continue;
        }

        $condition = $field['condition'];
        $relationshipName = $condition['relationship'];

        if (!isset($relationships[$relationshipName])) {
            continue;
        }

        $relationship = $relationships[$relationshipName];
        $relationshipTable = $relationship['table'];
        $valueField = $relationship['value_field'];
        $gameField = $relationship['game_field'];
        $sourceField = $condition['source_field'];

        $sql = "
            SELECT
                `$valueField` AS record_id,
                `$sourceField` AS condition_value
            FROM `$relationshipTable`
            WHERE `$gameField` = ?
        ";

        $stmt = $pdo->prepare($sql);
        $stmt->execute([$gameId]);

        foreach ($stmt->fetchAll() as $row) {
            $conditionData[$relationshipName][
                (string)$row['record_id']
            ] = (string)$row['condition_value'];
        }
    }

    return [
        'records'             => $records,
        'relationshipOptions' => $relationshipOptions,
        'conditionData'       => $conditionData,
    ];
}



==============================================================================
FILE: includes/builder/config-field.php
==============================================================================

<?php
/**
 * Expected variables: $fieldName, $field, $configValues, $record, $pdo
 */
$condition = $field['condition'] ?? null;
$initiallyVisible = configFieldApplies($pdo, $field, $record);
$value = $configValues[$fieldName] ?? '';
$fieldType = $field['type'] ?? 'text';
?>
<p
    data-config-field="<?= builderEscape($fieldName) ?>"
    <?php if ($condition): ?>
        data-condition-relationship="<?= builderEscape($condition['relationship']) ?>"
        data-condition-equals="<?= builderEscape($condition['equals']) ?>"
    <?php endif; ?>
    <?= $initiallyVisible ? '' : 'style="display:none;"' ?>
>
    <label>
        <?= builderEscape($field['label']) ?>
        <?php if (!empty($field['required'])): ?>*<?php endif; ?>
        <br>

        <?php if ($fieldType === 'number'): ?>
            <input
                type="number"
                name="config[<?= builderEscape($fieldName) ?>]"
                value="<?= builderEscape($value) ?>"
                <?= isset($field['min'])
                    ? 'min="' . builderEscape($field['min']) . '"'
                    : '' ?>
                <?= isset($field['max'])
                    ? 'max="' . builderEscape($field['max']) . '"'
                    : '' ?>
                <?= isset($field['step'])
                    ? 'step="' . builderEscape($field['step']) . '"'
                    : '' ?>
            >

        <?php elseif ($fieldType === 'textarea'): ?>
            <textarea
                name="config[<?= builderEscape($fieldName) ?>]"
                rows="6"
                cols="70"
            ><?= builderEscape($value) ?></textarea>

        <?php elseif ($fieldType === 'select'): ?>
            <select name="config[<?= builderEscape($fieldName) ?>]">
                <?php foreach (($field['options'] ?? []) as $optionValue => $optionLabel): ?>
                    <option
                        value="<?= builderEscape($optionValue) ?>"
                        <?= $value == $optionValue ? 'selected' : '' ?>
                    >
                        <?= builderEscape($optionLabel) ?>
                    </option>
                <?php endforeach; ?>
            </select>

        <?php else: ?>
            <input
                type="text"
                name="config[<?= builderEscape($fieldName) ?>]"
                value="<?= builderEscape($value) ?>"
            >
        <?php endif; ?>

        <?php if (!empty($field['help'])): ?>
            <br>
            <small><?= builderEscape($field['help']) ?></small>
        <?php endif; ?>
    </label>
</p>



==============================================================================
FILE: includes/builder/editor.php
==============================================================================

<?php
/**
 * Generic editor form.
 *
 * Expected variables include:
 * $id, $definition, $relationships, $relationshipOptions, $record,
 * $fields, $configFields, $configValues, $traits, $error
 */

$systemTraitsDefinition = $definition['system_traits'] ?? [];
$systemTraitsAfterField  = $systemTraitsDefinition['after_field'] ?? null;
$systemTraitsSelector    = $systemTraitsDefinition['selector_field'] ?? null;
$systemTraitGroups       = $systemTraitsDefinition['groups'] ?? [];

$storedSystemTraitValues = [];
$storedSystemTraitMaxValues = [];

/*
 * WAYFARER_ENTITY_SYSTEM_CONFIG_V55
 *
 * Universal Item/Character definitions live in Wayfarer code. Entity JSON
 * stores only the author's per-Entity values under config.system.
 */
if (!empty($record['config'])) {
    $decodedEditorConfig = json_decode($record['config'], true);

    if (
        is_array($decodedEditorConfig) &&
        !empty($decodedEditorConfig['system']) &&
        is_array($decodedEditorConfig['system'])
    ) {
        $compactSystem = $decodedEditorConfig['system'];

        if (
            isset($compactSystem['quantity']) &&
            is_array($compactSystem['quantity'])
        ) {
            $storedSystemTraitValues['item']['quantity'] =
                $compactSystem['quantity']['initial'] ?? 0;

            $storedSystemTraitMaxValues['item']['quantity'] =
                $compactSystem['quantity']['max'] ?? '';
        }

        if (array_key_exists('inventory_visibility', $compactSystem)) {
            $storedSystemTraitValues['item']['inventory_visibility'] =
                $compactSystem['inventory_visibility'];
        }

        if (array_key_exists('party_member', $compactSystem)) {
            $storedSystemTraitValues['character']['party_member'] =
                $compactSystem['party_member'];
        }
    }
}

/*
 * Legacy V49-V54 Entity JSON fallback.
 */
foreach ($traits as $storedTrait) {
    if (empty($storedTrait['system'])) {
        continue;
    }

    $storedGroup = (string)($storedTrait['system_group'] ?? '');
    $storedKey   = (string)($storedTrait['system_key'] ?? $storedTrait['name'] ?? '');

    if ($storedGroup === '' || $storedKey === '') {
        continue;
    }

    $storedSystemTraitValues[$storedGroup][$storedKey] =
        $storedTrait['initial'] ?? '';

    $storedSystemTraitMaxValues[$storedGroup][$storedKey] =
        $storedTrait['max'] ?? '';
}

/*
 * Migration fallback for the earlier experimental structure that stored
 * values under config.system_traits.
 */
if (!empty($record['config'])) {
    $decodedEditorConfig = json_decode($record['config'], true);

    if (
        is_array($decodedEditorConfig) &&
        !empty($decodedEditorConfig['system_traits']) &&
        is_array($decodedEditorConfig['system_traits'])
    ) {
        foreach ($decodedEditorConfig['system_traits'] as $groupName => $groupValues) {
            if (!is_array($groupValues)) {
                continue;
            }

            foreach ($groupValues as $traitName => $traitValue) {
                if (!isset($storedSystemTraitValues[$groupName][$traitName])) {
                    $storedSystemTraitValues[$groupName][$traitName] = $traitValue;
                }
            }
        }
    }
}

$renderSystemTraits = function () use (
    $record,
    $fields,
    $systemTraitsSelector,
    $systemTraitGroups,
    $storedSystemTraitValues,
    $storedSystemTraitMaxValues
) {
    if (!$systemTraitsSelector || empty($systemTraitGroups)) {
        return;
    }

    $selectedGroup = $record[$systemTraitsSelector]
        ?? ($fields[$systemTraitsSelector]['default'] ?? '');

    ?>
    <div
        data-system-trait-settings
        data-selector-field="<?= builderEscape($systemTraitsSelector) ?>"
    >
        <?php foreach ($systemTraitGroups as $groupName => $groupDefinition): ?>

            <?php
            $groupTraits = $groupDefinition['traits'] ?? [];

            if (empty($groupTraits)) {
                continue;
            }

            $groupActive = (string)$selectedGroup === (string)$groupName;
            ?>

            <div
                data-system-trait-group="<?= builderEscape($groupName) ?>"
                <?= $groupActive ? '' : 'style="display:none;"' ?>
            >
                <h3><?= builderEscape($groupDefinition['label'] ?? 'Settings') ?></h3>

                <?php if (!empty($groupDefinition['help'])): ?>
                    <p>
                        <small><?= builderEscape($groupDefinition['help']) ?></small>
                    </p>
                <?php endif; ?>

                <?php foreach ($groupTraits as $traitName => $traitDefinition): ?>

                    <?php
                    $fieldType = $traitDefinition['type'] ?? 'text';

                    $value =
                        $storedSystemTraitValues[$groupName][$traitName]
                        ?? ($traitDefinition['default'] ?? '');

                    $inputName =
                        'system_traits[' .
                        $groupName .
                        '][' .
                        $traitName .
                        ']';
                    ?>

                    <p>
                        <label>
                            <?= builderEscape($traitDefinition['label'] ?? $traitName) ?>

                            <?php if (!empty($traitDefinition['required'])): ?>
                                *
                            <?php endif; ?>

                            <br>

                            <?php if ($fieldType === 'number'): ?>

                                <input
                                    type="number"
                                    name="<?= builderEscape($inputName) ?>"
                                    value="<?= builderEscape($value) ?>"
                                    <?= isset($traitDefinition['min'])
                                        ? 'min="' . builderEscape($traitDefinition['min']) . '"'
                                        : '' ?>
                                    <?= isset($traitDefinition['max'])
                                        ? 'max="' . builderEscape($traitDefinition['max']) . '"'
                                        : '' ?>
                                    <?= isset($traitDefinition['step'])
                                        ? 'step="' . builderEscape($traitDefinition['step']) . '"'
                                        : '' ?>
                                    <?= $groupActive ? '' : 'disabled' ?>
                                >

                            <?php elseif ($fieldType === 'select'): ?>

                                <select
                                    name="<?= builderEscape($inputName) ?>"
                                    <?= $groupActive ? '' : 'disabled' ?>
                                >
                                    <?php foreach (($traitDefinition['options'] ?? []) as $optionValue => $optionLabel): ?>
                                        <option
                                            value="<?= builderEscape($optionValue) ?>"
                                            <?= (string)$value === (string)$optionValue
                                                ? 'selected'
                                                : '' ?>
                                        >
                                            <?= builderEscape($optionLabel) ?>
                                        </option>
                                    <?php endforeach; ?>
                                </select>

                            <?php elseif ($fieldType === 'binary'): ?>

                                <select
                                    name="<?= builderEscape($inputName) ?>"
                                    <?= $groupActive ? '' : 'disabled' ?>
                                >
                                    <option
                                        value="0"
                                        <?= (string)$value === '0' ? 'selected' : '' ?>
                                    >
                                        No
                                    </option>

                                    <option
                                        value="1"
                                        <?= (string)$value === '1' ? 'selected' : '' ?>
                                    >
                                        Yes
                                    </option>
                                </select>

                            <?php elseif ($fieldType === 'boolean'): ?>

                                <select
                                    name="<?= builderEscape($inputName) ?>"
                                    <?= $groupActive ? '' : 'disabled' ?>
                                >
                                    <option value="0" <?= !$value ? 'selected' : '' ?>>
                                        False
                                    </option>
                                    <option value="1" <?= $value ? 'selected' : '' ?>>
                                        True
                                    </option>
                                </select>

                            <?php else: ?>

                                <input
                                    type="text"
                                    name="<?= builderEscape($inputName) ?>"
                                    value="<?= builderEscape($value) ?>"
                                    <?= $groupActive ? '' : 'disabled' ?>
                                >

                            <?php endif; ?>

                            <?php if (!empty($traitDefinition['help'])): ?>
                                <br>
                                <small><?= builderEscape($traitDefinition['help']) ?></small>
                            <?php endif; ?>
                        </label>
                    </p>


                    <?php if (
                        $fieldType === 'number' &&
                        !empty(
                            $traitDefinition[
                                'show_system_min'
                            ]
                        ) &&
                        isset(
                            $traitDefinition[
                                'min'
                            ]
                        )
                    ): ?>

                        <!-- WAYFARER_SYSTEM_MINIMUM_DISPLAY_V44 -->
                        <p>
                            <label>
                                <?= builderEscape(
                                    $traitDefinition[
                                        'min_label'
                                    ]
                                    ?? 'Minimum'
                                ) ?>

                                <br>

                                <input
                                    type="number"
                                    value="<?= builderEscape(
                                        $traitDefinition[
                                            'min'
                                        ]
                                    ) ?>"
                                    disabled
                                    aria-disabled="true"
                                >

                                <?php if (
                                    !empty(
                                        $traitDefinition[
                                            'min_help'
                                        ]
                                    )
                                ): ?>
                                    <br>
                                    <small>
                                        <?= builderEscape(
                                            $traitDefinition[
                                                'min_help'
                                            ]
                                        ) ?>
                                    </small>
                                <?php endif; ?>
                            </label>
                        </p>

                    <?php endif; ?>


                    <?php if (
                        $fieldType === 'number' &&
                        !empty($traitDefinition['allow_author_max'])
                    ): ?>

                        <?php
                        $maxValue =
                            $storedSystemTraitMaxValues[$groupName][$traitName]
                            ?? '';

                        $maxInputName =
                            'system_trait_meta[' .
                            $groupName .
                            '][' .
                            $traitName .
                            '][max]';
                        ?>

                        <p>
                            <label>
                                <?= builderEscape(
                                    $traitDefinition['max_label']
                                    ?? 'Maximum'
                                ) ?>

                                <br>

                                <input
                                    type="number"
                                    name="<?= builderEscape($maxInputName) ?>"
                                    value="<?= builderEscape($maxValue) ?>"
                                    <?= isset($traitDefinition['min'])
                                        ? 'min="' . builderEscape($traitDefinition['min']) . '"'
                                        : '' ?>
                                    <?= $groupActive ? '' : 'disabled' ?>
                                >

                                <?php if (!empty($traitDefinition['max_help'])): ?>
                                    <br>
                                    <small>
                                        <?= builderEscape($traitDefinition['max_help']) ?>
                                    </small>
                                <?php endif; ?>
                            </label>
                        </p>

                    <?php endif; ?>

                <?php endforeach; ?>
            </div>

        <?php endforeach; ?>
    </div>
    <?php
};
?>
<?php
/* WAYFARER_OBJECT_CONTEXT_HEADING_V34 */
$builderRecordLabelField =
    (string)(
        $definition['list_field']
        ?? 'name'
    );

$builderRecordLabel =
    trim(
        (string)(
            $record[$builderRecordLabelField]
            ?? ''
        )
    );
?>
<h2
    class="builder-object-heading"
    data-builder-object-heading
    data-builder-object-label-field="<?= builderEscape(
        $builderRecordLabelField
    ) ?>"
>
    <span>
        <?= $id
            ? 'Edit ' . builderEscape($definition['singular'])
            : 'New ' . builderEscape($definition['singular']) ?>
    </span>

    <span
        class="builder-object-context"
        data-builder-object-context
        <?= $builderRecordLabel === ''
            ? 'hidden'
            : '' ?>
    >
        <span
            class="builder-object-context-separator"
            aria-hidden="true"
        >
            —
        </span>
        <span data-builder-object-context-label>
            <?= builderEscape($builderRecordLabel) ?>
        </span>
    </span>
</h2>

<?php if ($error): ?>
    <p style="color:red;">
        <?= builderEscape($error) ?>
    </p>
<?php endif; ?>

<?php if (
    ($definition['table'] ?? '') === 'wf_storylets' &&
    !empty($_GET['duplicated'])
): ?>
    <!-- WAYFARER_STORYLET_DUPLICATE_V83 -->
    <p style="color:#176b2c;">
        Storylet duplicated. This copy is saved as Draft.
    </p>
<?php endif; ?>

<?php if (
    $id &&
    ($definition['table'] ?? '') === 'wf_storylets'
): ?>
    <!-- WAYFARER_STORYLET_DUPLICATE_V83 -->
    <!-- WAYFARER_STORYLET_DUPLICATE_FORM_HOTFIX_V84 -->
    <div style="margin:0 0 1em;">
        <button
            type="submit"
            form="wayfarer-storylet-duplicate-form"
            class="secondary-button"
            onclick="return confirm('Duplicate the SAVED version of this Storylet?\n\nThe copy will open as Draft with \" - COPY\" added to its Name. Media links are copied. Child Branches are not duplicated. Unsaved changes on this page are not included.');"
        >
            Duplicate Storylet
        </button>

        <small style="margin-left:0.5em;">
            Copies the saved Storylet into a new Draft. If this is a Branch,
            the copy becomes a sibling Branch. Child Branches are not copied.
        </small>
    </div>
<?php endif; ?>

<form method="post" enctype="multipart/form-data">
    <?php if ($id): ?>
        <input type="hidden" name="id" value="<?= $id ?>">
    <?php endif; ?>

    <?php foreach ($relationships as $fieldName => $relationship): ?>
        <?php require __DIR__ . '/relationship-field.php'; ?>
    <?php endforeach; ?>

    <?php foreach ($fields as $fieldName => $field): ?>
        <?php require __DIR__ . '/field.php'; ?>

        <?php if (
            !empty($systemTraitsDefinition) &&
            $systemTraitsAfterField === $fieldName
        ): ?>
            <?php $renderSystemTraits(); ?>
        <?php endif; ?>
    <?php endforeach; ?>

    <?php if (
        !empty($systemTraitsDefinition) &&
        (
            $systemTraitsAfterField === null ||
            !array_key_exists($systemTraitsAfterField, $fields)
        )
    ): ?>
        <?php $renderSystemTraits(); ?>
    <?php endif; ?>

<?php

/*
|--------------------------------------------------------------------------
| MEDIA LIBRARY
|--------------------------------------------------------------------------
|
| Media is game-level and reusable. Each authored object may link one
| Image and one Audio asset.
|
*/

$builderMediaDefinition =
    getBuilderMediaLibraryDefinition();

$builderCurrentMedia =
    $id
        ? getBuilderMediaLinksForObject(
            $pdo,
            $gameId,
            $definition['table'],
            (int)$id
        )
        : [];

?>

<hr>

<h3>Media</h3>

<p>
    <small>
        Optional. Reuse an existing asset from this game's Media Library,
        upload a new asset, or leave the slot empty.
    </small>
</p>

<?php foreach ($builderMediaDefinition as $mediaSlot => $mediaDefinition): ?>

    <?php

    $currentMedia =
        $builderCurrentMedia[$mediaSlot]
        ?? null;

    $libraryAssets =
        getBuilderGameMediaAssets(
            $pdo,
            $gameId,
            $mediaSlot
        );

    $effectiveLimit =
        getBuilderEffectiveUploadLimit(
            (int)$mediaDefinition['app_max_bytes']
        );

    $defaultAction =
        $currentMedia
            ? 'keep'
            : 'none';

    ?>

    <fieldset
        data-media-slot="<?= builderEscape($mediaSlot) ?>"
        style="margin-bottom:1.25em;"
    >

        <legend>
            <strong>
                <?= builderEscape($mediaDefinition['label']) ?>
            </strong>
        </legend>

        <p>
            <small>
                <?= builderEscape($mediaDefinition['help']) ?>
                Maximum upload:
                <?= builderEscape(
                    formatBuilderBytes(
                        $effectiveLimit
                    )
                ) ?>.
            </small>
        </p>

        <?php if ($currentMedia): ?>

            <div style="margin-bottom:0.75em;">

                <strong>Current:</strong>
                <?= builderEscape($currentMedia['name']) ?>

                <?php if (!empty($currentMedia['original_filename'])): ?>
                    <small>
                        (<?= builderEscape($currentMedia['original_filename']) ?>)
                    </small>
                <?php endif; ?>

                <br>

                <?php if ($mediaSlot === 'image'): ?>

                    <img
                        src="<?= builderEscape(
                            builderMediaPublicUrl(
                                $currentMedia['relative_path']
                            )
                        ) ?>"
                        alt=""
                        style="max-width:320px;max-height:220px;margin-top:0.5em;"
                    >

                <?php elseif ($mediaSlot === 'audio'): ?>

                    <audio
                        controls
                        preload="metadata"
                        src="<?= builderEscape(
                            builderMediaPublicUrl(
                                $currentMedia['relative_path']
                            )
                        ) ?>"
                        style="margin-top:0.5em;"
                    ></audio>

                <?php endif; ?>

            </div>

            <p>
                <label>
                    <input
                        type="radio"
                        name="media_action[<?= builderEscape($mediaSlot) ?>]"
                        value="keep"
                        checked
                    >
                    Keep current
                </label>
            </p>

        <?php endif; ?>

        <p>
            <label>
                <input
                    type="radio"
                    name="media_action[<?= builderEscape($mediaSlot) ?>]"
                    value="none"
                    <?= !$currentMedia ? 'checked' : '' ?>
                >
                No <?= strtolower(builderEscape($mediaDefinition['label'])) ?>
            </label>
        </p>

        <p>
            <label>
                <input
                    type="radio"
                    name="media_action[<?= builderEscape($mediaSlot) ?>]"
                    value="existing"
                    <?= empty($libraryAssets) ? 'disabled' : '' ?>
                >
                Use existing
            </label>

            <br>

            <select
                name="media_existing[<?= builderEscape($mediaSlot) ?>]"
                data-media-existing
                disabled
            >
                <option value="">
                    -- Select existing <?= strtolower(builderEscape($mediaDefinition['label'])) ?> --
                </option>

                <?php foreach ($libraryAssets as $asset): ?>

                    <option value="<?= (int)$asset['id'] ?>">
                        <?= builderEscape($asset['name']) ?>

                        <?php if (
                            !empty($asset['original_filename']) &&
                            $asset['original_filename'] !== $asset['name']
                        ): ?>
                            — <?= builderEscape($asset['original_filename']) ?>
                        <?php endif; ?>
                    </option>

                <?php endforeach; ?>
            </select>

            <?php if (empty($libraryAssets)): ?>
                <br>
                <small>
                    No existing
                    <?= strtolower(builderEscape($mediaDefinition['label'])) ?>
                    assets have been uploaded to this game yet.
                </small>
            <?php endif; ?>
        </p>

        <p>
            <label>
                <input
                    type="radio"
                    name="media_action[<?= builderEscape($mediaSlot) ?>]"
                    value="upload"
                >
                Upload new
            </label>
        </p>

        <div data-media-upload-fields>

            <p>
                <label>
                    Library Name
                    <br>

                    <input
                        type="text"
                        name="media_name[<?= builderEscape($mediaSlot) ?>]"
                        maxlength="255"
                        placeholder="Optional — defaults to filename"
                        disabled
                    >
                </label>
            </p>

            <p>
                <input
                    type="file"
                    name="media_<?= builderEscape($mediaSlot) ?>"
                    accept="<?= builderEscape($mediaDefinition['accept']) ?>"
                    disabled
                >
            </p>

        </div>

    </fieldset>

<?php endforeach; ?>

    <?php foreach ($configFields as $fieldName => $field): ?>
        <?php require __DIR__ . '/config-field.php'; ?>
    <?php endforeach; ?>

    <?php if (
        ($definition['table'] ?? '') === 'wf_statuses'
    ): ?>

        <!-- WAYFARER_STATUS_LIFECYCLE_EDITOR_V88 -->
        <hr>

        <?php require __DIR__ . '/status-lifecycle.php'; ?>

    <?php endif; ?>

    <?php if (
        ($definition['table'] ?? '') === 'wf_regions'
    ): ?>

        <!-- WAYFARER_LINEAR_TRAVEL_EDITOR_INCLUDE_V72 -->
        <hr>

        <?php require __DIR__ . '/region-travel.php'; ?>

        <!-- WAYFARER_REGION_HUD_EDITOR_V64 -->
        <hr>

        <?php require __DIR__ . '/region-hud.php'; ?>

        <hr>

        <?php require __DIR__ . '/tick-effects.php'; ?>

    <?php elseif (
        ($definition['table'] ?? '') === 'wf_locations'
    ): ?>

        <!-- WAYFARER_LOCATION_GAMEPLAY_EDITOR_V35 -->
        <hr>

        <?php require __DIR__ . '/location-tick-effects.php'; ?>

    <?php elseif (
        ($definition['table'] ?? '') === 'wf_storylets'
    ): ?>

        <!-- WAYFARER_STORYLET_BUILDER_V56 -->
        <hr>

        <?php require __DIR__ . '/storylet-gameplay.php'; ?>

<?php endif; ?>

<?php if (!empty($definition['traits'])): ?>
        <hr>

        <h3>Traits</h3>

        <p>
            Traits are additional values associated with this
            <?= strtolower(builderEscape($definition['singular'])) ?>
            that can change during play.
        </p>

        <?php
        $allTraits = $traits;

        $traits = array_values(
            array_filter(
                $allTraits,
                function ($trait) {
                    return empty($trait['system']);
                }
            )
        );

        require __DIR__ . '/../traits/editor.php';

        $traits = $allTraits;
        ?>
    <?php endif; ?>

    <p>
        <button type="submit">
            Save <?= builderEscape($definition['singular']) ?>
        </button>
    </p>
</form>

<?php if (
    $id &&
    ($definition['table'] ?? '') === 'wf_storylets'
): ?>
    <form
        id="wayfarer-storylet-duplicate-form"
        method="post"
        hidden
    >
        <input type="hidden" name="action" value="duplicate">
        <input type="hidden" name="id" value="<?= (int)$id ?>">
    </form>
<?php endif; ?>

<?php if (
    $id &&
    !empty($definition['delete']['enabled'])
): ?>

    <hr>

    <div data-builder-delete-form>

        <h3>Danger Zone</h3>

        <p>
            Permanently delete this
            <?= strtolower(builderEscape($definition['singular'])) ?>.
            This cannot be undone.
        </p>

        <?php
        $deleteRecordLabel =
            (string)(
                $record[$definition['list_field']]
                ?? ''
            );

        $deleteConfirmation =
            'Delete "' .
            $deleteRecordLabel .
            "\"?\n\n" .
            'This permanently removes this ' .
            $definition['singular'] .
            ' and cannot be undone.';
        ?>

        <form
            method="post"
            onsubmit="return confirm(<?= builderEscape(
                json_encode(
                    $deleteConfirmation,
                    JSON_UNESCAPED_SLASHES |
                    JSON_UNESCAPED_UNICODE
                )
            ) ?>);"
        >
            <input
                type="hidden"
                name="action"
                value="delete"
            >

            <input
                type="hidden"
                name="id"
                value="<?= (int)$id ?>"
            >

            <button
                type="submit"
                style="color:#b00020;"
            >
                Delete <?= builderEscape($definition['singular']) ?>
            </button>
        </form>

    </div>

<?php endif; ?>



==============================================================================
FILE: includes/builder/field.php
==============================================================================

<?php
/**
 * Expected variables: $fieldName, $field, $record
 */
$value = $record[$fieldName] ?? '';
$fieldType = $field['type'] ?? 'text';
?>
<p>
    <label>
        <?= builderEscape($field['label']) ?>
        <?php if (!empty($field['required'])): ?>*<?php endif; ?>
        <br>

        <?php if ($fieldType === 'textarea'): ?>
            <textarea
                name="<?= builderEscape($fieldName) ?>"
                rows="6"
                cols="70"
            ><?= builderEscape($value) ?></textarea>

        <?php elseif ($fieldType === 'select'): ?>
            <select name="<?= builderEscape($fieldName) ?>">
                <?php foreach (($field['options'] ?? []) as $optionValue => $optionLabel): ?>
                    <option
                        value="<?= builderEscape($optionValue) ?>"
                        <?= $value == $optionValue ? 'selected' : '' ?>
                    >
                        <?= builderEscape($optionLabel) ?>
                    </option>
                <?php endforeach; ?>
            </select>

        <?php elseif ($fieldType === 'number'): ?>
            <input
                type="number"
                name="<?= builderEscape($fieldName) ?>"
                value="<?= builderEscape($value) ?>"
                <?= isset($field['min'])
                    ? 'min="' . builderEscape($field['min']) . '"'
                    : '' ?>
                <?= isset($field['max'])
                    ? 'max="' . builderEscape($field['max']) . '"'
                    : '' ?>
                <?= isset($field['step'])
                    ? 'step="' . builderEscape($field['step']) . '"'
                    : '' ?>
            >

        <?php else: ?>
            <input
                type="text"
                name="<?= builderEscape($fieldName) ?>"
                value="<?= builderEscape($value) ?>"
            >
        <?php endif; ?>

        <?php if (!empty($field['help'])): ?>
            <br>
            <small><?= builderEscape($field['help']) ?></small>
        <?php endif; ?>
    </label>
</p>



==============================================================================
FILE: includes/builder/functions.php
==============================================================================

<?php

/**
 * Shared helpers for the generic Wayfarer builder.
 */

function getRelationshipOptions(
    PDO $pdo,
    array $relationship,
    int $gameId
): array {
    $table      = $relationship['table'];
    $valueField = $relationship['value_field'];
    $labelField = $relationship['label_field'];
    $gameField  = $relationship['game_field'];

    $sql = "
        SELECT
            `$valueField` AS option_value,
            `$labelField` AS option_label
        FROM `$table`
        WHERE `$gameField` = ?
        ORDER BY `$labelField`
    ";

    $stmt = $pdo->prepare($sql);
    $stmt->execute([$gameId]);

    return $stmt->fetchAll();
}


function buildScopeQuery(array $definition): array
{
    $table = $definition['table'];
    $scope = $definition['scope'];

    if ($scope['type'] === 'game') {
        return [
            'from'  => "`$table`",
            'where' => "`$table`.`{$scope['field']}` = ?",
        ];
    }

    $scopeTable = $scope['scope_table'];
    $scopeField = $scope['field'];
    $scopeKey   = $scope['scope_key'];
    $gameField  = $scope['game_field'];

    return [
        'from' => "
            `$table`
            INNER JOIN `$scopeTable`
                ON `$table`.`$scopeField`
                = `$scopeTable`.`$scopeKey`
        ",
        'where' => "`$scopeTable`.`$gameField` = ?",
    ];
}


function getRelatedFieldValue(
    PDO $pdo,
    array $condition,
    $relationshipValue
) {
    if ($relationshipValue === '' || $relationshipValue === null) {
        return null;
    }

    $table       = $condition['source_table'];
    $sourceKey   = $condition['source_key'];
    $sourceField = $condition['source_field'];

    $sql = "
        SELECT `$sourceField`
        FROM `$table`
        WHERE `$sourceKey` = ?
        LIMIT 1
    ";

    $stmt = $pdo->prepare($sql);
    $stmt->execute([$relationshipValue]);

    $value = $stmt->fetchColumn();

    return $value === false ? null : $value;
}


function configFieldApplies(
    PDO $pdo,
    array $field,
    array $record
): bool {
    if (empty($field['condition'])) {
        return true;
    }

    $condition = $field['condition'];
    $relationshipName = $condition['relationship'] ?? null;

    if (!$relationshipName) {
        return false;
    }

    $relationshipValue = $record[$relationshipName] ?? '';

    $sourceValue = getRelatedFieldValue(
        $pdo,
        $condition,
        $relationshipValue
    );

    return (string)$sourceValue === (string)$condition['equals'];
}


function builderEscape($value): string
{
    return htmlspecialchars((string)$value, ENT_QUOTES, 'UTF-8');
}

/*
|--------------------------------------------------------------------------
| DELETE BUILDER RECORD
|--------------------------------------------------------------------------
|
| Permanently removes one authored record after:
|
| 1. verifying it belongs to the current game;
| 2. checking configured dependencies;
| 3. allowing the database to reject any other protected references.
|
| This is intentionally generic. Builder types describe their own
| dependency rules in config/builder-types.php.
|
*/

function deleteBuilderRecord(
    PDO $pdo,
    array $definition,
    int $gameId,
    int $id
): array {

    $deleteDefinition =
        $definition['delete'] ?? [];

    if (empty($deleteDefinition['enabled'])) {
        return [
            'deleted' => false,
            'error'   => 'Deletion is not enabled for this type.'
        ];
    }

    if ($id <= 0) {
        return [
            'deleted' => false,
            'error'   => 'A valid record ID is required.'
        ];
    }

    $table =
        $definition['table'];

    $listField =
        $definition['list_field'];

    $singular =
        $definition['singular'] ?? 'record';

    $scopeQuery =
        buildScopeQuery($definition);

    /*
     * Verify the record belongs to this game before doing anything else.
     */
    $sql = "
        SELECT
            `$table`.`id`,
            `$table`.`$listField` AS record_label,
            `$table`.`config` AS record_config
        FROM {$scopeQuery['from']}
        WHERE `$table`.`id` = ?
          AND {$scopeQuery['where']}
        LIMIT 1
    ";

    $stmt =
        $pdo->prepare($sql);

    $stmt->execute([
        $id,
        $gameId
    ]);

    $record =
        $stmt->fetch();

    if (!$record) {
        return [
            'deleted' => false,
            'error'   => $singular . ' not found.'
        ];
    }

    $recordLabel =
        (string)($record['record_label'] ?? '');

    /*
     * Check dependency rules declared by this builder type.
     */
    foreach (
        ($deleteDefinition['dependencies'] ?? [])
        as $dependency
    ) {

        $dependencyTable =
            $dependency['table'] ?? '';

        $foreignKey =
            $dependency['foreign_key'] ?? '';

        $dependencyLabel =
            $dependency['label'] ?? 'related records';

        if (
            !preg_match('/^[A-Za-z0-9_]+$/', $dependencyTable) ||
            !preg_match('/^[A-Za-z0-9_]+$/', $foreignKey)
        ) {
            return [
                'deleted' => false,
                'error'   =>
                    'The delete dependency configuration for this ' .
                    $singular .
                    ' is invalid.'
            ];
        }

        $dependencySql = "
            SELECT COUNT(*)
            FROM `$dependencyTable`
            WHERE `$foreignKey` = ?
        ";

        $dependencyStmt =
            $pdo->prepare($dependencySql);

        $dependencyStmt->execute([
            $id
        ]);

        $dependencyCount =
            (int)$dependencyStmt->fetchColumn();

        if ($dependencyCount > 0) {

            $namePart =
                $recordLabel !== ''
                    ? ' "' . $recordLabel . '"'
                    : '';

            return [
                'deleted' => false,
                'error'   =>
                    'Cannot delete ' .
                    $singular .
                    $namePart .
                    '. It still has ' .
                    $dependencyCount .
                    ' ' .
                    $dependencyLabel .
                    '. Move or delete those first.'
            ];
        }
    }

    /*
     * Delete only after all explicit dependency checks have passed.
     *
     * A database foreign-key constraint may still block deletion if a
     * dependency has not yet been described in builder-types.php. In that
     * case, report the failure rather than crashing the builder.
     */
    try {

        $deleteSql = "
            DELETE FROM `$table`
            WHERE id = ?
            LIMIT 1
        ";

        $deleteStmt =
            $pdo->prepare($deleteSql);

        $deleteStmt->execute([
            $id
        ]);

    } catch (PDOException $e) {

        return [
            'deleted' => false,
            'error'   =>
                'This ' .
                $singular .
                ' could not be deleted because another record still ' .
                'references it.'
        ];
    }

    if ($deleteStmt->rowCount() !== 1) {
        return [
            'deleted' => false,
            'error'   =>
                'The ' .
                $singular .
                ' was not deleted.'
        ];
    }

    /*
     * WAYFARER MEDIA LINK CLEANUP
     *
     * Media is game-level and reusable. Deleting this authored object
     * removes only its media associations, never the underlying asset.
     */
    $mediaLinkDelete =
        $pdo->prepare(
            "
            DELETE FROM wf_media_links
            WHERE object_type = ?
              AND object_id = ?
            "
        );

    $mediaLinkDelete->execute([
        $table,
        $id
    ]);

    return [
        'deleted' => true,
        'error'   => ''
    ];
}

/*
|--------------------------------------------------------------------------
| WAYFARER MEDIA LIBRARY
|--------------------------------------------------------------------------
|
| Uploaded files are game-level reusable assets stored in wf_media.
| wf_media_links associates those assets with authored objects.
|
*/

function getBuilderMediaLibraryDefinition(): array
{
    return [

        'image' => [
            'label' => 'Image',

            'directory' =>
                'images',

            'accept' =>
                '.jpg,.jpeg,.png,.gif',

            'app_max_bytes' =>
                10 * 1024 * 1024,

            'allowed_mime' => [
                'image/jpeg' => 'jpg',
                'image/png'  => 'png',
                'image/gif'  => 'gif'
            ],

            'help' =>
                'Optional. JPG, PNG, or GIF.'
        ],

        'audio' => [
            'label' => 'Audio',

            'directory' =>
                'audio',

            'accept' =>
                '.mp3,audio/mpeg',

            'app_max_bytes' =>
                30 * 1024 * 1024,

            'allowed_mime' => [
                'audio/mpeg'     => 'mp3',
                'audio/mp3'      => 'mp3',
                'audio/x-mpeg'   => 'mp3',
                'audio/mpeg3'    => 'mp3',
                'audio/x-mpeg-3' => 'mp3'
            ],

            'help' =>
                'Optional. MP3 only.'
        ]

    ];
}


function builderIniSizeToBytes($value): int
{
    if ($value === false || $value === null) {
        return 0;
    }

    $value =
        trim(
            (string)$value
        );

    if (
        $value === '' ||
        $value === '-1'
    ) {
        return 0;
    }

    $last =
        strtolower(
            substr(
                $value,
                -1
            )
        );

    $number =
        (float)$value;

    if ($last === 'g') {
        $number *= 1024;
        $number *= 1024;
        $number *= 1024;
    } elseif ($last === 'm') {
        $number *= 1024;
        $number *= 1024;
    } elseif ($last === 'k') {
        $number *= 1024;
    }

    return (int)floor($number);
}


function getBuilderEffectiveUploadLimit(
    int $applicationLimit
): int {

    $limits = [
        $applicationLimit
    ];

    $uploadLimit =
        builderIniSizeToBytes(
            ini_get(
                'upload_max_filesize'
            )
        );

    $postLimit =
        builderIniSizeToBytes(
            ini_get(
                'post_max_size'
            )
        );

    if ($uploadLimit > 0) {
        $limits[] =
            $uploadLimit;
    }

    if ($postLimit > 0) {
        $limits[] =
            $postLimit;
    }

    return min(
        $limits
    );
}


function formatBuilderBytes(
    int $bytes
): string {

    if ($bytes >= 1024 * 1024 * 1024) {
        return rtrim(
            rtrim(
                number_format(
                    $bytes /
                    1024 /
                    1024 /
                    1024,
                    1
                ),
                '0'
            ),
            '.'
        ) . ' GB';
    }

    if ($bytes >= 1024 * 1024) {
        return rtrim(
            rtrim(
                number_format(
                    $bytes /
                    1024 /
                    1024,
                    1
                ),
                '0'
            ),
            '.'
        ) . ' MB';
    }

    if ($bytes >= 1024) {
        return rtrim(
            rtrim(
                number_format(
                    $bytes /
                    1024,
                    1
                ),
                '0'
            ),
            '.'
        ) . ' KB';
    }

    return $bytes .
        ' bytes';
}


function builderMediaPublicUrl(
    string $relativePath
): string {

    return '../' .
        ltrim(
            $relativePath,
            '/'
        );
}


function getBuilderGameMediaAssets(
    PDO $pdo,
    int $gameId,
    string $mediaType
): array {

    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                name,
                original_filename,
                relative_path,
                mime_type,
                file_size
            FROM wf_media
            WHERE game_id = ?
              AND media_type = ?
            ORDER BY
                name,
                original_filename,
                id
            "
        );

    $stmt->execute([
        $gameId,
        $mediaType
    ]);

    return $stmt->fetchAll();
}


function getBuilderMediaLinksForObject(
    PDO $pdo,
    int $gameId,
    string $objectType,
    int $objectId
): array {

    if ($objectId <= 0) {
        return [];
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT
                l.slot,
                m.id,
                m.name,
                m.media_type,
                m.original_filename,
                m.relative_path,
                m.mime_type,
                m.file_size
            FROM wf_media_links l
            INNER JOIN wf_media m
                ON m.id = l.media_id
            WHERE l.object_type = ?
              AND l.object_id = ?
              AND m.game_id = ?
            "
        );

    $stmt->execute([
        $objectType,
        $objectId,
        $gameId
    ]);

    $result = [];

    foreach ($stmt->fetchAll() as $row) {
        $result[
            $row['slot']
        ] = $row;
    }

    return $result;
}


function builderMediaUploadErrorMessage(
    int $error,
    string $label
): string {

    if (
        $error === UPLOAD_ERR_INI_SIZE ||
        $error === UPLOAD_ERR_FORM_SIZE
    ) {
        return $label .
            ' exceeds the server upload limit.';
    }

    if ($error === UPLOAD_ERR_PARTIAL) {
        return $label .
            ' was only partially uploaded. Please try again.';
    }

    if ($error === UPLOAD_ERR_NO_TMP_DIR) {
        return 'The server has no temporary upload directory.';
    }

    if ($error === UPLOAD_ERR_CANT_WRITE) {
        return 'The server could not write the uploaded file.';
    }

    if ($error === UPLOAD_ERR_EXTENSION) {
        return $label .
            ' was blocked by a server extension.';
    }

    return $label .
        ' upload failed.';
}


function validateBuilderMediaUpload(
    array $file,
    string $slot,
    array $slotDefinition
): array {

    $label =
        $slotDefinition['label'];

    $uploadError =
        (int)(
            $file['error']
            ?? UPLOAD_ERR_NO_FILE
        );

    if ($uploadError === UPLOAD_ERR_NO_FILE) {
        return [
            'valid' => false,
            'error' =>
                'Choose a file to upload for ' .
                strtolower($label) .
                '.'
        ];
    }

    if ($uploadError !== UPLOAD_ERR_OK) {
        return [
            'valid' => false,
            'error' =>
                builderMediaUploadErrorMessage(
                    $uploadError,
                    $label
                )
        ];
    }

    $tmpName =
        (string)(
            $file['tmp_name']
            ?? ''
        );

    if (
        $tmpName === '' ||
        !is_uploaded_file(
            $tmpName
        )
    ) {
        return [
            'valid' => false,
            'error' =>
                'The uploaded ' .
                strtolower($label) .
                ' could not be verified.'
        ];
    }

    $size =
        (int)(
            $file['size']
            ?? 0
        );

    $effectiveLimit =
        getBuilderEffectiveUploadLimit(
            (int)$slotDefinition['app_max_bytes']
        );

    if (
        $size <= 0 ||
        $size > $effectiveLimit
    ) {
        return [
            'valid' => false,
            'error' =>
                $label .
                ' must be no larger than ' .
                formatBuilderBytes(
                    $effectiveLimit
                ) .
                '.'
        ];
    }

    $originalName =
        basename(
            (string)(
                $file['name']
                ?? ''
            )
        );

    $originalExtension =
        strtolower(
            pathinfo(
                $originalName,
                PATHINFO_EXTENSION
            )
        );

    $finfo =
        finfo_open(
            FILEINFO_MIME_TYPE
        );

    $mime =
        $finfo
            ? finfo_file(
                $finfo,
                $tmpName
            )
            : false;

    if ($finfo) {
        finfo_close(
            $finfo
        );
    }

    $allowedMime =
        $slotDefinition['allowed_mime'];

    if (
        !$mime ||
        !isset(
            $allowedMime[$mime]
        )
    ) {
        return [
            'valid' => false,
            'error' =>
                'Unsupported ' .
                strtolower($label) .
                ' file type.'
        ];
    }

    $normalizedExtension =
        $allowedMime[$mime];

    if (
        $slot === 'image' &&
        !in_array(
            $originalExtension,
            [
                'jpg',
                'jpeg',
                'png',
                'gif'
            ],
            true
        )
    ) {
        return [
            'valid' => false,
            'error' =>
                'Image filename must end in JPG, JPEG, PNG, or GIF.'
        ];
    }

    if (
        $slot === 'audio' &&
        $originalExtension !== 'mp3'
    ) {
        return [
            'valid' => false,
            'error' =>
                'Audio filename must end in MP3.'
        ];
    }

    if ($slot === 'image') {

        $imageInfo =
            @getimagesize(
                $tmpName
            );

        if ($imageInfo === false) {
            return [
                'valid' => false,
                'error' =>
                    'The uploaded image is not a valid raster image.'
            ];
        }
    }

    return [
        'valid'              => true,
        'error'              => '',
        'tmp_name'           => $tmpName,
        'size'               => $size,
        'mime'               => $mime,
        'extension'          => $normalizedExtension,
        'original_filename'  => $originalName
    ];
}


function builderMediaDefaultName(
    string $originalFilename
): string {

    $name =
        pathinfo(
            $originalFilename,
            PATHINFO_FILENAME
        );

    $name =
        preg_replace(
            '/[_-]+/',
            ' ',
            $name
        );

    $name =
        trim(
            preg_replace(
                '/\s+/',
                ' ',
                $name
            )
        );

    if ($name === '') {
        return 'Untitled Media';
    }

    return $name;
}


function setBuilderMediaLink(
    PDO $pdo,
    int $mediaId,
    string $objectType,
    int $objectId,
    string $slot
): void {

    $stmt =
        $pdo->prepare(
            "
            INSERT INTO wf_media_links
                (
                    media_id,
                    object_type,
                    object_id,
                    slot
                )
            VALUES
                (?, ?, ?, ?)
            ON DUPLICATE KEY UPDATE
                media_id = VALUES(media_id)
            "
        );

    $stmt->execute([
        $mediaId,
        $objectType,
        $objectId,
        $slot
    ]);
}


function removeBuilderMediaLink(
    PDO $pdo,
    string $objectType,
    int $objectId,
    string $slot
): void {

    $stmt =
        $pdo->prepare(
            "
            DELETE FROM wf_media_links
            WHERE object_type = ?
              AND object_id = ?
              AND slot = ?
            "
        );

    $stmt->execute([
        $objectType,
        $objectId,
        $slot
    ]);
}


function applyBuilderMediaSelections(
    PDO $pdo,
    int $gameId,
    string $objectType,
    int $objectId,
    array $post,
    array $files
): array {

    if ($objectId <= 0) {
        return [
            'saved' => false,
            'error' =>
                'Media cannot be attached until the authored object has an ID.'
        ];
    }

    $definition =
        getBuilderMediaLibraryDefinition();

    $current =
        getBuilderMediaLinksForObject(
            $pdo,
            $gameId,
            $objectType,
            $objectId
        );

    $plan = [];

    /*
     * First validate every requested operation. Nothing changes yet.
     */
    foreach ($definition as $slot => $slotDefinition) {

        $defaultAction =
            isset($current[$slot])
                ? 'keep'
                : 'none';

        $action =
            (string)(
                $post['media_action'][$slot]
                ?? $defaultAction
            );

        if (
            !in_array(
                $action,
                [
                    'keep',
                    'none',
                    'existing',
                    'upload'
                ],
                true
            )
        ) {
            return [
                'saved' => false,
                'error' =>
                    'Invalid ' .
                    strtolower($slotDefinition['label']) .
                    ' action.'
            ];
        }

        if ($action === 'keep') {
            $plan[$slot] = [
                'action' => 'keep'
            ];

            continue;
        }

        if ($action === 'none') {
            $plan[$slot] = [
                'action' => 'none'
            ];

            continue;
        }

        if ($action === 'existing') {

            $mediaId =
                (int)(
                    $post['media_existing'][$slot]
                    ?? 0
                );

            if ($mediaId <= 0) {
                return [
                    'saved' => false,
                    'error' =>
                        'Choose an existing ' .
                        strtolower($slotDefinition['label']) .
                        '.'
                ];
            }

            $stmt =
                $pdo->prepare(
                    "
                    SELECT id
                    FROM wf_media
                    WHERE id = ?
                      AND game_id = ?
                      AND media_type = ?
                    LIMIT 1
                    "
                );

            $stmt->execute([
                $mediaId,
                $gameId,
                $slot
            ]);

            if (!$stmt->fetchColumn()) {
                return [
                    'saved' => false,
                    'error' =>
                        'The selected existing ' .
                        strtolower($slotDefinition['label']) .
                        ' is not available to this game.'
                ];
            }

            $plan[$slot] = [
                'action'   => 'existing',
                'media_id' => $mediaId
            ];

            continue;
        }

        $fileKey =
            'media_' .
            $slot;

        $validation =
            validateBuilderMediaUpload(
                $files[$fileKey] ?? [],
                $slot,
                $slotDefinition
            );

        if (!$validation['valid']) {
            return [
                'saved' => false,
                'error' => $validation['error']
            ];
        }

        $requestedName =
            trim(
                (string)(
                    $post['media_name'][$slot]
                    ?? ''
                )
            );

        if ($requestedName === '') {
            $requestedName =
                builderMediaDefaultName(
                    $validation['original_filename']
                );
        }

        if (
            mb_strlen(
                $requestedName
            ) > 255
        ) {
            return [
                'saved' => false,
                'error' =>
                    $slotDefinition['label'] .
                    ' library name must be 255 characters or fewer.'
            ];
        }

        $plan[$slot] =
            array_merge(
                [
                    'action' => 'upload',
                    'name'   => $requestedName
                ],
                $validation
            );
    }

    $newPhysicalPaths = [];

    try {

        $pdo->beginTransaction();

        foreach ($plan as $slot => $operation) {

            if ($operation['action'] === 'keep') {
                continue;
            }

            if ($operation['action'] === 'none') {

                removeBuilderMediaLink(
                    $pdo,
                    $objectType,
                    $objectId,
                    $slot
                );

                continue;
            }

            if ($operation['action'] === 'existing') {

                setBuilderMediaLink(
                    $pdo,
                    (int)$operation['media_id'],
                    $objectType,
                    $objectId,
                    $slot
                );

                continue;
            }

            $slotDefinition =
                $definition[$slot];

            $relativeDirectory =
                'uploads/media/game_' .
                $gameId .
                '/' .
                $slotDefinition['directory'];

            $absoluteDirectory =
                dirname(__DIR__, 2) .
                '/' .
                $relativeDirectory;

            if (
                !is_dir(
                    $absoluteDirectory
                ) &&
                !mkdir(
                    $absoluteDirectory,
                    0755,
                    true
                )
            ) {
                throw new RuntimeException(
                    'Wayfarer could not create the ' .
                    strtolower($slotDefinition['label']) .
                    ' media directory.'
                );
            }

            $storedFilename =
                bin2hex(
                    random_bytes(16)
                ) .
                '.' .
                $operation['extension'];

            $relativePath =
                $relativeDirectory .
                '/' .
                $storedFilename;

            $absolutePath =
                dirname(__DIR__, 2) .
                '/' .
                $relativePath;

            if (
                !move_uploaded_file(
                    $operation['tmp_name'],
                    $absolutePath
                )
            ) {
                throw new RuntimeException(
                    'Wayfarer could not save the uploaded ' .
                    strtolower($slotDefinition['label']) .
                    '.'
                );
            }

            $newPhysicalPaths[] =
                $absolutePath;

            $insert =
                $pdo->prepare(
                    "
                    INSERT INTO wf_media
                        (
                            game_id,
                            media_type,
                            name,
                            original_filename,
                            stored_filename,
                            relative_path,
                            mime_type,
                            file_size,
                            created_at
                        )
                    VALUES
                        (?, ?, ?, ?, ?, ?, ?, ?, NOW())
                    "
                );

            $insert->execute([
                $gameId,
                $slot,
                $operation['name'],
                $operation['original_filename'],
                $storedFilename,
                $relativePath,
                $operation['mime'],
                $operation['size']
            ]);

            $mediaId =
                (int)$pdo->lastInsertId();

            setBuilderMediaLink(
                $pdo,
                $mediaId,
                $objectType,
                $objectId,
                $slot
            );
        }

        $pdo->commit();

    } catch (Throwable $e) {

        if ($pdo->inTransaction()) {
            $pdo->rollBack();
        }

        foreach ($newPhysicalPaths as $path) {
            if (is_file($path)) {
                @unlink($path);
            }
        }

        return [
            'saved' => false,
            'error' => $e->getMessage()
        ];
    }

    return [
        'saved' => true,
        'error' => ''
    ];
}



==============================================================================
FILE: includes/builder/load-record.php
==============================================================================

<?php

/**
 * Creates the default builder state and, when editing, loads the existing
 * record/config/traits after verifying that the record belongs to the game.
 */
function loadBuilderRecord(
    PDO $pdo,
    array $definition,
    int $gameId,
    int $id
): array {
    $table         = $definition['table'];
    $relationships = $definition['relationships'] ?? [];
    $fields        = $definition['fields'] ?? [];
    $configFields  = $definition['config_fields'] ?? [];

    $record = [
        'id' => null,
    ];

    foreach ($relationships as $fieldName => $relationship) {
        $record[$fieldName] = '';
    }

    foreach ($fields as $fieldName => $field) {
        $record[$fieldName] = $field['default'] ?? '';
    }

    $configValues = [];

    foreach ($configFields as $fieldName => $field) {
        $configValues[$fieldName] = $field['default'] ?? '';
    }

    $traits = [];

    if (!$id) {
        return [
            'record'       => $record,
            'configValues' => $configValues,
            'traits'       => $traits,
        ];
    }

    $scopeQuery = buildScopeQuery($definition);

    $sql = "
        SELECT `$table`.*
        FROM {$scopeQuery['from']}
        WHERE `$table`.`id` = ?
          AND {$scopeQuery['where']}
        LIMIT 1
    ";

    $stmt = $pdo->prepare($sql);
    $stmt->execute([$id, $gameId]);

    $existing = $stmt->fetch();

    if (!$existing) {
        die('Record not found.');
    }

    $record = array_merge($record, $existing);

    if (!empty($existing['config'])) {
        $decodedConfig = json_decode($existing['config'], true);

        if (is_array($decodedConfig)) {
            foreach ($configFields as $fieldName => $field) {
                if (array_key_exists($fieldName, $decodedConfig)) {
                    $configValues[$fieldName] = $decodedConfig[$fieldName];
                }
            }

            if (
                !empty($definition['traits']) &&
                isset($decodedConfig['traits']) &&
                is_array($decodedConfig['traits'])
            ) {
                $traits = $decodedConfig['traits'];
            }
        }
    }

    return [
        'record'       => $record,
        'configValues' => $configValues,
        'traits'       => $traits,
    ];
}



==============================================================================
FILE: includes/builder/location-tick-effects.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Location Gameplay Adapter
|--------------------------------------------------------------------------
|
| WAYFARER_LOCATION_TICK_EFFECTS_ADAPTER_V35
|
| WAYFARER_LOCATION_EFFECTS_V42
|
| Locations expose deliberately separate authoring concepts:
|
|   Conditions -> whether the Location is eligible to trigger.
|   Effects    -> one-time state changes when it triggers.
|
| Conditions and Effects have separate builder tabs.
|
| Current target model:
|   - Game Traits
|   - Current Region Traits
|   - Navigation Position when the parent Region is linear
|
| Location Traits are not runtime targets yet because mutable per-Location
| Trait state has not been introduced.
|
| Expected variables:
|   $pdo
|   $gameId
|   $game
|   $record
|   $id
|
*/

require_once __DIR__ . '/../gameplay/functions.php';


$locationGameplayConfig = [];

if (
    !empty(
        $record['config']
    )
) {

    $decoded =
        json_decode(
            (string)$record['config'],
            true
        );

    if (is_array($decoded)) {
        $locationGameplayConfig =
            $decoded;
    }
}


/*
 * Failed POSTs retain the author's submitted one-time Effect rows.
 * An absent effects collection during POST is canonical empty, which allows
 * removal of the final Effect.
 */
if (
    $_SERVER['REQUEST_METHOD'] === 'POST'
) {

    $gameplayEffects =
        isset(
            $_POST['effects']
        ) &&
        is_array(
            $_POST['effects']
        )
            ? array_values(
                $_POST['effects']
            )
            : [];

} else {

    $gameplayEffects =
        isset(
            $locationGameplayConfig['effects']
        ) &&
        is_array(
            $locationGameplayConfig['effects']
        )
            ? array_values(
                $locationGameplayConfig['effects']
            )
            : [];
}


/*
 * Failed POSTs retain the author's submitted Tick Effect rows.
 */
if (
    $_SERVER['REQUEST_METHOD'] === 'POST'
) {

    $gameplayTickEffects =
        isset(
            $_POST['tick_effects']
        ) &&
        is_array(
            $_POST['tick_effects']
        )
            ? array_values(
                $_POST['tick_effects']
            )
            : [];

} else {

    $gameplayTickEffects =
        isset(
            $locationGameplayConfig['tick_effects']
        ) &&
        is_array(
            $locationGameplayConfig['tick_effects']
        )
            ? array_values(
                $locationGameplayConfig['tick_effects']
            )
            : [];
}


/*
 * Game Trait targets.
 */
$gameConfig = [];

if (
    !empty(
        $game['config']
    )
) {

    $decoded =
        json_decode(
            (string)$game['config'],
            true
        );

    if (is_array($decoded)) {
        $gameConfig =
            $decoded;
    }
}


$gameplayGameTraitTargets =
    gameplayNumericTraitTargets(
        $gameConfig['traits']
            ?? [],
        'game'
    );


/*
 * Parent Region context supplies Region Trait targets and determines whether
 * Navigation Position is valid for this Location.
 */
$parentRegionTraits = [];
$parentRegionNavigationType = '';

$parentRegionId =
    (int)(
        $record['region_id']
        ?? 0
    );

if ($parentRegionId > 0) {

    $regionStmt =
        $pdo->prepare(
            "
            SELECT
                navigation_type,
                config
            FROM wf_regions
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

    $regionStmt->execute([
        $parentRegionId,
        $gameId,
    ]);

    $parentRegion =
        $regionStmt->fetch(
            PDO::FETCH_ASSOC
        );

    if ($parentRegion) {

        $parentRegionNavigationType =
            (string)(
                $parentRegion['navigation_type']
                ?? ''
            );

        if (
            !empty(
                $parentRegion['config']
            )
        ) {

            $decoded =
                json_decode(
                    (string)$parentRegion['config'],
                    true
                );

            if (
                is_array($decoded) &&
                isset(
                    $decoded['traits']
                ) &&
                is_array(
                    $decoded['traits']
                )
            ) {
                $parentRegionTraits =
                    $decoded['traits'];
            }
        }
    }
}


$gameplayScopeTraitTargets =
    gameplayNumericTraitTargets(
        $parentRegionTraits,
        'region'
    );


$gameplayScopeKey =
    'region';

$gameplayScopeLabel =
    'Region';

$gameplayAllowNavigation =
    strtolower(
        trim(
            $parentRegionNavigationType
        )
    ) ===
    'linear';

$gameplayNavigationType =
    $parentRegionNavigationType;


/* WAYFARER_UNIVERSAL_LOCATION_TARGETS_V56 */
$gameplayTargetCatalog =
    gameplayRuntimeStateTargets(
        $pdo,
        $gameId
    );

$gameplayConditionTargets =
    $gameplayTargetCatalog;


/*
 * WAYFARER_LOCATION_CONDITIONS_V45
 *
 * Empty Conditions mean the Location is always eligible.
 */
if (
    $_SERVER['REQUEST_METHOD'] ===
    'POST'
) {

    $locationGameplayConditions =
        $_POST['conditions']
        ?? null;

} else {

    $locationGameplayConditions =
        $locationGameplayConfig[
            'conditions'
        ]
        ?? null;
}


$gameplayEffectDescription =
    "These Effects run once when this Location is triggered.";

$gameplayAllowEffectNavigation =
    false;

/*
 * WAYFARER_LOCATION_EFFECTS_ONLY_V43
 *
 * Locations are event boundaries. Recurring simulation belongs to Game and
 * Region Tick Effects; Location state changes belong to one-time Effects.
 */
?>
<!-- WAYFARER_LOCATION_CONDITIONS_TAB_V45_1 -->
<section
    class="builder-conditions-panel"
    data-builder-conditions-panel
>
    <h3>Conditions</h3>

    <p class="builder-field-help">
        Optional. The Location triggers only when these conditions are true
        at the moment the player reaches or crosses its Position. If they
        are false, travel passes through the Location normally.
    </p>

    <?php
    $conditionEditorNode =
        $locationGameplayConditions;

    $conditionEditorName =
        'conditions';

    $conditionEditorTargets =
        $gameplayConditionTargets;

    require __DIR__ .
        '/../gameplay/condition-editor.php';
    ?>
</section>


<section
    class="builder-effects-panel"
    data-builder-effects-panel
>
    <?php require __DIR__ . '/../gameplay/effects-editor.php'; ?>
</section>
<?php



==============================================================================
FILE: includes/builder/navigation.php
==============================================================================

<?php
/** @var array $builderTypes */
/** @var string $type */
/** @var int $gameId */
/** @var string $builderPage */
?>
<nav>
    <?php foreach ($builderTypes as $navType => $navDefinition): ?>
        <?php if ($navType === $type): ?>
            <strong><?= builderEscape($navDefinition['label']) ?></strong>
        <?php else: ?>
            <a href="<?= builderEscape($builderPage) ?>?game=<?= $gameId ?>&amp;type=<?= urlencode($navType) ?>">
                <?= builderEscape($navDefinition['label']) ?>
            </a>
        <?php endif; ?>
        &nbsp;&nbsp;
    <?php endforeach; ?>
</nav>



==============================================================================
FILE: includes/builder/region-hud.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Region HUD Editor
 * WAYFARER_REGION_HUD_EDITOR_V64
 * --------------------------------------------------------------------------
 *
 * A Region chooses which global/current-Region values are exposed in the
 * persistent player HUD. The underlying state remains owned by the original
 * Trait scope; the HUD is only a Region-specific presentation configuration.
 *
 * V64 supports progress_bar components. Future types can reuse config.hud.
 */

$regionHudConfig = [];

if (
    !empty($record['config'])
) {
    $decodedRegionHudConfig =
        json_decode(
            (string)$record['config'],
            true
        );

    if (is_array($decodedRegionHudConfig)) {
        $regionHudConfig =
            isset($decodedRegionHudConfig['hud']) &&
            is_array($decodedRegionHudConfig['hud'])
                ? $decodedRegionHudConfig['hud']
                : [];
    }
}

$regionHudEnabled =
    !empty(
        $regionHudConfig['enabled']
    );

$regionHudComponents =
    isset($regionHudConfig['components']) &&
    is_array($regionHudConfig['components'])
        ? array_values(
            $regionHudConfig['components']
        )
        : [];


/*
 * Build bounded numeric Trait choices.
 * A progress bar needs a known numeric minimum and maximum.
 */
$regionHudSources = [];

$regionHudGameStmt =
    $pdo->prepare(
        "
        SELECT config
        FROM wf_games
        WHERE id = ?
        LIMIT 1
        "
    );

$regionHudGameStmt->execute([
    (int)$gameId,
]);

$regionHudGameRaw =
    $regionHudGameStmt->fetchColumn();

$regionHudGameConfig =
    $regionHudGameRaw
        ? json_decode(
            (string)$regionHudGameRaw,
            true
        )
        : [];

if (!is_array($regionHudGameConfig)) {
    $regionHudGameConfig = [];
}


$appendHudTrait =
    static function (
        array &$choices,
        string $scope,
        array $trait
    ): void {

        $id =
            trim(
                (string)(
                    $trait['id']
                    ?? ''
                )
            );

        $name =
            trim(
                (string)(
                    $trait['name']
                    ?? $id
                )
            );

        $type =
            strtolower(
                trim(
                    (string)(
                        $trait['type']
                        ?? ''
                    )
                )
            );

        $min =
            $trait['min']
            ?? null;

        $max =
            $trait['max']
            ?? null;

        if (
            $id === '' ||
            $type !== 'number' ||
            !is_numeric($min) ||
            !is_numeric($max) ||
            (float)$max <= (float)$min
        ) {
            return;
        }

        $choices[] = [
            'scope' => $scope,
            'id' => $id,
            'name' => $name !== ''
                ? $name
                : $id,
            'min' => (float)$min,
            'max' => (float)$max,
        ];
    };


foreach (
    (
        isset($regionHudGameConfig['traits']) &&
        is_array($regionHudGameConfig['traits'])
            ? $regionHudGameConfig['traits']
            : []
    )
    as $trait
) {
    if (is_array($trait)) {
        $appendHudTrait(
            $regionHudSources,
            'game',
            $trait
        );
    }
}


foreach (
    (
        isset($traits) &&
        is_array($traits)
            ? $traits
            : []
    )
    as $trait
) {
    if (is_array($trait)) {
        $appendHudTrait(
            $regionHudSources,
            'region',
            $trait
        );
    }
}


/*
 * Preserve a stored choice in the editor even if its Trait was later changed
 * so it is no longer a valid bounded numeric progress-bar source. Save-time
 * validation will require the author to repair it.
 */
$regionHudSourceKeys = [];

foreach ($regionHudSources as $source) {
    $regionHudSourceKeys[
        $source['scope'] .
        '|' .
        $source['id']
    ] = true;
}

foreach ($regionHudComponents as $component) {

    if (!is_array($component)) {
        continue;
    }

    $storedScope =
        (string)(
            $component['source_scope']
            ?? ''
        );

    $storedId =
        (string)(
            $component['source_id']
            ?? ''
        );

    $storedKey =
        $storedScope .
        '|' .
        $storedId;

    if (
        $storedScope !== '' &&
        $storedId !== '' &&
        empty(
            $regionHudSourceKeys[
                $storedKey
            ]
        )
    ) {
        $regionHudSources[] = [
            'scope' => $storedScope,
            'id' => $storedId,
            'name' =>
                '[Unavailable] ' .
                $storedId,
            'min' => 0,
            'max' => 1,
        ];

        $regionHudSourceKeys[
            $storedKey
        ] = true;
    }
}

?>
<section
    class="builder-region-hud"
    data-region-hud-editor
>
    <h3>Player HUD</h3>

    <p>
        Choose the persistent information shown at the bottom of the player
        screen while this Region is active. The same HUD remains visible in
        both Action and Travel modes; full-screen Location and Storylet
        presentations cover it.
    </p>

    <p>
        <label>
            <input
                type="checkbox"
                name="hud[enabled]"
                value="1"
                <?= $regionHudEnabled
                    ? 'checked'
                    : '' ?>
            >
            Show the HUD in this Region
        </label>
    </p>

    <div
        data-region-hud-components
        data-next-index="<?= count(
            $regionHudComponents
        ) ?>"
    >
        <?php foreach (
            $regionHudComponents
            as $hudIndex => $component
        ): ?>

            <?php
            $component =
                is_array($component)
                    ? $component
                    : [];

            $componentId =
                trim(
                    (string)(
                        $component['id']
                        ?? ''
                    )
                );

            $sourceScope =
                trim(
                    (string)(
                        $component['source_scope']
                        ?? ''
                    )
                );

            $sourceId =
                trim(
                    (string)(
                        $component['source_id']
                        ?? ''
                    )
                );

            $sourceValue =
                $sourceScope .
                '|' .
                $sourceId;

            $label =
                trim(
                    (string)(
                        $component['label']
                        ?? ''
                    )
                );

            $showValue =
                !empty(
                    $component['show_value']
                );
            ?>

            <fieldset
                class="builder-region-hud-component"
                data-region-hud-component
            >
                <legend>
                    Progress Bar
                </legend>

                <input
                    type="hidden"
                    name="hud[components][<?= (int)$hudIndex ?>][id]"
                    value="<?= builderEscape(
                        $componentId
                    ) ?>"
                >

                <input
                    type="hidden"
                    name="hud[components][<?= (int)$hudIndex ?>][type]"
                    value="progress_bar"
                >

                <p>
                    <label>
                        Source
                        <br>

                        <select
                            name="hud[components][<?= (int)$hudIndex ?>][source]"
                            required
                        >
                            <option value="">
                                Select a bounded numeric Trait
                            </option>

                            <?php foreach (
                                $regionHudSources
                                as $source
                            ): ?>

                                <?php
                                $optionValue =
                                    $source['scope'] .
                                    '|' .
                                    $source['id'];

                                $scopeLabel =
                                    $source['scope'] ===
                                    'game'
                                        ? 'Game'
                                        : 'Region';
                                ?>

                                <option
                                    value="<?= builderEscape(
                                        $optionValue
                                    ) ?>"
                                    <?= $sourceValue ===
                                        $optionValue
                                            ? 'selected'
                                            : '' ?>
                                >
                                    <?= builderEscape(
                                        $scopeLabel .
                                        ' — ' .
                                        $source['name'] .
                                        ' (' .
                                        $source['min'] .
                                        '–' .
                                        $source['max'] .
                                        ')'
                                    ) ?>
                                </option>

                            <?php endforeach; ?>
                        </select>
                    </label>
                </p>

                <p>
                    <label>
                        Player-facing label
                        <br>

                        <input
                            type="text"
                            name="hud[components][<?= (int)$hudIndex ?>][label]"
                            value="<?= builderEscape(
                                $label
                            ) ?>"
                            maxlength="120"
                            placeholder="Uses the Trait name if blank"
                        >
                    </label>
                </p>

                <p>
                    <label>
                        <input
                            type="checkbox"
                            name="hud[components][<?= (int)$hudIndex ?>][show_value]"
                            value="1"
                            <?= $showValue
                                ? 'checked'
                                : '' ?>
                        >
                        Show the numeric value beside the bar
                    </label>
                </p>

                <p>
                    <button
                        type="button"
                        data-region-hud-remove
                    >
                        Remove Progress Bar
                    </button>
                </p>
            </fieldset>

        <?php endforeach; ?>
    </div>

    <?php if (empty($regionHudSources)): ?>

        <p>
            <small>
                No bounded numeric Traits are currently available. A Progress
                Bar requires a Number Trait with both a Minimum and Maximum.
            </small>
        </p>

    <?php endif; ?>

    <p>
        <button
            type="button"
            data-region-hud-add
            <?= empty($regionHudSources)
                ? 'disabled'
                : '' ?>
        >
            Add Progress Bar
        </button>
    </p>

    <template data-region-hud-template>
        <fieldset
            class="builder-region-hud-component"
            data-region-hud-component
        >
            <legend>
                Progress Bar
            </legend>

            <input
                type="hidden"
                data-hud-name="id"
                value=""
            >

            <input
                type="hidden"
                data-hud-name="type"
                value="progress_bar"
            >

            <p>
                <label>
                    Source
                    <br>

                    <select
                        data-hud-name="source"
                        required
                    >
                        <option value="">
                            Select a bounded numeric Trait
                        </option>

                        <?php foreach (
                            $regionHudSources
                            as $source
                        ): ?>

                            <?php
                            $optionValue =
                                $source['scope'] .
                                '|' .
                                $source['id'];

                            $scopeLabel =
                                $source['scope'] ===
                                'game'
                                    ? 'Game'
                                    : 'Region';
                            ?>

                            <option
                                value="<?= builderEscape(
                                    $optionValue
                                ) ?>"
                            >
                                <?= builderEscape(
                                    $scopeLabel .
                                    ' — ' .
                                    $source['name'] .
                                    ' (' .
                                    $source['min'] .
                                    '–' .
                                    $source['max'] .
                                    ')'
                                ) ?>
                            </option>

                        <?php endforeach; ?>
                    </select>
                </label>
            </p>

            <p>
                <label>
                    Player-facing label
                    <br>

                    <input
                        type="text"
                        data-hud-name="label"
                        maxlength="120"
                        placeholder="Uses the Trait name if blank"
                    >
                </label>
            </p>

            <p>
                <label>
                    <input
                        type="checkbox"
                        data-hud-name="show_value"
                        value="1"
                    >
                    Show the numeric value beside the bar
                </label>
            </p>

            <p>
                <button
                    type="button"
                    data-region-hud-remove
                >
                    Remove Progress Bar
                </button>
            </p>
        </fieldset>
    </template>
</section>

<script>
(() => {
    'use strict';

    const editor =
        document.querySelector(
            '[data-region-hud-editor]'
        );

    if (!editor) {
        return;
    }

    const host =
        editor.querySelector(
            '[data-region-hud-components]'
        );

    const template =
        editor.querySelector(
            '[data-region-hud-template]'
        );

    const addButton =
        editor.querySelector(
            '[data-region-hud-add]'
        );

    if (
        !host ||
        !template ||
        !addButton
    ) {
        return;
    }

    function bindRemove(button) {
        button.addEventListener(
            'click',
            function () {
                const component =
                    button.closest(
                        '[data-region-hud-component]'
                    );

                if (component) {
                    component.remove();
                }
            }
        );
    }

    editor
        .querySelectorAll(
            '[data-region-hud-remove]'
        )
        .forEach(
            bindRemove
        );

    addButton.addEventListener(
        'click',
        function () {

            const index =
                Number(
                    host.dataset.nextIndex ||
                    0
                );

            host.dataset.nextIndex =
                String(
                    index + 1
                );

            const fragment =
                template.content.cloneNode(
                    true
                );

            fragment
                .querySelectorAll(
                    '[data-hud-name]'
                )
                .forEach(
                    function (field) {

                        const fieldName =
                            field.dataset
                                .hudName;

                        field.name =
                            'hud[components][' +
                            index +
                            '][' +
                            fieldName +
                            ']';

                        field.removeAttribute(
                            'data-hud-name'
                        );
                    }
                );

            const removeButton =
                fragment.querySelector(
                    '[data-region-hud-remove]'
                );

            if (removeButton) {
                bindRemove(
                    removeButton
                );
            }

            host.appendChild(
                fragment
            );
        }
    );
})();
</script>


==============================================================================
FILE: includes/builder/region-travel.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Linear Region Travel Editor
 * WAYFARER_LINEAR_TRAVEL_EDITOR_V72
 * --------------------------------------------------------------------------
 *
 * Dedicated travel is opt-in so existing Regions keep their authored Position
 * Tick Effect behavior until the author deliberately migrates them.
 */

$regionTravelStoredConfig = [];

if (!empty($record['config'])) {
    $decodedRegionTravelConfig =
        json_decode(
            (string)$record['config'],
            true
        );

    if (
        is_array($decodedRegionTravelConfig) &&
        isset($decodedRegionTravelConfig['travel']) &&
        is_array($decodedRegionTravelConfig['travel'])
    ) {
        $regionTravelStoredConfig =
            $decodedRegionTravelConfig['travel'];
    }
}

$regionTravelPosted =
    ($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST' &&
    isset($_POST['travel']) &&
    is_array($_POST['travel']);

$regionTravelFormConfig =
    $regionTravelPosted
        ? $_POST['travel']
        : $regionTravelStoredConfig;

$regionTravelEnabled =
    !empty($regionTravelFormConfig['enabled']);

$regionTravelBaseDistance =
    $regionTravelFormConfig['base_distance']
    ?? 1;

$regionTravelAllowTurnaround =
    $regionTravelPosted
        ? !empty(
            $regionTravelFormConfig[
                'allow_turnaround'
            ]
        )
        : (
            array_key_exists(
                'allow_turnaround',
                $regionTravelFormConfig
            )
                ? !empty(
                    $regionTravelFormConfig[
                        'allow_turnaround'
                    ]
                )
                : true
        );

$regionTravelIsLinear =
    strtolower(
        trim(
            (string)(
                $record['navigation_type']
                ?? ''
            )
        )
    ) === 'linear';

?>
<section
    class="builder-region-travel"
    data-builder-travel-panel
    data-region-travel-editor
>
    <h3>Linear Travel</h3>

    <p>
        Configure the Region's normal movement rate independently from the
        player's current direction. Direction is runtime journey state; this
        section defines how far one normal tick moves along the line.
    </p>

    <p data-region-travel-nonlinear <?= $regionTravelIsLinear ? 'hidden' : '' ?>>
        <small>
            Save this Region with Navigation Type set to Linear before enabling
            dedicated travel.
        </small>
    </p>

    <fieldset
        data-region-travel-fields
        <?= $regionTravelIsLinear ? '' : 'disabled' ?>
    >
        <legend>Movement</legend>

        <p>
            <label>
                <input
                    type="checkbox"
                    name="travel[enabled]"
                    value="1"
                    <?= $regionTravelEnabled ? 'checked' : '' ?>
                    data-region-travel-enabled
                >
                Use dedicated Linear Travel for this Region
            </label>
        </p>

        <p>
            <label>
                Base Distance Per Tick
                <br>
                <input
                    type="number"
                    name="travel[base_distance]"
                    value="<?= builderEscape($regionTravelBaseDistance) ?>"
                    min="0.000001"
                    step="any"
                    data-region-travel-base-distance
                >
            </label>
            <br>
            <small>
                The normal distance moved each tick before future conditional
                travel modifiers are applied. The player's current direction
                determines whether this distance increases or decreases Position.
            </small>
        </p>

        <p>
            <label>
                <input
                    type="checkbox"
                    name="travel[allow_turnaround]"
                    value="1"
                    <?= $regionTravelAllowTurnaround ? 'checked' : '' ?>
                >
                Player may turn around freely in this Region
            </label>
            <br>
            <small>
                When enabled, Action Mode offers Turn Around. Turning around does
                not consume a separate tick; the next travel tick moves in the
                opposite direction.
            </small>
        </p>

        <p>
            <small>
                Compatibility: until dedicated Linear Travel is enabled, this
                Region continues using its existing Navigation Position Tick
                Effect. Once enabled, Region Tick Effects that directly target
                Navigation Position are ignored so movement is not applied twice.
                All other Region Tick Effects continue normally.
            </small>
        </p>
    </fieldset>
</section>

<script>
(() => {
    'use strict';

    const editor =
        document.querySelector(
            '[data-region-travel-editor]'
        );

    if (!editor) {
        return;
    }

    const form =
        editor.closest('form');

    if (!form) {
        return;
    }

    const navigationType =
        form.querySelector(
            '[name="navigation_type"]'
        );

    const fieldset =
        editor.querySelector(
            '[data-region-travel-fields]'
        );

    const nonLinearMessage =
        editor.querySelector(
            '[data-region-travel-nonlinear]'
        );

    if (!navigationType || !fieldset) {
        return;
    }

    function updateAvailability() {
        const isLinear =
            String(
                navigationType.value || ''
            ).toLowerCase() === 'linear';

        fieldset.disabled =
            !isLinear;

        if (nonLinearMessage) {
            nonLinearMessage.hidden =
                isLinear;
        }
    }

    navigationType.addEventListener(
        'change',
        updateAvailability
    );

    updateAvailability();
})();
</script>


==============================================================================
FILE: includes/builder/relationship-field.php
==============================================================================

<?php
/**
 * Expected variables:
 * $fieldName, $relationship, $relationshipOptions, $record
 */
?>
<p>
    <label>
        <?= builderEscape($relationship['label']) ?>
        <?php if (!empty($relationship['required'])): ?>*<?php endif; ?>
        <br>

        <select
            name="<?= builderEscape($fieldName) ?>"
            data-relationship="<?= builderEscape($fieldName) ?>"
        >
            <option value="">
                -- Select <?= builderEscape($relationship['label']) ?> --
            </option>

            <?php foreach ($relationshipOptions[$fieldName] as $option): ?>
                <?php if (
                    !empty($relationship['exclude_current']) &&
                    !empty($record['id']) &&
                    (int)$option['option_value'] === (int)$record['id']
                ): ?>
                    <?php continue; ?>
                <?php endif; ?>

                <option
                    value="<?= (int)$option['option_value'] ?>"
                    <?= ($record[$fieldName] ?? '') == $option['option_value']
                        ? 'selected'
                        : '' ?>
                >
                    <?= builderEscape($option['option_label']) ?>
                </option>
            <?php endforeach; ?>
        </select>

        <?php if (!empty($relationship['help'])): ?>
            <br>
            <small><?= builderEscape($relationship['help']) ?></small>
        <?php endif; ?>
    </label>
</p>



==============================================================================
FILE: includes/builder/save-record.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| REGION TICK EFFECTS v18
|--------------------------------------------------------------------------
*/

/* WAYFARER_GAMEPLAY_MODULAR_V25 */
require_once __DIR__ . '/../gameplay/functions.php';
require_once __DIR__ . '/../gameplay/storylet-bindings.php'; /* WAYFARER_STORYLET_BINDINGS_V79 */
require_once __DIR__ . '/../gameplay/status-lifecycle.php'; /* WAYFARER_STATUS_LIFECYCLE_AUTHORING_V88 */

/*
 * Compatibility wrapper for the current Region save path.
 * Game-level Gameplay will call the shared functions directly when added.
 */
function buildRegionTickEffectsFromPost(
    PDO $pdo,
    int $gameId,
    array $record,
    array $regionTraits,
    array $postedEffects
): array {

    $gameStmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_games
            WHERE id = ?
            LIMIT 1
            "
        );

    $gameStmt->execute([
        $gameId
    ]);

    $gameConfigRaw =
        $gameStmt->fetchColumn();

    $gameConfig = [];

    if (
        $gameConfigRaw !== false &&
        $gameConfigRaw !== null &&
        $gameConfigRaw !== ''
    ) {

        $decodedGameConfig =
            json_decode(
                (string)$gameConfigRaw,
                true
            );

        if (is_array($decodedGameConfig)) {
            $gameConfig =
                $decodedGameConfig;
        }
    }

    /* WAYFARER_CANONICAL_REGION_TARGET_SAVE_V68 */
    $currentRegionId =
        (int)(
            $record['id']
            ?? 0
        );

    if ($currentRegionId > 0) {
        $postedEffects =
            gameplayCanonicalizeLegacyCurrentRegionTickEffects(
                $postedEffects,
                $currentRegionId
            );
    }

    $allowedTargets =
        gameplayRuntimeStateTargets(
            $pdo,
            $gameId
        );

    $allowedConditionTargets =
        $allowedTargets;
    /* WAYFARER_BUILDER_UNIVERSAL_TARGETS_V56 */

    return
        gameplayBuildTickEffectsFromPost(
            $allowedTargets,
            $postedEffects,
            $allowedConditionTargets
        );
}

/*
|--------------------------------------------------------------------------
| Location Conditions
|--------------------------------------------------------------------------
| WAYFARER_LOCATION_CONDITIONS_SAVE_V45
*/

function buildLocationConditionsFromPost(
    PDO $pdo,
    int $gameId,
    array $record,
    $postedConditions
): array {

    $gameConfig = [];

    $gameStmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_games
            WHERE id = ?
            LIMIT 1
            "
        );

    $gameStmt->execute([
        $gameId
    ]);

    $rawGameConfig =
        $gameStmt->fetchColumn();

    if (
        $rawGameConfig !== false &&
        $rawGameConfig !== null &&
        $rawGameConfig !== ''
    ) {

        $decoded =
            json_decode(
                (string)$rawGameConfig,
                true
            );

        if (is_array($decoded)) {
            $gameConfig =
                $decoded;
        }
    }


    $regionId =
        (int)(
            $record['region_id']
            ?? 0
        );

    if ($regionId <= 0) {

        return [
            'conditions' => null,
            'error' =>
                'A Location must belong to a Region before Conditions can be saved.',
        ];
    }


    $regionStmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_regions
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

    $regionStmt->execute([
        $regionId,
        $gameId,
    ]);

    $rawRegionConfig =
        $regionStmt->fetchColumn();

    if ($rawRegionConfig === false) {

        return [
            'conditions' => null,
            'error' =>
                'The Location parent Region could not be loaded for Conditions.',
        ];
    }


    $regionConfig =
        [];

    if (
        $rawRegionConfig !== null &&
        $rawRegionConfig !== ''
    ) {

        $decoded =
            json_decode(
                (string)$rawRegionConfig,
                true
            );

        if (is_array($decoded)) {
            $regionConfig =
                $decoded;
        }
    }


    $conditionResult =
        gameplayBuildConditionNodeFromPost(
            $postedConditions,
            gameplayRuntimeStateTargets(
                $pdo,
                $gameId
            )
        );


    return [
        'conditions' =>
            $conditionResult['node'],

        'error' =>
            $conditionResult['error'],
    ];
}


/*
|--------------------------------------------------------------------------
| Location Effects
|--------------------------------------------------------------------------
|
| WAYFARER_LOCATION_ONE_TIME_EFFECTS_SAVE_V42
|
| One-time Location Effects currently target numeric Game Traits and the
| parent Region's numeric Traits. Navigation is intentionally excluded here
| so an arrival Effect cannot move the player away from the Location that
| just triggered its Presentation Mode.
|
*/

function buildLocationEffectsFromPost(
    PDO $pdo,
    int $gameId,
    array $record,
    array $postedEffects
): array {

    $gameConfig = [];

    $gameStmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_games
            WHERE id = ?
            LIMIT 1
            "
        );

    $gameStmt->execute([
        $gameId
    ]);

    $gameConfigRaw =
        $gameStmt->fetchColumn();

    if (
        $gameConfigRaw !== false &&
        $gameConfigRaw !== null &&
        $gameConfigRaw !== ''
    ) {

        $decoded =
            json_decode(
                (string)$gameConfigRaw,
                true
            );

        if (is_array($decoded)) {
            $gameConfig =
                $decoded;
        }
    }


    $regionId =
        (int)(
            $record['region_id']
            ?? 0
        );

    if ($regionId <= 0) {

        return [
            'effects' => [],
            'error' =>
                'A Location must belong to a Region before Effects can be saved.',
        ];
    }


    $regionStmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_regions
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

    $regionStmt->execute([
        $regionId,
        $gameId,
    ]);

    $regionRaw =
        $regionStmt->fetchColumn();

    if ($regionRaw === false) {

        return [
            'effects' => [],
            'error' =>
                'The Location parent Region could not be loaded for Effects.',
        ];
    }


    $regionConfig = [];

    if (
        $regionRaw !== null &&
        $regionRaw !== ''
    ) {

        $decoded =
            json_decode(
                (string)$regionRaw,
                true
            );

        if (is_array($decoded)) {
            $regionConfig =
                $decoded;
        }
    }


    $regionTraits =
        isset(
            $regionConfig['traits']
        ) &&
        is_array(
            $regionConfig['traits']
        )
            ? $regionConfig['traits']
            : [];


    /*
     * WAYFARER_GENERALIZED_LOCATION_EFFECT_SAVE_V43
     *
     * Result conditions may inspect active Game/Region Traits, while the
     * Effect target itself remains restricted to numeric state.
     */
    return
        gameplayBuildEffectsFromPost(
            gameplayRuntimeStateTargets(
                $pdo,
                $gameId
            ),
            $postedEffects,
            gameplayRuntimeStateTargets(
                $pdo,
                $gameId
            )
        );
}


/*
|--------------------------------------------------------------------------
| Location Tick Effects
|--------------------------------------------------------------------------
|
| WAYFARER_LOCATION_TICK_EFFECTS_SAVE_V35
|
| A Location effect may mutate Game Traits, the active Region's Traits, or
| Navigation Position when that Location belongs to a linear Region.
| Per-Location mutable Trait state does not exist yet, so Location Traits are
| deliberately not exposed as effect targets.
|
*/
function buildLocationTickEffectsFromPost(
    PDO $pdo,
    int $gameId,
    array $record,
    array $postedEffects
): array {

    $gameConfig = [];

    $gameStmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_games
            WHERE id = ?
            LIMIT 1
            "
        );

    $gameStmt->execute([
        $gameId
    ]);

    $gameConfigRaw =
        $gameStmt->fetchColumn();

    if (
        $gameConfigRaw !== false &&
        $gameConfigRaw !== null &&
        $gameConfigRaw !== ''
    ) {

        $decoded =
            json_decode(
                (string)$gameConfigRaw,
                true
            );

        if (is_array($decoded)) {
            $gameConfig =
                $decoded;
        }
    }


    $regionId =
        (int)(
            $record['region_id']
            ?? 0
        );

    if ($regionId <= 0) {
        return [
            'effects' => [],
            'error' =>
                'A Location must belong to a Region before Tick Effects can be saved.',
        ];
    }


    $regionStmt =
        $pdo->prepare(
            "
            SELECT
                navigation_type,
                config
            FROM wf_regions
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

    $regionStmt->execute([
        $regionId,
        $gameId,
    ]);

    $region =
        $regionStmt->fetch(
            PDO::FETCH_ASSOC
        );

    if (!$region) {
        return [
            'effects' => [],
            'error' =>
                'The Location parent Region could not be loaded for Tick Effects.',
        ];
    }


    $regionConfig = [];

    if (
        !empty(
            $region['config']
        )
    ) {

        $decoded =
            json_decode(
                (string)$region['config'],
                true
            );

        if (is_array($decoded)) {
            $regionConfig =
                $decoded;
        }
    }


    $regionTraits =
        isset(
            $regionConfig['traits']
        ) &&
        is_array(
            $regionConfig['traits']
        )
            ? $regionConfig['traits']
            : [];


    $allowLinearNavigation =
        strtolower(
            trim(
                (string)(
                    $region['navigation_type']
                    ?? ''
                )
            )
        ) ===
        'linear';


    $allowedTargets =
        gameplayRuntimeStateTargets(
            $pdo,
            $gameId
        );

    $allowedConditionTargets =
        $allowedTargets;

    /* WAYFARER_BUILDER_UNIVERSAL_TARGETS_V56 */


    return
        gameplayBuildTickEffectsFromPost(
            $allowedTargets,
            $postedEffects,
            $allowedConditionTargets
        );
}

/*
|--------------------------------------------------------------------------
| Storylet Conditions + Effects
| WAYFARER_STORYLET_BUILDER_V56
|--------------------------------------------------------------------------
*/

function buildStoryletGameConfig(
    PDO $pdo,
    int $gameId
): array {

    $stmt = $pdo->prepare(
        "
        SELECT config
        FROM wf_games
        WHERE id = ?
        LIMIT 1
        "
    );

    $stmt->execute([
        $gameId
    ]);

    $raw = $stmt->fetchColumn();

    if (
        $raw === false ||
        $raw === null ||
        $raw === ''
    ) {
        return [];
    }

    $decoded = json_decode(
        (string)$raw,
        true
    );

    return is_array($decoded)
        ? $decoded
        : [];
}


function buildStoryletConditionsFromPost(
    PDO $pdo,
    int $gameId,
    $postedConditions
): array {

    $gameConfig =
        buildStoryletGameConfig(
            $pdo,
            $gameId
        );

    $result =
        gameplayBuildConditionNodeFromPost(
            $postedConditions,
            gameplayRuntimeStateTargets(
                $pdo,
                $gameId
            )
        );

    return [
        'conditions' => $result['node'],
        'error'      => $result['error'],
    ];
}


function buildStoryletEffectsFromPost(
    PDO $pdo,
    int $gameId,
    array $postedEffects,
    array $storyletBindings = [],
    int $currentStoryletId = 0
): array {

    $gameConfig =
        buildStoryletGameConfig(
            $pdo,
            $gameId
        );

    $allowedTargets =
        array_replace(
            gameplayRuntimeStateTargets(
                $pdo,
                $gameId
            ),
            gameplayStoryletBindingEffectTargets(
                $pdo,
                $gameId,
                $storyletBindings
            ),
            gameplayStoryletNavigationEffectTargets(
                $pdo,
                $gameId,
                $currentStoryletId
            )
        );

    $result =
        gameplayBuildEffectsFromPost(
            $allowedTargets,
            $postedEffects,
            gameplayConditionGameWideTargets(
                $pdo,
                $gameId,
                $gameConfig['traits']
                    ?? []
            )
        );

    if (($result['error'] ?? '') !== '') {
        return $result;
    }

    $transitionCount = 0;

    foreach (
        $result['effects']
            ?? []
        as $effect
    ) {
        if (
            is_array($effect) &&
            (string)(
                $effect['target_scope']
                ?? ''
            ) === 'storylet' &&
            (string)(
                $effect['target_type']
                ?? ''
            ) === 'transition'
        ) {
            $transitionCount++;
        }
    }

    if ($transitionCount > 1) {
        return [
            'effects' => [],
            'error' =>
                'A Storylet may have only one Storylet → Continue To Effect.',
        ];
    }

    return $result;
}


function validateStoryletParentChain(
    PDO $pdo,
    int $gameId,
    int $storyletId,
    int $parentStoryletId
): string {

    if ($parentStoryletId <= 0) {
        return '';
    }

    if (
        $storyletId > 0 &&
        $parentStoryletId === $storyletId
    ) {
        return 'A Storylet cannot be its own Parent Storylet.';
    }

    $seen = [];
    $currentId = $parentStoryletId;

    while ($currentId > 0) {

        if (
            $storyletId > 0 &&
            $currentId === $storyletId
        ) {
            return 'Parent Storylet would create a circular Choice chain.';
        }

        if (isset($seen[$currentId])) {
            return 'The selected Parent Storylet is already part of a circular Choice chain.';
        }

        $seen[$currentId] = true;

        $stmt = $pdo->prepare(
            "
            SELECT parent_storylet_id
            FROM wf_storylets
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

        $stmt->execute([
            $currentId,
            $gameId,
        ]);

        $parent = $stmt->fetchColumn();

        if ($parent === false) {
            return 'Invalid Parent Storylet.';
        }

        $currentId =
            $parent === null || $parent === ''
                ? 0
                : (int)$parent;
    }

    return '';
}

function buildSystemTraitForStorage(
    string $groupName,
    string $traitName,
    array $traitDefinition,
    $value,
    $authorMax = null
): array {
    $traitType = $traitDefinition['type'] ?? 'text';

    if ($traitType === 'number') {
        if (filter_var($value, FILTER_VALIDATE_INT) !== false) {
            $value = (int)$value;
        } else {
            $value = (float)$value;
        }
    } elseif ($traitType === 'binary') {
        $value = (int)$value;
    } elseif ($traitType === 'boolean') {
        $value = in_array(
            (string)$value,
            ['1', 'true', 'yes', 'on'],
            true
        );
    }

    return [
        'id'           => 'sys_' . $groupName . '_' . $traitName,
        'name'         => $traitName,
        'type'         => $traitType,
        'min'          => $traitDefinition['min'] ?? null,
        'max'          => $authorMax !== null
            ? $authorMax
            : ($traitDefinition['max'] ?? null),
        'initial'      => $value,
        'active'       => true,
        'notes'        => $traitDefinition['help'] ?? '',
        'system'       => true,
        'system_group' => $groupName,
        'system_key'   => $traitName,
    ];
}


/*
|--------------------------------------------------------------------------
| Region Player HUD
| WAYFARER_REGION_HUD_SAVE_V64
|--------------------------------------------------------------------------
*/
function buildRegionHudFromPost(
    PDO $pdo,
    int $gameId,
    array $regionTraits,
    array $postedHud
): array {

    $enabled =
        !empty(
            $postedHud['enabled']
        );

    $postedComponents =
        isset($postedHud['components']) &&
        is_array($postedHud['components'])
            ? array_values(
                $postedHud['components']
            )
            : [];


    $gameStmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_games
            WHERE id = ?
            LIMIT 1
            "
        );

    $gameStmt->execute([
        $gameId,
    ]);

    $gameRaw =
        $gameStmt->fetchColumn();

    $gameConfig =
        $gameRaw
            ? json_decode(
                (string)$gameRaw,
                true
            )
            : [];

    if (!is_array($gameConfig)) {
        $gameConfig = [];
    }


    $catalog = [
        'game' => [],
        'region' => [],
    ];

    $indexTrait =
        static function (
            array &$bucket,
            array $trait
        ): void {

            $id =
                trim(
                    (string)(
                        $trait['id']
                        ?? ''
                    )
                );

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

            $bucket[$id] =
                $trait;
        };


    foreach (
        (
            isset($gameConfig['traits']) &&
            is_array($gameConfig['traits'])
                ? $gameConfig['traits']
                : []
        )
        as $trait
    ) {
        if (is_array($trait)) {
            $indexTrait(
                $catalog['game'],
                $trait
            );
        }
    }


    foreach ($regionTraits as $trait) {
        if (is_array($trait)) {
            $indexTrait(
                $catalog['region'],
                $trait
            );
        }
    }


    $components = [];

    foreach (
        $postedComponents
        as $rowIndex => $postedComponent
    ) {

        if (!is_array($postedComponent)) {
            continue;
        }

        $type =
            strtolower(
                trim(
                    (string)(
                        $postedComponent['type']
                        ?? 'progress_bar'
                    )
                )
            );

        if ($type !== 'progress_bar') {
            return [
                'hud' => [],
                'error' =>
                    'HUD component ' .
                    ($rowIndex + 1) .
                    ' has an unsupported component type.',
            ];
        }


        $source =
            trim(
                (string)(
                    $postedComponent['source']
                    ?? ''
                )
            );

        $parts =
            explode(
                '|',
                $source,
                2
            );

        $scope =
            strtolower(
                trim(
                    (string)(
                        $parts[0]
                        ?? ''
                    )
                )
            );

        $sourceId =
            trim(
                (string)(
                    $parts[1]
                    ?? ''
                )
            );

        if (
            !in_array(
                $scope,
                ['game', 'region'],
                true
            ) ||
            $sourceId === ''
        ) {
            return [
                'hud' => [],
                'error' =>
                    'HUD component ' .
                    ($rowIndex + 1) .
                    ' must select a Trait source.',
            ];
        }


        $definition =
            $catalog[$scope][
                $sourceId
            ]
            ?? null;

        if (
            !is_array($definition) ||
            strtolower(
                trim(
                    (string)(
                        $definition['type']
                        ?? ''
                    )
                )
            ) !== 'number' ||
            !is_numeric(
                $definition['min']
                ?? null
            ) ||
            !is_numeric(
                $definition['max']
                ?? null
            ) ||
            (float)$definition['max'] <=
                (float)$definition['min']
        ) {
            return [
                'hud' => [],
                'error' =>
                    'HUD component ' .
                    ($rowIndex + 1) .
                    ' must use a bounded Number Trait with both Minimum and Maximum values.',
            ];
        }


        $label =
            trim(
                (string)(
                    $postedComponent['label']
                    ?? ''
                )
            );

        if (
            function_exists(
                'mb_strlen'
            )
                ? mb_strlen(
                    $label
                ) > 120
                : strlen(
                    $label
                ) > 120
        ) {
            return [
                'hud' => [],
                'error' =>
                    'HUD component ' .
                    ($rowIndex + 1) .
                    ' label must be 120 characters or fewer.',
            ];
        }


        $componentId =
            trim(
                (string)(
                    $postedComponent['id']
                    ?? ''
                )
            );

        if ($componentId === '') {
            $componentId =
                'hud_' .
                bin2hex(
                    random_bytes(6)
                );
        }


        $components[] = [
            'id' =>
                $componentId,

            'type' =>
                'progress_bar',

            'source_scope' =>
                $scope,

            'source_id' =>
                $sourceId,

            'label' =>
                $label,

            'show_value' =>
                !empty(
                    $postedComponent[
                        'show_value'
                    ]
                ),
        ];
    }


    return [
        'hud' => [
            'enabled' =>
                $enabled,

            'components' =>
                $components,
        ],

        'error' => '',
    ];
}


/*
 * WAYFARER_LINEAR_TRAVEL_SAVE_V72
 *
 * Dedicated Linear Travel is deliberately opt-in. A null travel result means
 * the Region should continue using the legacy Position Tick Effect path.
 */
function buildRegionTravelFromPost(
    array $record,
    array $postedTravel
): array {
    $navigationType =
        strtolower(
            trim(
                (string)(
                    $record['navigation_type']
                    ?? ''
                )
            )
        );

    if ($navigationType !== 'linear') {
        return [
            'travel' => null,
            'error' => '',
        ];
    }

    if (empty($postedTravel['enabled'])) {
        return [
            'travel' => null,
            'error' => '',
        ];
    }

    $baseDistance =
        $postedTravel['base_distance']
        ?? '';

    if (
        !is_numeric($baseDistance) ||
        (float)$baseDistance <= 0
    ) {
        return [
            'travel' => null,
            'error' =>
                'Base Distance Per Tick must be greater than zero.',
        ];
    }

    $baseDistance =
        (float)$baseDistance;

    if (floor($baseDistance) === $baseDistance) {
        $baseDistance =
            (int)$baseDistance;
    }

    return [
        'travel' => [
            'enabled' => true,
            'base_distance' =>
                $baseDistance,
            'allow_turnaround' =>
                !empty(
                    $postedTravel[
                        'allow_turnaround'
                    ]
                ),
        ],
        'error' => '',
    ];
}


/*
|--------------------------------------------------------------------------
| Storylet duplication
| WAYFARER_STORYLET_DUPLICATE_V83
|--------------------------------------------------------------------------
|
| Duplicate the currently saved Storylet as a Draft. The duplicate copies
| the selected Storylet record and its media links, but intentionally does
| not recursively copy child Branch Storylets.
|
*/
function duplicateStoryletRecord(
    PDO $pdo,
    int $gameId,
    int $storyletId
): array {

    if ($gameId <= 0 || $storyletId <= 0) {
        return [
            'duplicated' => false,
            'id' => 0,
            'error' => 'A valid Storylet is required to duplicate.',
        ];
    }

    try {
        $pdo->beginTransaction();

        $stmt = $pdo->prepare(
            "
            SELECT
                id,
                uuid,
                game_id,
                name,
                storylet_key,
                description,
                conditions,
                effects,
                max_occurrences,
                trigger_type,
                status,
                config,
                parent_storylet_id,
                choice_label,
                choice_sort_order,
                branch_label,
                branch_sort_order
            FROM wf_storylets
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            FOR UPDATE
            "
        );

        $stmt->execute([
            $storyletId,
            $gameId,
        ]);

        $source = $stmt->fetch(PDO::FETCH_ASSOC);

        if (!$source) {
            throw new RuntimeException(
                'The Storylet to duplicate could not be found.'
            );
        }

        $sourceName =
            trim(
                (string)(
                    $source['name']
                    ?? 'Storylet'
                )
            );

        if ($sourceName === '') {
            $sourceName = 'Storylet';
        }

        $baseName =
            preg_replace(
                '/\s+-\s+COPY(?:\s+\d+)?$/i',
                '',
                $sourceName
            );

        if (!is_string($baseName) || trim($baseName) === '') {
            $baseName = $sourceName;
        }

        $baseName = trim($baseName);

        /* Leave room for " - COPY 9999" within the 200-character Name. */
        $baseName =
            function_exists('mb_substr')
                ? mb_substr($baseName, 0, 185, 'UTF-8')
                : substr($baseName, 0, 185);

        $copyName = $baseName . ' - COPY';
        $copyNumber = 2;

        $nameCheck = $pdo->prepare(
            "
            SELECT 1
            FROM wf_storylets
            WHERE game_id = ?
              AND name = ?
            LIMIT 1
            "
        );

        while (true) {
            $nameCheck->execute([
                $gameId,
                $copyName,
            ]);

            if (!$nameCheck->fetchColumn()) {
                break;
            }

            $copyName =
                $baseName .
                ' - COPY ' .
                $copyNumber;

            $copyNumber++;

            if ($copyNumber > 9999) {
                throw new RuntimeException(
                    'Could not generate a unique Storylet copy name.'
                );
            }
        }

        $sourceKey =
            trim(
                (string)(
                    $source['storylet_key']
                    ?? ''
                )
            );

        if ($sourceKey === '') {
            $sourceKey =
                'storylet-' .
                $storyletId;
        }

        $copyKey =
            substr(
                $sourceKey,
                0,
                80
            ) .
            '-copy-' .
            bin2hex(
                random_bytes(6)
            );

        $copyUuid =
            bin2hex(
                random_bytes(16)
            );

        $parentId =
            (int)(
                $source['parent_storylet_id']
                ?? 0
            );

        $branchSortOrder =
            (int)(
                $source['branch_sort_order']
                ?? 0
            );

        $choiceSortOrder =
            (int)(
                $source['choice_sort_order']
                ?? 0
            );

        $branchLabel =
            (string)(
                $source['branch_label']
                ?? ''
            );

        $choiceLabel =
            (string)(
                $source['choice_label']
                ?? ''
            );

        if ($parentId > 0) {
            $orderStmt = $pdo->prepare(
                "
                SELECT COALESCE(MAX(branch_sort_order), 0)
                FROM wf_storylets
                WHERE game_id = ?
                  AND parent_storylet_id = ?
                "
            );

            $orderStmt->execute([
                $gameId,
                $parentId,
            ]);

            $branchSortOrder =
                (int)$orderStmt->fetchColumn() + 10;

            $choiceSortOrder =
                $branchSortOrder;

            if (trim($branchLabel) !== '') {
                $branchLabel =
                    rtrim($branchLabel) .
                    ' - COPY';
            }

            if (trim($choiceLabel) !== '') {
                $choiceLabel =
                    rtrim($choiceLabel) .
                    ' - COPY';
            }
        }

        $insert = $pdo->prepare(
            "
            INSERT INTO wf_storylets
                (
                    uuid,
                    game_id,
                    name,
                    storylet_key,
                    description,
                    conditions,
                    effects,
                    max_occurrences,
                    trigger_type,
                    status,
                    config,
                    parent_storylet_id,
                    choice_label,
                    choice_sort_order,
                    branch_label,
                    branch_sort_order
                )
            VALUES
                (?, ?, ?, ?, ?, ?, ?, ?, ?, 'draft', ?, ?, ?, ?, ?, ?)
            "
        );

        $insert->execute([
            $copyUuid,
            $gameId,
            $copyName,
            $copyKey,
            $source['description'] ?? null,
            $source['conditions'] ?? null,
            $source['effects'] ?? null,
            $source['max_occurrences'] ?? null,
            $source['trigger_type'] ?? 'manual',
            $source['config'] ?? null,
            $parentId > 0 ? $parentId : null,
            $choiceLabel !== '' ? $choiceLabel : null,
            $choiceSortOrder,
            $branchLabel,
            $branchSortOrder,
        ]);

        $copyId =
            (int)$pdo->lastInsertId();

        if ($copyId <= 0) {
            throw new RuntimeException(
                'The Storylet copy could not be created.'
            );
        }

        /* Reuse the same game-level media assets; do not duplicate files. */
        $media = $pdo->prepare(
            "
            INSERT INTO wf_media_links
                (
                    media_id,
                    object_type,
                    object_id,
                    slot
                )
            SELECT
                media_id,
                object_type,
                ?,
                slot
            FROM wf_media_links
            WHERE object_type = 'wf_storylets'
              AND object_id = ?
            "
        );

        $media->execute([
            $copyId,
            $storyletId,
        ]);

        $pdo->commit();

        return [
            'duplicated' => true,
            'id' => $copyId,
            'error' => '',
        ];

    } catch (Throwable $exception) {
        if ($pdo->inTransaction()) {
            $pdo->rollBack();
        }

        return [
            'duplicated' => false,
            'id' => 0,
            'error' => $exception->getMessage(),
        ];
    }
}


/**
 * Validates and writes a builder record.
 */
function saveBuilderRecord(
    PDO $pdo,
    array $definition,
    int $gameId,
    array $post,
    array $record,
    array $configValues,
    array $traits
): array {
    $table         = $definition['table'];
    $relationships = $definition['relationships'] ?? [];
    $fields        = $definition['fields'] ?? [];
    $configFields  = $definition['config_fields'] ?? [];
    $scope         = $definition['scope'];


    $systemTraitsDefinition =
        $definition['system_traits'] ?? [];

    $systemSelectorField =
        $systemTraitsDefinition['selector_field'] ?? null;

    $systemGroups =
        $systemTraitsDefinition['groups'] ?? [];

    $error = '';

    $postedId = !empty($post['id'])
        ? (int)$post['id']
        : 0;

    foreach ($relationships as $fieldName => $relationship) {
        $value = $post[$fieldName] ?? '';
        $record[$fieldName] = $value === '' ? '' : (int)$value;
    }

    foreach ($fields as $fieldName => $field) {
        $value = $post[$fieldName] ?? '';

        if (is_string($value)) {
            $value = trim($value);
        }

        $record[$fieldName] = $value;
    }

    foreach ($configFields as $fieldName => $field) {
        $value = $post['config'][$fieldName] ?? '';

        if (is_string($value)) {
            $value = trim($value);
        }

        $configValues[$fieldName] = $value;
    }

    foreach ($relationships as $fieldName => $relationship) {
        if (
            !empty($relationship['required']) &&
            empty($record[$fieldName])
        ) {
            $error = $relationship['label'] . ' is required.';
            break;
        }
    }

    $customTraits = [];

    if (!empty($definition['traits'])) {
        $traitResult = buildTraitsFromPost($post['traits'] ?? []);
        $customTraits = $traitResult['traits'];

        if ($traitResult['error'] !== '') {
            $error = $traitResult['error'];
        }
    }

    $systemTraits = [];

    if (
        $error === '' &&
        $systemSelectorField &&
        !empty($systemGroups)
    ) {
        $activeSystemGroup =
            (string)($record[$systemSelectorField] ?? '');

        $activeGroupDefinition =
            $systemGroups[$activeSystemGroup] ?? null;

        if ($activeGroupDefinition) {
            foreach (
                ($activeGroupDefinition['traits'] ?? [])
                as $traitName => $traitDefinition
            ) {
                $value =
                    $post['system_traits'][$activeSystemGroup][$traitName]
                    ?? ($traitDefinition['default'] ?? '');

                if (is_string($value)) {
                    $value = trim($value);
                }

                if (
                    !empty($traitDefinition['required']) &&
                    $value === ''
                ) {
                    $error =
                        ($traitDefinition['label'] ?? $traitName) .
                        ' is required.';
                    break;
                }

                $traitType = $traitDefinition['type'] ?? 'text';

                if (
                    $traitType === 'number' &&
                    $value !== '' &&
                    !is_numeric($value)
                ) {
                    $error =
                        ($traitDefinition['label'] ?? $traitName) .
                        ' must be a number.';
                    break;
                }

                if (
                    $traitType === 'number' &&
                    $value !== '' &&
                    isset($traitDefinition['min']) &&
                    (float)$value < (float)$traitDefinition['min']
                ) {
                    $error =
                        ($traitDefinition['label'] ?? $traitName) .
                        ' must be at least ' .
                        $traitDefinition['min'] .
                        '.';
                    break;
                }

                if (
                    $traitType === 'binary' &&
                    !in_array(
                        (string)$value,
                        ['0', '1'],
                        true
                    )
                ) {
                    $error =
                        ($traitDefinition['label'] ?? $traitName) .
                        ' must be No or Yes.';
                    break;
                }

                if ($traitType === 'select') {
                    $options = $traitDefinition['options'] ?? [];

                    if (!array_key_exists((string)$value, $options)) {
                        $error =
                            'Invalid ' .
                            ($traitDefinition['label'] ?? $traitName) .
                            '.';
                        break;
                    }
                }

                $authorMax = null;

                if (
                    $traitType === 'number' &&
                    !empty($traitDefinition['allow_author_max'])
                ) {
                    $postedMax =
                        $post['system_trait_meta']
                            [$activeSystemGroup]
                            [$traitName]
                            ['max']
                        ?? '';

                    if (is_string($postedMax)) {
                        $postedMax = trim($postedMax);
                    }

                    if ($postedMax !== '') {

                        if (!is_numeric($postedMax)) {
                            $error =
                                ($traitDefinition['max_label'] ?? 'Maximum') .
                                ' must be a number.';
                            break;
                        }

                        if (
                            isset($traitDefinition['min']) &&
                            (float)$postedMax < (float)$traitDefinition['min']
                        ) {
                            $error =
                                ($traitDefinition['max_label'] ?? 'Maximum') .
                                ' must be at least ' .
                                $traitDefinition['min'] .
                                '.';
                            break;
                        }

                        if ((float)$value > (float)$postedMax) {
                            $error =
                                'Starting Quantity cannot be greater than ' .
                                'Maximum Quantity.';
                            break;
                        }

                        if (
                            filter_var(
                                $postedMax,
                                FILTER_VALIDATE_INT
                            ) !== false
                        ) {
                            $authorMax = (int)$postedMax;
                        } else {
                            $authorMax = (float)$postedMax;
                        }
                    }
                }

                $systemTraits[] =
                    buildSystemTraitForStorage(
                        $activeSystemGroup,
                        $traitName,
                        $traitDefinition,
                        $value,
                        $authorMax
                    );
            }
        }
    }

    if ($error === '' && !empty($systemTraits)) {
        $reservedNames = [];

        foreach ($systemTraits as $systemTrait) {
            $reservedNames[] =
                strtolower((string)$systemTrait['name']);
        }

        foreach ($customTraits as $customTrait) {
            $customName =
                strtolower(trim((string)($customTrait['name'] ?? '')));

            if (
                $customName !== '' &&
                in_array($customName, $reservedNames, true)
            ) {
                $error =
                    '"' .
                    ($customTrait['name'] ?? '') .
                    '" is a Wayfarer system trait for this entity type. ' .
                    'Choose a different custom trait name.';
                break;
            }
        }
    }

    $traits = array_merge($systemTraits, $customTraits);

    /* WAYFARER_LINEAR_TRAVEL_SAVE_V72 */
    $regionTravel =
        null;

    if (
        $error === '' &&
        ($definition['table'] ?? '') ===
            'wf_regions'
    ) {
        $regionTravelResult =
            buildRegionTravelFromPost(
                $record,
                isset($post['travel']) &&
                is_array($post['travel'])
                    ? $post['travel']
                    : []
            );

        $regionTravel =
            $regionTravelResult['travel']
            ?? null;

        if (
            ($regionTravelResult['error'] ?? '') !==
            ''
        ) {
            $error =
                (string)$regionTravelResult['error'];
        }
    }

    /* WAYFARER_REGION_HUD_SAVE_V64 */
    $regionHud = [
        'enabled' => false,
        'components' => [],
    ];

    if (
        $error === '' &&
        ($definition['table'] ?? '') ===
            'wf_regions'
    ) {

        $regionHudResult =
            buildRegionHudFromPost(
                $pdo,
                $gameId,
                $traits,
                isset($post['hud']) &&
                is_array($post['hud'])
                    ? $post['hud']
                    : []
            );

        $regionHud =
            $regionHudResult['hud']
            ?? $regionHud;

        if (
            ($regionHudResult['error'] ?? '') !==
            ''
        ) {
            $error =
                (string)$regionHudResult['error'];
        }
    }

    /* WAYFARER_REGION_TICK_EFFECTS_PARSE_V18 */
    $regionTickEffects = [];

    if (
        $error === '' &&
        ($definition['table'] ?? '') ===
            'wf_regions'
    ) {

        $tickEffectResult =
            buildRegionTickEffectsFromPost(
                $pdo,
                $gameId,
                $record,
                $traits,
                $post['tick_effects']
                ?? []
            );

        $regionTickEffects =
            $tickEffectResult[
                'effects'
            ];

        if (
            $tickEffectResult['error'] !==
            ''
        ) {

            $error =
                $tickEffectResult[
                    'error'
                ];
        }
    }


    /*
     * WAYFARER_LOCATION_CONDITIONS_PARSE_V45
     */
    $locationConditions =
        null;

    if (
        $error === '' &&
        ($definition['table'] ?? '') ===
            'wf_locations'
    ) {

        $conditionResult =
            buildLocationConditionsFromPost(
                $pdo,
                $gameId,
                $record,
                $post['conditions']
                    ?? null
            );

        $locationConditions =
            $conditionResult[
                'conditions'
            ];

        if (
            $conditionResult['error'] !==
            ''
        ) {
            $error =
                $conditionResult[
                    'error'
                ];
        }
    }


    /*
     * WAYFARER_LOCATION_ONE_TIME_EFFECTS_PARSE_V42
     */
    $locationEffects = [];

    if (
        $error === '' &&
        ($definition['table'] ?? '') ===
            'wf_locations'
    ) {

        $effectResult =
            buildLocationEffectsFromPost(
                $pdo,
                $gameId,
                $record,
                $post['effects']
                ?? []
            );

        $locationEffects =
            $effectResult[
                'effects'
            ];

        if (
            $effectResult['error'] !==
            ''
        ) {

            $error =
                $effectResult[
                    'error'
                ];
        }
    }


    /* WAYFARER_LOCATION_TICK_EFFECTS_PARSE_V35 */
    $locationTickEffects = [];

    if (
        $error === '' &&
        ($definition['table'] ?? '') ===
            'wf_locations'
    ) {

        $tickEffectResult =
            buildLocationTickEffectsFromPost(
                $pdo,
                $gameId,
                $record,
                $post['tick_effects']
                ?? []
            );

        $locationTickEffects =
            $tickEffectResult[
                'effects'
            ];

        if (
            $tickEffectResult['error'] !==
            ''
        ) {

            $error =
                $tickEffectResult[
                    'error'
                ];
        }
    }

    /* WAYFARER_STATUS_LIFECYCLE_SAVE_V88 */
    $statusLifecycle = null;

    if (
        $error === '' &&
        ($definition['table'] ?? '') === 'wf_statuses'
    ) {
        $statusLifecycleResult =
            gameplayBuildStatusLifecycleFromPost(
                $pdo,
                $gameId,
                $post['status_lifecycle']
                    ?? []
            );

        $statusLifecycle =
            $statusLifecycleResult['lifecycle']
            ?? null;

        $record['_status_lifecycle_editor'] =
            is_array(
                $statusLifecycleResult['editor']
                ?? null
            )
                ? $statusLifecycleResult['editor']
                : [];

        if (
            ($statusLifecycleResult['error'] ?? '') !== ''
        ) {
            $error =
                (string)$statusLifecycleResult['error'];
        }
    }

    /* WAYFARER_STORYLET_PARSE_V56 */
    /* WAYFARER_STORYLET_BINDINGS_V79 */
    $storyletBindings = [];
    $storyletConditions = null;
    $storyletEffects = [];

    if (
        $error === '' &&
        ($definition['table'] ?? '') === 'wf_storylets'
    ) {
        $bindingResult =
            gameplayBuildStoryletBindingsFromPost(
                isset($post['bindings']) &&
                is_array($post['bindings'])
                    ? array_values($post['bindings'])
                    : []
            );

        $storyletBindings =
            $bindingResult['bindings'];

        if ($bindingResult['error'] !== '') {
            $error =
                $bindingResult['error'];
        }
    }

    if (
        $error === '' &&
        ($definition['table'] ?? '') === 'wf_storylets'
    ) {
        $conditionResult =
            buildStoryletConditionsFromPost(
                $pdo,
                $gameId,
                $post['conditions']
                    ?? null
            );

        $storyletConditions =
            $conditionResult['conditions'];

        if ($conditionResult['error'] !== '') {
            $error = $conditionResult['error'];
        }
    }

    if (
        $error === '' &&
        ($definition['table'] ?? '') === 'wf_storylets'
    ) {
        $effectResult =
            buildStoryletEffectsFromPost(
                $pdo,
                $gameId,
                isset($post['effects']) &&
                is_array($post['effects'])
                    ? array_values($post['effects'])
                    : [],
                $storyletBindings,
                $postedId
            );

        $storyletEffects =
            $effectResult['effects'];

        if ($effectResult['error'] !== '') {
            $error = $effectResult['error'];
        }
    }

    if ($error === '') {
        foreach ($fields as $fieldName => $field) {
            if (
                !empty($field['required']) &&
                $record[$fieldName] === ''
            ) {
                $error = $field['label'] . ' is required.';
                break;
            }
        }
    }

    if ($error === '') {
        foreach ($relationships as $fieldName => $relationship) {
            if (empty($record[$fieldName])) {
                continue;
            }

            $relationshipTable = $relationship['table'];
            $valueField        = $relationship['value_field'];
            $gameField         = $relationship['game_field'];

            $sql = "
                SELECT COUNT(*)
                FROM `$relationshipTable`
                WHERE `$valueField` = ?
                  AND `$gameField` = ?
            ";

            $stmt = $pdo->prepare($sql);
            $stmt->execute([
                $record[$fieldName],
                $gameId,
            ]);

            if (!$stmt->fetchColumn()) {
                $error = 'Invalid ' . $relationship['label'] . '.';
                break;
            }
        }
    }
    /* WAYFARER_STORYLET_PARENT_VALIDATION_V56 */
if (
        $error === '' &&
        ($definition['table'] ?? '') === 'wf_storylets'
    ) {
        $error = validateStoryletParentChain(
            $pdo,
            $gameId,
            $postedId,
            (int)($record['parent_storylet_id'] ?? 0)
        );
    }


    if ($error === '') {
        foreach ($configFields as $fieldName => $field) {
            $applies = configFieldApplies($pdo, $field, $record);

            if (!$applies) {
                continue;
            }

            $value = $configValues[$fieldName] ?? '';

            if (
                !empty($field['required']) &&
                $value === ''
            ) {
                $error = $field['label'] . ' is required.';
                break;
            }

            if (
                $value !== '' &&
                ($field['type'] ?? '') === 'number' &&
                !is_numeric($value)
            ) {
                $error = $field['label'] . ' must be a number.';
                break;
            }

            if (
                $value !== '' &&
                isset($field['min']) &&
                (float)$value < (float)$field['min']
            ) {
                $error = $field['label'] .
                    ' must be at least ' .
                    $field['min'] .
                    '.';
                break;
            }
        }
    }

    /* WAYFARER_CONFIG_MAX_VALIDATION_V56 */
    if ($error === '') {
        foreach ($configFields as $fieldName => $field) {
            if (!configFieldApplies($pdo, $field, $record)) {
                continue;
            }

            $value = $configValues[$fieldName] ?? '';

            if (
                $value !== '' &&
                ($field['type'] ?? '') === 'number' &&
                is_numeric($value) &&
                isset($field['max']) &&
                (float)$value > (float)$field['max']
            ) {
                $error = $field['label'] .
                    ' must be no more than ' .
                    $field['max'] .
                    '.';
                break;
            }
        }
    }
    if ($error !== '') {
        return [
            'saved'        => false,
            'id'           => $postedId,
            'record'       => $record,
            'configValues' => $configValues,
            'traits'       => $traits,
            'error'        => $error,
        ];
    }

    $writeFields = [];

    foreach ($relationships as $fieldName => $relationship) {
        $writeFields[] = $fieldName;
    }

    foreach ($fields as $fieldName => $field) {
        $writeFields[] = $fieldName;
    }

    $configToSave = [];

    if (!empty($record['config'])) {
        $existingConfig = json_decode($record['config'], true);

        if (is_array($existingConfig)) {
            $configToSave = $existingConfig;
        }
    }

    unset($configToSave['system_traits']);

    foreach ($configFields as $fieldName => $field) {
        if (!configFieldApplies($pdo, $field, $record)) {
            continue;
        }

        $value = $configValues[$fieldName] ?? '';

        if ($value === '') {
            unset($configToSave[$fieldName]);
            continue;
        }

        if (($field['type'] ?? '') === 'number') {
            if (
                filter_var(
                    $value,
                    FILTER_VALIDATE_INT
                ) !== false
            ) {
                $value = (int)$value;
            } else {
                $value = (float)$value;
            }
        }

        $configToSave[$fieldName] = $value;
    }

    if (
        !empty($definition['traits']) ||
        !empty($definition['system_traits'])
    ) {
        /*
         * WAYFARER_ENTITY_SYSTEM_CONFIG_V55
         *
         * Entity system schema/help text is universal Wayfarer code and must
         * not be duplicated into every wf_entities.config JSON document.
         */
        if (
            ($definition['table'] ?? '') === 'wf_entities' &&
            !empty($definition['system_traits'])
        ) {
            $compactSystem = [];

            foreach ($systemTraits as $systemTrait) {
                if (!is_array($systemTrait)) {
                    continue;
                }

                $systemKey =
                    (string)($systemTrait['system_key'] ?? '');

                if ($systemKey === 'quantity') {
                    $compactSystem['quantity'] = [
                        'initial' => $systemTrait['initial'] ?? 0,
                        'max' => $systemTrait['max'] ?? null,
                    ];
                } elseif ($systemKey === 'inventory_visibility') {
                    $compactSystem['inventory_visibility'] =
                        (string)(
                            $systemTrait['initial']
                            ?? 'while_possessed'
                        );
                } elseif ($systemKey === 'party_member') {
                    $compactSystem['party_member'] =
                        (int)($systemTrait['initial'] ?? 0);
                }
            }

            $configToSave['traits'] =
                array_values($customTraits);

            if ($compactSystem) {
                $configToSave['system'] =
                    $compactSystem;
            } else {
                unset($configToSave['system']);
            }

            unset($configToSave['system_traits']);

        } else {
            $configToSave['traits'] = $traits;
        }

        /* WAYFARER_LINEAR_TRAVEL_SAVE_V72 */
        if (
            ($definition['table'] ?? '') ===
                'wf_regions'
        ) {
            if ($regionTravel !== null) {
                $configToSave['travel'] =
                    $regionTravel;
            } else {
                unset(
                    $configToSave['travel']
                );
            }
        }

        /* WAYFARER_REGION_HUD_SAVE_V64 */
        if (
            ($definition['table'] ?? '') ===
                'wf_regions'
        ) {

            if (
                !empty($regionHud['enabled']) ||
                !empty($regionHud['components'])
            ) {
                $configToSave['hud'] =
                    $regionHud;
            } else {
                unset(
                    $configToSave['hud']
                );
            }
        }

        /* WAYFARER_REGION_TICK_EFFECTS_CONFIG_V18 */
        if (
            ($definition['table'] ?? '') ===
                'wf_regions'
        ) {

            if ($regionTickEffects) {

                $configToSave[
                    'tick_effects'
                ] =
                    $regionTickEffects;

            } else {

                unset(
                    $configToSave[
                        'tick_effects'
                    ]
                );
            }
        }


        /*
         * WAYFARER_LOCATION_CONDITIONS_CONFIG_V45
         */
        if (
            ($definition['table'] ?? '') ===
                'wf_locations'
        ) {

            if ($locationConditions !== null) {

                $configToSave[
                    'conditions'
                ] =
                    $locationConditions;

            } else {

                unset(
                    $configToSave[
                        'conditions'
                    ]
                );
            }
        }


        /*
         * WAYFARER_LOCATION_ONE_TIME_EFFECTS_CONFIG_V42
         */
        if (
            ($definition['table'] ?? '') ===
                'wf_locations'
        ) {

            if ($locationEffects) {

                $configToSave[
                    'effects'
                ] =
                    array_values(
                        $locationEffects
                    );

            } else {

                unset(
                    $configToSave[
                        'effects'
                    ]
                );
            }
        }


        /* WAYFARER_LOCATION_TICK_EFFECTS_CONFIG_V35 */
        if (
            ($definition['table'] ?? '') ===
                'wf_locations'
        ) {

            if ($locationTickEffects) {

                $configToSave[
                    'tick_effects'
                ] =
                    $locationTickEffects;

            } else {

                unset(
                    $configToSave[
                        'tick_effects'
                    ]
                );
            }
        }
    }
    /* WAYFARER_STATUS_LIFECYCLE_CONFIG_V88 */
    if (
        ($definition['table'] ?? '') === 'wf_statuses'
    ) {
        if (is_array($statusLifecycle)) {
            $configToSave['lifecycle'] =
                $statusLifecycle;
        } else {
            unset($configToSave['lifecycle']);
        }
    }

    /* WAYFARER_STORYLET_CONFIG_SAVE_V56 */
    if (
        ($definition['table'] ?? '') === 'wf_storylets'
    ) {
        /* WAYFARER_STORYLET_BINDINGS_V79 */
        if ($storyletBindings) {
            $configToSave['bindings'] =
                array_values($storyletBindings);
        } else {
            unset($configToSave['bindings']);
        }

        if ($storyletConditions !== null) {
            $configToSave['conditions'] =
                $storyletConditions;
        } else {
            unset($configToSave['conditions']);
        }

        if ($storyletEffects) {
            $configToSave['effects'] =
                array_values($storyletEffects);
        } else {
            unset($configToSave['effects']);
        }
    }


    if (
        !empty($configFields) ||
        !empty($definition['traits']) ||
        !empty($definition['system_traits'])
    ) {
        $record['config'] = empty($configToSave)
            ? null
            : json_encode(
                $configToSave,
                JSON_UNESCAPED_SLASHES |
                JSON_UNESCAPED_UNICODE
            );

        $writeFields[] = 'config';
    }

    if ($postedId) {
        $scopeQuery = buildScopeQuery($definition);

        $checkSql = "
            SELECT `$table`.`id`
            FROM {$scopeQuery['from']}
            WHERE `$table`.`id` = ?
              AND {$scopeQuery['where']}
            LIMIT 1
        ";

        $stmt = $pdo->prepare($checkSql);
        $stmt->execute([$postedId, $gameId]);

        if (!$stmt->fetch()) {
            die('Record not found.');
        }

        $assignments = [];
        $values = [];

        foreach ($writeFields as $fieldName) {
            $assignments[] = "`$fieldName` = ?";
            $value = $record[$fieldName] ?? null;

            /* WAYFARER_OPTIONAL_RELATIONSHIP_NULL_V56 */
            if (
                isset($relationships[$fieldName]) &&
                $value === ''
            ) {
                $value = null;
            }

            if (
                isset($fields[$fieldName]) &&
                ($fields[$fieldName]['type'] ?? '') === 'number' &&
                $value === ''
            ) {
                $value = null;
            }

            $values[] = $value;
        }

        $values[] = $postedId;

        $sql = "
            UPDATE `$table`
            SET " . implode(', ', $assignments) . "
            WHERE id = ?
        ";

        $stmt = $pdo->prepare($sql);
        $stmt->execute($values);
    } else {
        $columns = [];
        $placeholders = [];
        $values = [];

        if ($scope['type'] === 'game') {
            $columns[] = "`{$scope['field']}`";
            $placeholders[] = '?';
            $values[] = $gameId;
        }

        foreach ($relationships as $fieldName => $relationship) {
            $columns[] = "`$fieldName`";
            $placeholders[] = '?';
            /* WAYFARER_OPTIONAL_RELATIONSHIP_INSERT_V56 */
            $relationshipValue =
                $record[$fieldName] === ''
                    ? null
                    : $record[$fieldName];

            $values[] = $relationshipValue;
        }

        foreach ($fields as $fieldName => $field) {
            $columns[] = "`$fieldName`";
            $placeholders[] = '?';

            $value = $record[$fieldName];

            if (
                ($field['type'] ?? '') === 'number' &&
                $value === ''
            ) {
                $value = null;
            }

            $values[] = $value;
        }

        if (
            !empty($configFields) ||
            !empty($definition['traits']) ||
            !empty($definition['system_traits'])
        ) {
            $columns[] = '`config`';
            $placeholders[] = '?';
            $values[] = $record['config'];
        }

        $sql = "
            INSERT INTO `$table`
            (" . implode(', ', $columns) . ")
            VALUES
            (" . implode(', ', $placeholders) . ")
        ";

        $stmt = $pdo->prepare($sql);
        $stmt->execute($values);

        $postedId = (int)$pdo->lastInsertId();
    }

    return [
        'saved'        => true,
        'id'           => $postedId,
        'record'       => $record,
        'configValues' => $configValues,
        'traits'       => $traits,
        'error'        => '',
    ];
}



==============================================================================
FILE: includes/builder/status-lifecycle.php
==============================================================================

<?php

/*
 * Status lifecycle editor
 * WAYFARER_STATUS_LIFECYCLE_EDITOR_V88
 * WAYFARER_STATUS_SUBJECT_EFFECTS_EDITOR_V89
 *
 * Expected variables: $pdo, $gameId, $record
 */

require_once __DIR__ . '/../gameplay/status-lifecycle.php';

$statusLifecycleConfig = [];

if (
    isset($record['_status_lifecycle_editor']) &&
    is_array($record['_status_lifecycle_editor'])
) {
    $statusLifecycleConfig = $record['_status_lifecycle_editor'];
} elseif (!empty($record['config'])) {
    $decodedStatusConfig = json_decode((string)$record['config'], true);
    if (
        is_array($decodedStatusConfig) &&
        isset($decodedStatusConfig['lifecycle']) &&
        is_array($decodedStatusConfig['lifecycle'])
    ) {
        $statusLifecycleConfig = $decodedStatusConfig['lifecycle'];
    }
}

$statusLifecycleMode = strtolower(trim((string)($statusLifecycleConfig['mode'] ?? 'manual')));
if (!in_array($statusLifecycleMode, ['manual', 'progression'], true)) {
    $statusLifecycleMode = 'manual';
}

$statusLifecycleStages = isset($statusLifecycleConfig['stages']) &&
    is_array($statusLifecycleConfig['stages'])
        ? array_values($statusLifecycleConfig['stages'])
        : [];

$statusLifecycleStorylets = gameplayStatusLifecycleStorylets(
    $pdo,
    (int)$gameId
);

$statusLifecycleRenderStoryletOptions = static function (
    array $storylets,
    int $selectedId = 0
): void {
    echo '<option value="">Select root Storylet...</option>';

    foreach ($storylets as $storylet) {
        $id = (int)($storylet['id'] ?? 0);
        if ($id <= 0) {
            continue;
        }

        $name = trim((string)($storylet['name'] ?? ('Storylet ' . $id)));
        $status = strtolower(trim((string)($storylet['status'] ?? 'draft')));
        $trigger = strtolower(trim((string)($storylet['trigger_type'] ?? 'manual')));

        $suffix = [];
        if ($status !== 'active') {
            $suffix[] = ucfirst($status);
        }
        if ($trigger === 'event') {
            $suffix[] = 'Event';
        }

        $label = $name;
        if ($suffix) {
            $label .= ' [' . implode(', ', $suffix) . ']';
        }

        echo '<option value="' . builderEscape($id) . '"' .
            ($id === $selectedId ? ' selected' : '') . '>' .
            builderEscape($label) .
            '</option>';
    }
};

$statusLifecycleRenderResultOptions = static function (
    array $stages,
    string $selected
): void {
    echo '<option value="inactive"' .
        ($selected === 'inactive' ? ' selected' : '') .
        '>End Status (Inactive)</option>';

    echo '<option value="stay"' .
        ($selected === 'stay' ? ' selected' : '') .
        '>Stay in this Stage / Restart Timer</option>';

    foreach ($stages as $stage) {
        if (!is_array($stage)) {
            continue;
        }

        $key = trim((string)($stage['key'] ?? ''));
        $name = trim((string)($stage['name'] ?? $key));

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

        $value = 'stage:' . $key;
        echo '<option value="' . builderEscape($value) . '"' .
            ($selected === $value ? ' selected' : '') . '>' .
            'Go to Stage: ' . builderEscape($name) .
            '</option>';
    }
 };

/* WAYFARER_STATUS_SUBJECT_EFFECTS_EDITOR_V89 */
$statusLifecycleTraitCatalog = gameplayStatusLifecycleSubjectTraitCatalog(
    $pdo,
    (int)$gameId
);

$statusLifecycleRenderTraitOptions = static function (
    array $catalog,
    string $selected = ''
): void {
    echo '<option value="">Select Trait...</option>';

    foreach ($catalog as $targetId => $definition) {
        if (!is_array($definition)) {
            continue;
        }

        $name = trim((string)($definition['name'] ?? ''));
        $dataType = strtolower(trim((string)($definition['data_type'] ?? 'number')));
        if ($name === '') {
            continue;
        }

        echo '<option value="' . builderEscape((string)$targetId) . '"' .
            ' data-status-trait-type="' . builderEscape($dataType) . '"' .
            ((string)$targetId === $selected ? ' selected' : '') . '>' .
            builderEscape($name) .
            '</option>';
    }
};

$statusLifecycleRenderEffectRow = static function (
    array $effect,
    string $namePrefix,
    bool $recurring,
    array $traitCatalog,
    callable $renderTraitOptions
): void {
    $effectKey = trim((string)($effect['key'] ?? ''));
    $targetId = trim((string)($effect['target_id'] ?? ''));
    $operation = strtolower(trim((string)($effect['operation'] ?? 'set')));
    $valueMode = strtolower(trim((string)($effect['value_mode'] ?? 'fixed')));
    $value = $effect['value'] ?? 0;
    $valueMin = $effect['value_min'] ?? 0;
    $valueMax = $effect['value_max'] ?? 0;
    $interval = max(1, (int)($effect['interval_ticks'] ?? 1));
    $dataType = isset($traitCatalog[$targetId])
        ? (string)($traitCatalog[$targetId]['data_type'] ?? 'number')
        : strtolower(trim((string)($effect['data_type'] ?? 'number')));
    ?>
    <div
        class="wayfarer-status-effect"
        data-status-effect
        <?= $recurring ? 'data-status-effect-recurring="1"' : '' ?>
    >
        <input
            type="hidden"
            name="<?= builderEscape($namePrefix) ?>[key]"
            value="<?= builderEscape($effectKey) ?>"
            data-status-effect-key
            data-status-effect-field="key"
        >

        <label>
            Status Subject Trait
            <select
                name="<?= builderEscape($namePrefix) ?>[target_id]"
                data-status-effect-target
                data-status-effect-field="target_id"
            >
                <?php $renderTraitOptions($traitCatalog, $targetId); ?>
            </select>
        </label>

        <label>
            Operation
            <select
                name="<?= builderEscape($namePrefix) ?>[operation]"
                data-status-effect-operation
                data-status-effect-field="operation"
            >
                <option value="set" <?= $operation === 'set' ? 'selected' : '' ?>>Set</option>
                <option value="add" data-status-number-operation <?= $operation === 'add' ? 'selected' : '' ?>>Add</option>
                <option value="subtract" data-status-number-operation <?= $operation === 'subtract' ? 'selected' : '' ?>>Subtract</option>
                <option value="subtract_percent_current" data-status-number-operation <?= $operation === 'subtract_percent_current' ? 'selected' : '' ?>>Subtract % of Current</option>
                <option value="subtract_percent_max" data-status-number-operation <?= $operation === 'subtract_percent_max' ? 'selected' : '' ?>>Subtract % of Maximum</option>
                <option value="add_percent_max" data-status-number-operation <?= $operation === 'add_percent_max' ? 'selected' : '' ?>>Add % of Maximum</option>
            </select>
        </label>

        <?php if ($recurring): ?>
            <label>
                Every
                <span class="wayfarer-status-effect-inline-number">
                    <input
                        type="number"
                        min="1"
                        step="1"
                        name="<?= builderEscape($namePrefix) ?>[interval_ticks]"
                        value="<?= builderEscape($interval) ?>"
                        data-status-effect-field="interval_ticks"
                    >
                    <span>tick(s)</span>
                </span>
            </label>
        <?php endif; ?>

        <label data-status-effect-value-mode-wrap>
            Value Type
            <select
                name="<?= builderEscape($namePrefix) ?>[value_mode]"
                data-status-effect-value-mode
                data-status-effect-field="value_mode"
            >
                <option value="fixed" <?= $valueMode === 'fixed' ? 'selected' : '' ?>>Fixed</option>
                <option value="random" <?= $valueMode === 'random' ? 'selected' : '' ?>>Random Min–Max</option>
            </select>
        </label>

        <label data-status-effect-fixed-number>
            Value
            <input
                type="number"
                step="any"
                name="<?= builderEscape($namePrefix) ?>[value]"
                value="<?= builderEscape($dataType === 'boolean' ? 0 : $value) ?>"
                data-status-effect-value-number
                data-status-effect-field="value"
            >
        </label>

        <label data-status-effect-fixed-boolean>
            Value
            <select
                name="<?= builderEscape($namePrefix) ?>[value]"
                data-status-effect-value-boolean
                data-status-effect-field="value"
            >
                <option value="0" <?= !$value ? 'selected' : '' ?>>False</option>
                <option value="1" <?= $value ? 'selected' : '' ?>>True</option>
            </select>
        </label>

        <label data-status-effect-random-min>
            Minimum
            <input
                type="number"
                step="any"
                name="<?= builderEscape($namePrefix) ?>[value_min]"
                value="<?= builderEscape($valueMin) ?>"
                data-status-effect-field="value_min"
            >
        </label>

        <label data-status-effect-random-max>
            Maximum
            <input
                type="number"
                step="any"
                name="<?= builderEscape($namePrefix) ?>[value_max]"
                value="<?= builderEscape($valueMax) ?>"
                data-status-effect-field="value_max"
            >
        </label>

        <button type="button" data-remove-status-effect>Remove Effect</button>
    </div>
    <?php
};

?>

<div
    class="wayfarer-status-lifecycle"
    data-builder-status-lifecycle
>
    <h3>Status Progression</h3>

    <p>
        <small>
            Manual Statuses stay active until an Effect changes them. Timed Stages
            advance independently for every affected character. The first Stage is
            entered when the Status becomes active.
        </small>
    </p>

    <p>
        <label>
            Progression Mode<br>
            <select
                name="status_lifecycle[mode]"
                data-status-lifecycle-mode
            >
                <option value="manual" <?= $statusLifecycleMode === 'manual' ? 'selected' : '' ?>>
                    Manual
                </option>
                <option value="progression" <?= $statusLifecycleMode === 'progression' ? 'selected' : '' ?>>
                    Timed Stages
                </option>
            </select>
        </label>
    </p>

    <div
        data-status-lifecycle-stages-wrap
        <?= $statusLifecycleMode === 'progression' ? '' : 'hidden' ?>
    >
        <div class="wayfarer-status-lifecycle-heading">
            <div>
                <h4>Stages</h4>
                <small>
                    Each Stage rolls its duration once on entry. When its timer expires,
                    exactly one Outcome is chosen from the authored percentages.
                </small>
            </div>

            <button
                type="button"
                data-add-status-stage
            >
                + Add Stage
            </button>
        </div>

        <div data-status-stages-list>
            <?php foreach ($statusLifecycleStages as $stageIndex => $stage): ?>
                <?php
                if (!is_array($stage)) {
                    continue;
                }

                $stageKey = trim((string)($stage['key'] ?? ''));
                $stageName = trim((string)($stage['name'] ?? ''));
                $duration = isset($stage['duration']) && is_array($stage['duration'])
                    ? $stage['duration']
                    : [];
                $durationMode = strtolower(trim((string)($duration['mode'] ?? 'fixed')));
                $durationValue = (int)($duration['value'] ?? 1);
                $durationMin = (int)($duration['min'] ?? 1);
                $durationMax = (int)($duration['max'] ?? max(1, $durationMin));
                $entryEffects = isset($stage['entry_effects']) && is_array($stage['entry_effects'])
                    ? array_values($stage['entry_effects'])
                    : [];
                $tickEffects = isset($stage['tick_effects']) && is_array($stage['tick_effects'])
                    ? array_values($stage['tick_effects'])
                    : [];
                $outcomes = isset($stage['outcomes']) && is_array($stage['outcomes'])
                    ? array_values($stage['outcomes'])
                    : [];
                ?>

                <section
                    class="wayfarer-status-stage"
                    data-status-stage
                    data-stage-index="<?= (int)$stageIndex ?>"
                >
                    <input
                        type="hidden"
                        name="status_lifecycle[stages][<?= (int)$stageIndex ?>][key]"
                        value="<?= builderEscape($stageKey) ?>"
                        data-status-stage-key
                        data-status-field="key"
                    >

                    <div class="wayfarer-status-stage-heading">
                        <strong>
                            Stage <?= (int)$stageIndex + 1 ?><?= $stageIndex === 0 ? ' — Initial' : '' ?>
                        </strong>

                        <div class="wayfarer-status-stage-actions">
                            <button type="button" data-move-status-stage-up>Up</button>
                            <button type="button" data-move-status-stage-down>Down</button>
                            <button type="button" data-remove-status-stage>Remove Stage</button>
                        </div>
                    </div>

                    <div class="wayfarer-status-stage-fields">
                        <label>
                            Stage Name
                            <input
                                type="text"
                                name="status_lifecycle[stages][<?= (int)$stageIndex ?>][name]"
                                value="<?= builderEscape($stageName) ?>"
                                maxlength="80"
                                data-status-stage-name
                                data-status-field="name"
                            >
                        </label>

                        <label>
                            Duration Mode
                            <select
                                name="status_lifecycle[stages][<?= (int)$stageIndex ?>][duration_mode]"
                                data-status-duration-mode
                                data-status-field="duration_mode"
                            >
                                <option value="fixed" <?= $durationMode === 'fixed' ? 'selected' : '' ?>>Fixed</option>
                                <option value="random" <?= $durationMode === 'random' ? 'selected' : '' ?>>Random Min–Max</option>
                            </select>
                        </label>

                        <label data-status-duration-fixed>
                            Ticks
                            <input
                                type="number"
                                min="1"
                                step="1"
                                name="status_lifecycle[stages][<?= (int)$stageIndex ?>][duration_value]"
                                value="<?= builderEscape($durationValue) ?>"
                                data-status-field="duration_value"
                            >
                        </label>

                        <label data-status-duration-random>
                            Minimum Ticks
                            <input
                                type="number"
                                min="1"
                                step="1"
                                name="status_lifecycle[stages][<?= (int)$stageIndex ?>][duration_min]"
                                value="<?= builderEscape($durationMin) ?>"
                                data-status-field="duration_min"
                            >
                        </label>

                        <label data-status-duration-random>
                            Maximum Ticks
                            <input
                                type="number"
                                min="1"
                                step="1"
                                name="status_lifecycle[stages][<?= (int)$stageIndex ?>][duration_max]"
                                value="<?= builderEscape($durationMax) ?>"
                                data-status-field="duration_max"
                            >
                        </label>
                    </div>

                    <div class="wayfarer-status-stage-effects" data-status-stage-effects>
                        <div class="wayfarer-status-effects-heading">
                            <div>
                                <strong>On Enter Effects</strong>
                                <small>Applied once when this character enters the Stage.</small>
                            </div>
                            <button type="button" data-add-status-entry-effect>+ Add Effect</button>
                        </div>

                        <div data-status-entry-effects-list>
                            <?php foreach ($entryEffects as $effectIndex => $effect): ?>
                                <?php
                                if (!is_array($effect)) {
                                    continue;
                                }
                                $statusLifecycleRenderEffectRow(
                                    $effect,
                                    'status_lifecycle[stages][' . (int)$stageIndex . '][entry_effects][' . (int)$effectIndex . ']',
                                    false,
                                    $statusLifecycleTraitCatalog,
                                    $statusLifecycleRenderTraitOptions
                                );
                                ?>
                            <?php endforeach; ?>
                        </div>

                        <div class="wayfarer-status-effects-heading">
                            <div>
                                <strong>While in Stage Effects</strong>
                                <small>
                                    Applied to the Status Subject every authored number of gameplay ticks.
                                    The first interval starts when the Stage starts.
                                </small>
                            </div>
                            <button type="button" data-add-status-tick-effect>+ Add Effect</button>
                        </div>

                        <div data-status-tick-effects-list>
                            <?php foreach ($tickEffects as $effectIndex => $effect): ?>
                                <?php
                                if (!is_array($effect)) {
                                    continue;
                                }
                                $statusLifecycleRenderEffectRow(
                                    $effect,
                                    'status_lifecycle[stages][' . (int)$stageIndex . '][tick_effects][' . (int)$effectIndex . ']',
                                    true,
                                    $statusLifecycleTraitCatalog,
                                    $statusLifecycleRenderTraitOptions
                                );
                                ?>
                            <?php endforeach; ?>
                        </div>
                    </div>

                    <div class="wayfarer-status-outcomes-heading">
                        <div>
                            <strong>Outcomes</strong>
                            <small>Chances for this Stage must total exactly 100%.</small>
                        </div>
                        <button type="button" data-add-status-outcome>+ Add Outcome</button>
                    </div>

                    <div data-status-outcomes-list>
                        <?php foreach ($outcomes as $outcomeIndex => $outcome): ?>
                            <?php
                            if (!is_array($outcome)) {
                                continue;
                            }

                            $outcomeKey = trim((string)($outcome['key'] ?? ''));
                            $outcomeLabel = trim((string)($outcome['label'] ?? ''));
                            $outcomeChance = (int)($outcome['chance'] ?? 100);
                            $outcomeResult = strtolower(trim((string)($outcome['result'] ?? 'inactive')));
                            $outcomePresentation = strtolower(trim((string)($outcome['presentation'] ?? 'silent')));
                            $outcomeStoryletId = (int)($outcome['storylet_id'] ?? 0);
                            $outcomeEffects = isset($outcome['effects']) && is_array($outcome['effects'])
                                ? array_values($outcome['effects'])
                                : [];
                            ?>

                            <article
                                class="wayfarer-status-outcome"
                                data-status-outcome
                                data-outcome-index="<?= (int)$outcomeIndex ?>"
                            >
                                <input
                                    type="hidden"
                                    name="status_lifecycle[stages][<?= (int)$stageIndex ?>][outcomes][<?= (int)$outcomeIndex ?>][key]"
                                    value="<?= builderEscape($outcomeKey) ?>"
                                    data-status-outcome-key
                                    data-status-outcome-field="key"
                                >

                                <div class="wayfarer-status-outcome-fields">
                                    <label>
                                        Outcome Name
                                        <input
                                            type="text"
                                            name="status_lifecycle[stages][<?= (int)$stageIndex ?>][outcomes][<?= (int)$outcomeIndex ?>][label]"
                                            value="<?= builderEscape($outcomeLabel) ?>"
                                            data-status-outcome-field="label"
                                        >
                                    </label>

                                    <label>
                                        Chance %
                                        <input
                                            type="number"
                                            min="1"
                                            max="100"
                                            step="1"
                                            name="status_lifecycle[stages][<?= (int)$stageIndex ?>][outcomes][<?= (int)$outcomeIndex ?>][chance]"
                                            value="<?= builderEscape($outcomeChance) ?>"
                                            data-status-outcome-field="chance"
                                        >
                                    </label>

                                    <label>
                                        Result
                                        <select
                                            name="status_lifecycle[stages][<?= (int)$stageIndex ?>][outcomes][<?= (int)$outcomeIndex ?>][result]"
                                            data-status-outcome-result
                                            data-status-outcome-field="result"
                                        >
                                            <?php $statusLifecycleRenderResultOptions($statusLifecycleStages, $outcomeResult); ?>
                                        </select>
                                    </label>

                                    <label>
                                        Presentation
                                        <select
                                            name="status_lifecycle[stages][<?= (int)$stageIndex ?>][outcomes][<?= (int)$outcomeIndex ?>][presentation]"
                                            data-status-outcome-presentation
                                            data-status-outcome-field="presentation"
                                        >
                                            <option value="silent" <?= $outcomePresentation === 'silent' ? 'selected' : '' ?>>Silent</option>
                                            <option value="storylet" <?= $outcomePresentation === 'storylet' ? 'selected' : '' ?>>Open Storylet</option>
                                        </select>
                                    </label>

                                    <label data-status-outcome-storylet>
                                        Storylet
                                        <select
                                            name="status_lifecycle[stages][<?= (int)$stageIndex ?>][outcomes][<?= (int)$outcomeIndex ?>][storylet_id]"
                                            data-status-outcome-field="storylet_id"
                                        >
                                            <?php $statusLifecycleRenderStoryletOptions($statusLifecycleStorylets, $outcomeStoryletId); ?>
                                        </select>
                                    </label>
                                </div>

                                <div class="wayfarer-status-outcome-effects">
                                    <div class="wayfarer-status-effects-heading">
                                        <div>
                                            <strong>Outcome Effects</strong>
                                            <small>Applied to the Status Subject before the Result transition and Storylet presentation.</small>
                                        </div>
                                        <button type="button" data-add-status-outcome-effect>+ Add Effect</button>
                                    </div>

                                    <div data-status-outcome-effects-list>
                                        <?php foreach ($outcomeEffects as $effectIndex => $effect): ?>
                                            <?php
                                            if (!is_array($effect)) {
                                                continue;
                                            }
                                            $statusLifecycleRenderEffectRow(
                                                $effect,
                                                'status_lifecycle[stages][' . (int)$stageIndex . '][outcomes][' . (int)$outcomeIndex . '][effects][' . (int)$effectIndex . ']',
                                                false,
                                                $statusLifecycleTraitCatalog,
                                                $statusLifecycleRenderTraitOptions
                                            );
                                            ?>
                                        <?php endforeach; ?>
                                    </div>
                                </div>

                                <button
                                    type="button"
                                    data-remove-status-outcome
                                >
                                    Remove Outcome
                                </button>
                            </article>
                        <?php endforeach; ?>
                    </div>
                </section>
            <?php endforeach; ?>
        </div>
    </div>

    <p class="wayfarer-status-lifecycle-note">
        <small>
            When an Outcome opens a Storylet, Wayfarer supplies the affected character
            as the reserved <strong>subject</strong> binding. Use <code>{{subject}}</code>
            or <code>{{subject.name}}</code> in Storylet text. If the Storylet defines a
            normal Binding with Key <code>subject</code>, Status-triggered entry reuses the
            affected character instead of rolling a new one.
        </small>
    </p>

    <template data-status-stage-template>
        <section class="wayfarer-status-stage" data-status-stage>
            <input type="hidden" value="" data-status-stage-key data-status-field="key">

            <div class="wayfarer-status-stage-heading">
                <strong data-status-stage-heading>Stage</strong>
                <div class="wayfarer-status-stage-actions">
                    <button type="button" data-move-status-stage-up>Up</button>
                    <button type="button" data-move-status-stage-down>Down</button>
                    <button type="button" data-remove-status-stage>Remove Stage</button>
                </div>
            </div>

            <div class="wayfarer-status-stage-fields">
                <label>
                    Stage Name
                    <input type="text" maxlength="80" data-status-stage-name data-status-field="name">
                </label>
                <label>
                    Duration Mode
                    <select data-status-duration-mode data-status-field="duration_mode">
                        <option value="fixed">Fixed</option>
                        <option value="random">Random Min–Max</option>
                    </select>
                </label>
                <label data-status-duration-fixed>
                    Ticks
                    <input type="number" min="1" step="1" value="1" data-status-field="duration_value">
                </label>
                <label data-status-duration-random>
                    Minimum Ticks
                    <input type="number" min="1" step="1" value="1" data-status-field="duration_min">
                </label>
                <label data-status-duration-random>
                    Maximum Ticks
                    <input type="number" min="1" step="1" value="1" data-status-field="duration_max">
                </label>
            </div>

            <div class="wayfarer-status-stage-effects" data-status-stage-effects>
                <div class="wayfarer-status-effects-heading">
                    <div>
                        <strong>On Enter Effects</strong>
                        <small>Applied once when this character enters the Stage.</small>
                    </div>
                    <button type="button" data-add-status-entry-effect>+ Add Effect</button>
                </div>
                <div data-status-entry-effects-list></div>

                <div class="wayfarer-status-effects-heading">
                    <div>
                        <strong>While in Stage Effects</strong>
                        <small>Applied to the Status Subject every authored number of gameplay ticks.</small>
                    </div>
                    <button type="button" data-add-status-tick-effect>+ Add Effect</button>
                </div>
                <div data-status-tick-effects-list></div>
            </div>

            <div class="wayfarer-status-outcomes-heading">
                <div>
                    <strong>Outcomes</strong>
                    <small>Chances for this Stage must total exactly 100%.</small>
                </div>
                <button type="button" data-add-status-outcome>+ Add Outcome</button>
            </div>

            <div data-status-outcomes-list></div>
        </section>
    </template>

    <template data-status-outcome-template>
        <article class="wayfarer-status-outcome" data-status-outcome>
            <input type="hidden" value="" data-status-outcome-key data-status-outcome-field="key">

            <div class="wayfarer-status-outcome-fields">
                <label>
                    Outcome Name
                    <input type="text" value="Complete" data-status-outcome-field="label">
                </label>
                <label>
                    Chance %
                    <input type="number" min="1" max="100" step="1" value="100" data-status-outcome-field="chance">
                </label>
                <label>
                    Result
                    <select data-status-outcome-result data-status-outcome-field="result">
                        <option value="inactive">End Status (Inactive)</option>
                        <option value="stay">Stay in this Stage / Restart Timer</option>
                    </select>
                </label>
                <label>
                    Presentation
                    <select data-status-outcome-presentation data-status-outcome-field="presentation">
                        <option value="silent">Silent</option>
                        <option value="storylet">Open Storylet</option>
                    </select>
                </label>
                <label data-status-outcome-storylet>
                    Storylet
                    <select data-status-outcome-field="storylet_id">
                        <?php $statusLifecycleRenderStoryletOptions($statusLifecycleStorylets, 0); ?>
                    </select>
                </label>
            </div>

            <div class="wayfarer-status-outcome-effects">
                <div class="wayfarer-status-effects-heading">
                    <div>
                        <strong>Outcome Effects</strong>
                        <small>Applied before the Result transition and Storylet presentation.</small>
                    </div>
                    <button type="button" data-add-status-outcome-effect>+ Add Effect</button>
                </div>
                <div data-status-outcome-effects-list></div>
            </div>

            <button type="button" data-remove-status-outcome>Remove Outcome</button>
        </article>
    </template>

    <template data-status-effect-template>
        <?php
        $statusLifecycleRenderEffectRow(
            [],
            '',
            false,
            $statusLifecycleTraitCatalog,
            $statusLifecycleRenderTraitOptions
        );
        ?>
    </template>

    <template data-status-recurring-effect-template>
        <?php
        $statusLifecycleRenderEffectRow(
            ['interval_ticks' => 1],
            '',
            true,
            $statusLifecycleTraitCatalog,
            $statusLifecycleRenderTraitOptions
        );
        ?>
    </template>
</div>



==============================================================================
FILE: includes/builder/storylet-gameplay.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Storylet Gameplay Authoring
| WAYFARER_STORYLET_BUILDER_V56
|--------------------------------------------------------------------------
|
| Storylets reuse Wayfarer's shared recursive Conditions and generalized
| one-time Effects. Branches are structural: an immediate child Storylet is a
| player Branch, and that child owns its own Media, Conditions, Effects, and
| further Branches.
|
*/

require_once __DIR__ . '/../gameplay/functions.php';
require_once __DIR__ . '/../gameplay/storylet-bindings.php'; /* WAYFARER_STORYLET_BINDINGS_V79 */
/* WAYFARER_STORYLET_BINDING_UI_V83 */

$storyletConfig = [];

if (!empty($record['config'])) {
    $decoded = json_decode(
        (string)$record['config'],
        true
    );

    if (is_array($decoded)) {
        $storyletConfig = $decoded;
    }
}

/* WAYFARER_STORYLET_BINDINGS_V79 */
$storyletBindingRows =
    $_SERVER['REQUEST_METHOD'] === 'POST'
        ? (
            isset($_POST['bindings']) &&
            is_array($_POST['bindings'])
                ? array_values($_POST['bindings'])
                : []
        )
        : (
            isset($storyletConfig['bindings']) &&
            is_array($storyletConfig['bindings'])
                ? array_values($storyletConfig['bindings'])
                : []
        );

$storyletBindingBuild =
    gameplayBuildStoryletBindingsFromPost(
        $storyletBindingRows
    );

$storyletBindingDefinitions =
    $storyletBindingBuild['bindings']
    ?? [];

$storyletConditions =
    $_SERVER['REQUEST_METHOD'] === 'POST'
        ? ($_POST['conditions'] ?? null)
        : ($storyletConfig['conditions'] ?? null);

$storyletEffects =
    $_SERVER['REQUEST_METHOD'] === 'POST'
        ? (
            isset($_POST['effects']) &&
            is_array($_POST['effects'])
                ? array_values($_POST['effects'])
                : []
        )
        : (
            isset($storyletConfig['effects']) &&
            is_array($storyletConfig['effects'])
                ? array_values($storyletConfig['effects'])
                : []
        );

$storyletGameConfig = [];

if (!empty($game['config'])) {
    $decoded = json_decode(
        (string)$game['config'],
        true
    );

    if (is_array($decoded)) {
        $storyletGameConfig = $decoded;
    }
}

$storyletGameTraits =
    isset($storyletGameConfig['traits']) &&
    is_array($storyletGameConfig['traits'])
        ? $storyletGameConfig['traits']
        : [];

$storyletConditionTargets =
    gameplayRuntimeStateTargets(
        $pdo,
        $gameId
    );

$storyletEffectTargets =
    array_replace(
        $storyletConditionTargets,
        gameplayStoryletBindingEffectTargets(
            $pdo,
            $gameId,
            $storyletBindingDefinitions
        ),
        gameplayStoryletNavigationEffectTargets(
            $pdo,
            $gameId,
            (int)($id ?? 0)
        )
    );

$gameplayTargetCatalog =
    $storyletEffectTargets;

?>


<section
    data-storylet-bindings-editor
>
    <h3>Bindings</h3>

    <p>
        A Binding selects one runtime subject when this Storylet begins and keeps
        that same selection for the entire Storylet occurrence. Effects and
        narrative tokens can then refer to the selected subject consistently.
    </p>

    <p class="builder-field-help">
        <strong>Binding Name</strong> is the author-facing name shown elsewhere
        in the builder. <strong>Key</strong> is the internal identifier used by
        narrative tokens such as <code>{{victim.name}}</code>; Wayfarer
        normalizes it to lowercase letters, numbers, and underscores.
        <strong>Selection Rule</strong> decides what is selected.
        <strong>Random Party Member</strong> chooses from both named Player
        Characters and recruited Character Entities currently in the party; if
        an Effect uses a Trait such as Health, only party members that expose
        that Trait are eligible. <strong>Random Possessed Item</strong> chooses
        from Items whose current Quantity is greater than 0.
    </p>

    <div data-storylet-bindings-list>
        <?php foreach (
            $storyletBindingRows
            as $bindingIndex => $bindingRow
        ): ?>
            <?php
            $bindingRow =
                is_array($bindingRow)
                    ? $bindingRow
                    : [];

            $bindingKey =
                (string)(
                    $bindingRow['key']
                    ?? ''
                );

            $bindingLabel =
                (string)(
                    $bindingRow['label']
                    ?? ''
                );

            $bindingSelector =
                (string)(
                    $bindingRow['selector']
                    ?? ''
                );
            ?>

            <div
                class="builder-storylet-binding-row"
                data-storylet-binding-row
                style="margin:0 0 1em;padding:0.75em;border:1px solid #ddd;"
            >
                <label>
                    Binding Name
                    <input
                        type="text"
                        name="bindings[<?= (int)$bindingIndex ?>][label]"
                        value="<?= builderEscape($bindingLabel) ?>"
                        maxlength="80"
                        placeholder="Affected Character"
                        data-storylet-binding-label
                    >
                    <br>
                    <small>
                        Descriptive author-facing name used in the builder.
                    </small>
                </label>

                <label>
                    Key
                    <input
                        type="text"
                        name="bindings[<?= (int)$bindingIndex ?>][key]"
                        value="<?= builderEscape($bindingKey) ?>"
                        maxlength="32"
                        pattern="[a-z][a-z0-9_]{0,31}"
                        placeholder="affected_character"
                        autocomplete="off"
                        spellcheck="false"
                        data-storylet-binding-key
                    >
                    <br>
                    <small>
                        Internal identifier. Generated from Binding Name when blank;
                        lowercase letters, numbers, and underscores only.
                    </small>
                </label>

                <label>
                    Selection Rule
                    <select
                        name="bindings[<?= (int)$bindingIndex ?>][selector]"
                    >
                        <option value="">
                            Select...
                        </option>

                        <?php foreach (
                            gameplayStoryletBindingSelectorOptions()
                            as $selectorValue => $selectorLabel
                        ): ?>
                            <option
                                value="<?= builderEscape($selectorValue) ?>"
                                <?= $bindingSelector === $selectorValue
                                    ? 'selected'
                                    : '' ?>
                            >
                                <?= builderEscape($selectorLabel) ?>
                            </option>
                        <?php endforeach; ?>
                    </select>
                    <br>
                    <small>
                        Determines which runtime Entity this Binding selects.
                    </small>
                </label>

                <span style="margin-left:0.5em;">
                    Narrative Token:
                    <code data-storylet-binding-token>
                        <?= $bindingKey !== ''
                            ? builderEscape(
                                '{{' .
                                strtolower($bindingKey) .
                                '.name}}'
                            )
                            : '{{key.name}}' ?>
                    </code>
                </span>

                <button
                    type="button"
                    class="secondary-button"
                    data-remove-storylet-binding
                    style="margin-left:0.5em;"
                >
                    Remove Binding
                </button>
            </div>
        <?php endforeach; ?>
    </div>

    <button
        type="button"
        class="secondary-button"
        data-add-storylet-binding
    >
        + Add Binding
    </button>

    <template data-storylet-binding-template>
        <div
            class="builder-storylet-binding-row"
            data-storylet-binding-row
            style="margin:0 0 1em;padding:0.75em;border:1px solid #ddd;"
        >
            <label>
                Binding Name
                <input
                    type="text"
                    name="bindings[__BINDING_INDEX__][label]"
                    maxlength="80"
                    placeholder="Affected Character"
                    data-storylet-binding-label
                >
                <br>
                <small>
                    Descriptive author-facing name used in the builder.
                </small>
            </label>

            <label>
                Key
                <input
                    type="text"
                    name="bindings[__BINDING_INDEX__][key]"
                    maxlength="32"
                    pattern="[a-z][a-z0-9_]{0,31}"
                    placeholder="affected_character"
                    autocomplete="off"
                    spellcheck="false"
                    data-storylet-binding-key
                >
                <br>
                <small>
                    Internal identifier. Generated from Binding Name when blank;
                    lowercase letters, numbers, and underscores only.
                </small>
            </label>

            <label>
                Selection Rule
                <select
                    name="bindings[__BINDING_INDEX__][selector]"
                >
                    <option value="">
                        Select...
                    </option>

                    <?php foreach (
                        gameplayStoryletBindingSelectorOptions()
                        as $selectorValue => $selectorLabel
                    ): ?>
                        <option value="<?= builderEscape($selectorValue) ?>">
                            <?= builderEscape($selectorLabel) ?>
                        </option>
                    <?php endforeach; ?>
                </select>
                <br>
                <small>
                    Determines which runtime Entity this Binding selects.
                </small>
            </label>

            <span style="margin-left:0.5em;">
                Narrative Token:
                <code data-storylet-binding-token>{{key.name}}</code>
            </span>

            <button
                type="button"
                class="secondary-button"
                data-remove-storylet-binding
                style="margin-left:0.5em;"
            >
                Remove Binding
            </button>
        </div>
    </template>
</section>

<script>
(function () {
    'use strict';

    const editor =
        document.querySelector(
            '[data-storylet-bindings-editor]'
        );

    if (!editor) {
        return;
    }

    const list =
        editor.querySelector(
            '[data-storylet-bindings-list]'
        );

    const template =
        editor.querySelector(
            '[data-storylet-binding-template]'
        );

    let nextIndex = 0;

    editor
        .querySelectorAll(
            '[data-storylet-binding-row]'
        )
        .forEach(
            function (row) {
                row
                    .querySelectorAll(
                        '[name]'
                    )
                    .forEach(
                        function (field) {
                            const match =
                                field.name.match(
                                    /^bindings\[(\d+)\]/
                                );

                            if (match) {
                                nextIndex =
                                    Math.max(
                                        nextIndex,
                                        Number(match[1]) + 1
                                    );
                            }
                        }
                    );
            }
        );

    function normalizeBindingKey(value) {
        let key =
            String(value || '')
                .trim()
                .toLowerCase()
                .replace(/[^a-z0-9]+/g, '_')
                .replace(/^_+|_+$/g, '')
                .replace(/_+/g, '_');

        if (key === '') {
            return '';
        }

        if (!/^[a-z]/.test(key)) {
            key = 'binding_' + key;
        }

        return key
            .slice(0, 32)
            .replace(/_+$/g, '');
    }


    function initializeKeyMode(row) {
        const keyInput =
            row.querySelector(
                '[data-storylet-binding-key]'
            );

        if (!keyInput) {
            return;
        }

        if (!row.dataset.bindingKeyMode) {
            row.dataset.bindingKeyMode =
                String(keyInput.value || '').trim() === ''
                    ? 'auto'
                    : 'manual';
        }
    }


    function syncAutomaticKey(row) {
        initializeKeyMode(row);

        if (row.dataset.bindingKeyMode !== 'auto') {
            return;
        }

        const labelInput =
            row.querySelector(
                '[data-storylet-binding-label]'
            );

        const keyInput =
            row.querySelector(
                '[data-storylet-binding-key]'
            );

        if (!keyInput) {
            return;
        }

        keyInput.value =
            normalizeBindingKey(
                labelInput
                    ? labelInput.value
                    : ''
            );
    }


    function refreshToken(row) {
        const keyInput =
            row.querySelector(
                '[data-storylet-binding-key]'
            );

        const token =
            row.querySelector(
                '[data-storylet-binding-token]'
            );

        if (!token) {
            return;
        }

        const key =
            keyInput
                ? String(
                    keyInput.value ||
                    ''
                )
                    .trim()
                    .toLowerCase()
                : '';

        token.textContent =
            key !== ''
                ? '{{' + key + '.name}}'
                : '{{key.name}}';
    }

    editor.addEventListener(
        'input',
        function (event) {
            const row =
                event.target.closest(
                    '[data-storylet-binding-row]'
                );

            if (!row) {
                return;
            }

            if (
                event.target.matches(
                    '[data-storylet-binding-label]'
                )
            ) {
                syncAutomaticKey(row);
                refreshToken(row);
                return;
            }

            if (
                event.target.matches(
                    '[data-storylet-binding-key]'
                )
            ) {
                const normalized =
                    normalizeBindingKey(
                        event.target.value
                    );

                if (event.target.value !== normalized) {
                    event.target.value = normalized;
                }

                row.dataset.bindingKeyMode =
                    normalized === ''
                        ? 'auto'
                        : 'manual';

                refreshToken(row);
            }
        }
    );

    editor.addEventListener(
        'click',
        function (event) {
            const remove =
                event.target.closest(
                    '[data-remove-storylet-binding]'
                );

            if (remove) {
                const row =
                    remove.closest(
                        '[data-storylet-binding-row]'
                    );

                if (row) {
                    row.remove();
                }

                return;
            }

            if (
                event.target.closest(
                    '[data-add-storylet-binding]'
                ) &&
                list &&
                template
            ) {
                const html =
                    template.innerHTML
                        .replaceAll(
                            '__BINDING_INDEX__',
                            String(nextIndex++)
                        );

                const holder =
                    document.createElement(
                        'div'
                    );

                holder.innerHTML =
                    html.trim();

                const row =
                    holder.firstElementChild;

                if (row) {
                    list.appendChild(row);
                    initializeKeyMode(row);
                    syncAutomaticKey(row);
                    refreshToken(row);
                }
            }
        }
    );

    editor
        .querySelectorAll(
            '[data-storylet-binding-row]'
        )
        .forEach(
            function (row) {
                initializeKeyMode(row);
                refreshToken(row);
            }
        );
})();
</script>
<section data-builder-conditions-panel>
    <h3>Conditions</h3>

    <p>
        Conditions determine whether this Storylet is eligible. A root Manual
        Storylet can be offered only while these are true. Automatic and Chance
        Storylets can fire only while eligible. For a child Storylet, these same
        Conditions determine whether its Branch is available to the player.
    </p>

    <?php
    $conditionEditorNode =
        $storyletConditions;

    $conditionEditorName =
        'conditions';

    $conditionEditorTargets =
        $storyletConditionTargets;

    require __DIR__ . '/../gameplay/condition-editor.php';
    ?>
</section>


<section
    class="builder-effects-panel"
    data-builder-effects-panel
>
    <h3>Effects</h3>

    <p>
        These Effects run once when the player enters this Storylet. Each Effect
        may use ordered conditional results and an optional Otherwise result.
        Targets come from Wayfarer's universal runtime-state catalog, so the
        Storylet may inspect or change Game, Player, Region, Location, Item, and
        Character Trait state. Definition metadata such as min/max is not a target.
    </p>

    <?php
    $gameplayEffects =
        $storyletEffects;

    $gameplayGameTraitTargets = [];
    $gameplayScopeTraitTargets = [];
    $gameplayScopeKey = '';
    $gameplayScopeLabel = '';
    $gameplayAllowEffectNavigation = true;
    $gameplayTargetCatalog =
        $storyletEffectTargets;
    $gameplayConditionTargets =
        $storyletConditionTargets;
    $gameplayEffectDescription =
        'Storylet Effects execute once when this Storylet is entered. ' .
        'A Storylet → Continue To Effect resolves after the other Effects and ' .
        'opens the selected root Storylet.';

    require __DIR__ . '/../gameplay/effects-editor.php';
    ?>
</section>


<section data-builder-branches-panel>
    <h3>Branches</h3>

    <p>
        A Branch is another Storylet whose Parent Storylet is this Storylet.
        The child Storylet's Conditions decide whether the Branch is available;
        entering that child runs its Effects. Children may have their own Branches,
        so this structure can nest to any practical depth without a separate
        branch-object schema.
    </p>

    <?php if (!$id): ?>
        <p>
            Save this Storylet first. After it has an ID, you can add child
            Branch Storylets here.
        </p>
    <?php else: ?>
        <?php
        $branchStmt = $pdo->prepare(
            "
            SELECT
                id,
                name,
                branch_label,
                branch_sort_order,
                trigger_type,
                status
            FROM wf_storylets
            WHERE game_id = ?
              AND parent_storylet_id = ?
            ORDER BY branch_sort_order, name, id
            "
        );

        $branchStmt->execute([
            $gameId,
            (int)$id,
        ]);

        $storyletBranches =
            $branchStmt->fetchAll(
                PDO::FETCH_ASSOC
            );
        ?>

        <p>
            <a
                class="builder-new-object"
                href="<?= builderEscape($builderPage) ?>?game=<?= (int)$gameId ?>&amp;type=storylets&amp;parent_storylet_id=<?= (int)$id ?>"
            >
                + New Branch Storylet
            </a>
        </p>

        <?php if (!$storyletBranches): ?>
            <p>No child Branches have been created yet.</p>
        <?php else: ?>
            <div class="builder-storylet-branches">
                <table>
                    <thead>
                        <tr>
                            <th>Order</th>
                            <th>Branch</th>
                            <th>Storylet</th>
                            <th>Trigger</th>
                            <th>Status</th>
                        </tr>
                    </thead>
                    <tbody>
                        <?php foreach ($storyletBranches as $branch): ?>
                            <?php
                            $branchLabel =
                                trim(
                                    (string)(
                                        $branch['branch_label']
                                        ?? ''
                                    )
                                );

                            if ($branchLabel === '') {
                                $branchLabel =
                                    (string)$branch['name'];
                            }
                            ?>
                            <tr>
                                <td><?= (int)$branch['branch_sort_order'] ?></td>
                                <td><?= builderEscape($branchLabel) ?></td>
                                <td>
                                    <a href="<?= builderEscape($builderPage) ?>?game=<?= (int)$gameId ?>&amp;type=storylets&amp;id=<?= (int)$branch['id'] ?>">
                                        <?= builderEscape($branch['name']) ?>
                                    </a>
                                </td>
                                <td><?= builderEscape($branch['trigger_type']) ?></td>
                                <td><?= builderEscape($branch['status']) ?></td>
                            </tr>
                        <?php endforeach; ?>
                    </tbody>
                </table>
            </div>
        <?php endif; ?>
    <?php endif; ?>
</section>



==============================================================================
FILE: includes/builder/tick-effects.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Region Gameplay Adapter
|--------------------------------------------------------------------------
|
| WAYFARER_GAMEPLAY_MODULAR_V25
|
| Region-specific loading lives here. The actual Tick Effects editor and
| validation are shared under includes/gameplay/.
|
| Expected variables:
|   $pdo
|   $gameId
|   $game
|   $record
|   $traits
|
*/

require_once __DIR__ . '/../gameplay/functions.php';

$regionGameplayConfig = [];

$regionGameplayRecordId =
    (int)(
        $record['id']
        ?? $id
        ?? 0
    );

if ($regionGameplayRecordId > 0) {

    $stmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_regions
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

    $stmt->execute([
        $regionGameplayRecordId,
        $gameId,
    ]);

    $rawConfig =
        $stmt->fetchColumn();

    if (
        $rawConfig !== false &&
        $rawConfig !== null &&
        $rawConfig !== ''
    ) {

        $decoded =
            json_decode(
                (string)$rawConfig,
                true
            );

        if (is_array($decoded)) {
            $regionGameplayConfig =
                $decoded;
        }
    }

} elseif (!empty($record['config'])) {

    $decoded =
        json_decode(
            (string)$record['config'],
            true
        );

    if (is_array($decoded)) {
        $regionGameplayConfig =
            $decoded;
    }
}


/*
 * Failed POSTs retain the author's submitted rows.
 */
if (
    $_SERVER['REQUEST_METHOD'] === 'POST' &&
    isset($_POST['tick_effects']) &&
    is_array($_POST['tick_effects'])
) {

    $gameplayTickEffects =
        array_values(
            $_POST['tick_effects']
        );

} else {

    $gameplayTickEffects =
        isset(
            $regionGameplayConfig['tick_effects']
        ) &&
        is_array(
            $regionGameplayConfig['tick_effects']
        )
            ? array_values(
                $regionGameplayConfig['tick_effects']
            )
            : [];
}


/* WAYFARER_CANONICALIZE_REGION_EFFECTS_FOR_EDITOR_V68 */
if ($regionGameplayRecordId > 0) {
    $gameplayTickEffects =
        gameplayCanonicalizeLegacyCurrentRegionTickEffects(
            $gameplayTickEffects,
            $regionGameplayRecordId
        );
}


/*
 * Game trait targets.
 */
$gameConfig = [];

if (!empty($game['config'])) {

    $decoded =
        json_decode(
            (string)$game['config'],
            true
        );

    if (is_array($decoded)) {
        $gameConfig =
            $decoded;
    }
}

$gameplayGameTraitTargets =
    gameplayNumericTraitTargets(
        $gameConfig['traits']
        ?? [],
        'game'
    );


/*
 * WAYFARER_NO_CURRENT_REGION_ALIAS_V68
 *
 * Region Tick Effects use the universal target catalog only. A Region Trait
 * is addressed by its actual Region id; there is no separate Current Region
 * authoring scope.
 */
$gameplayScopeTraitTargets = [];
$gameplayScopeKey = '';
$gameplayScopeLabel = '';

$gameplayAllowNavigation =
    true;

$gameplayNavigationType =
    (string)(
        $record['navigation_type']
        ?? ''
    );

/* WAYFARER_UNIVERSAL_REGION_TARGETS_V56 */
/* WAYFARER_CANONICAL_REGION_TARGET_EDITOR_V68 */
$gameplayTargetCatalog =
    gameplayRuntimeStateTargets(
        $pdo,
        $gameId
    );

$gameplayConditionTargets =
    $gameplayTargetCatalog;

$gameplayDescription =
    "These effects are applied while this Region is the player's current Region.";

require __DIR__ . '/../gameplay/tick-effects-editor.php';



==============================================================================
FILE: includes/gameplay/condition-editor.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Shared Recursive Condition Editor
|--------------------------------------------------------------------------
|
| WAYFARER_CONDITION_EDITOR_V27
|
| Expected:
|   $conditionEditorNode
|   $conditionEditorName
|   $conditionEditorTargets
|
| The editor is deliberately generic. It does not know that its current
| consumer is a Tick Effect.
|
*/


if (
    !function_exists(
        'wayfarerConditionEditorRenderNode'
    )
) {

    function wayfarerConditionEditorRenderTargetOptions(
        array $targets,
        string $selected
    ): void {

        echo '<option value="">Select target...</option>';

        $grouped = [];

        foreach ($targets as $key => $target) {

            if (!is_array($target)) {
                continue;
            }

            /*
             * WAYFARER_LOCATION_CONDITION_TARGETS_V75
             *
             * Keep a hidden legacy target visible only when an existing
             * Condition already uses it.
             */
            if (
                !empty($target['condition_hidden']) &&
                $key !== $selected
            ) {
                continue;
            }

            $label =
                (string)(
                    $target['label']
                    ?? $key
                );

            $group =
                (string)(
                    $target['group']
                    ?? 'Targets'
                );

            if (!isset($grouped[$group])) {
                $grouped[$group] = [];
            }

            $helper =
                trim(
                    (string)(
                        $target['helper']
                        ?? ''
                    )
                );

            $grouped[$group][$key] =
                $helper !== ''
                    ? $label . ' — ' . $helper
                    : $label;
        }

        foreach ($grouped as $group => $options) {

            echo '<optgroup label="' .
                builderEscape(
                    $group
                ) .
                '">';

            foreach ($options as $value => $label) {

                echo '<option value="' .
                    builderEscape(
                        $value
                    ) .
                    '"' .
                    (
                        $value === $selected
                            ? ' selected'
                            : ''
                    ) .
                    '>' .
                    builderEscape(
                        $label
                    ) .
                    '</option>';
            }

            echo '</optgroup>';
        }
    }


    function wayfarerConditionEditorRenderNode(
        $node,
        string $name,
        array $targets,
        bool $isRoot = false
    ): void {

        if (
            !is_array(
                $node
            ) ||
            (
                ($node['type'] ?? '') !== 'group' &&
                ($node['type'] ?? '') !== 'condition'
            )
        ) {
            $node =
                wayfarerConditionEmptyGroup(
                    'all'
                );
        }

        $type =
            (string)(
                $node['type']
                ?? 'group'
            );


        if ($type === 'condition') {

            $targetKey =
                (string)(
                    $node['scope']
                    ?? ''
                ) .
                ':' .
                (string)(
                    $node['target_type']
                    ?? ''
                ) .
                ':' .
                (string)(
                    $node['target_id']
                    ?? ''
                );

            $operator =
                (string)(
                    $node['operator']
                    ?? 'equals'
                );

            $value =
                $node['value']
                ?? '';

            /* WAYFARER_DATATYPE_CONDITION_EDITOR_V58 */
            $targetDefinition =
                isset($targets[$targetKey]) &&
                is_array($targets[$targetKey])
                    ? $targets[$targetKey]
                    : [];

            $allowedOperators =
                isset($targetDefinition['condition_operators']) &&
                is_array($targetDefinition['condition_operators'])
                    ? array_values($targetDefinition['condition_operators'])
                    : wayfarerConditionOperators();

            $valueOptions =
                isset($targetDefinition['value_options']) &&
                is_array($targetDefinition['value_options'])
                    ? $targetDefinition['value_options']
                    : [];

            $dataType =
                strtolower(
                    trim(
                        (string)(
                            $targetDefinition['data_type']
                            ?? $targetDefinition['trait_type']
                            ?? 'text'
                        )
                    )
                );

            if ($dataType === 'binary') {
                $dataType = 'boolean';
            }

            ?>

            <div
                class="builder-condition-row"
                data-condition-node
                data-condition-type="condition"
            >

                <input
                    type="hidden"
                    name="<?= builderEscape(
                        $name
                    ) ?>[type]"
                    value="condition"
                >

                <label>
                    Target
                    <select
                        name="<?= builderEscape(
                            $name
                        ) ?>[target]"
                        data-condition-target
                    >
                        <?php
                        wayfarerConditionEditorRenderTargetOptions(
                            $targets,
                            $targetKey
                        );
                        ?>
                    </select>
                </label>

                <label>
                    Comparison
                    <select
                        name="<?= builderEscape(
                            $name
                        ) ?>[operator]"
                        data-condition-operator
                    >
                        <?php
                        $operatorLabels = [
                            'equals' => 'Equals',
                            'not_equals' => 'Does not equal',
                            'greater_than' => 'Greater than',
                            'greater_than_or_equal' => 'Greater than or equal',
                            'less_than' => 'Less than',
                            'less_than_or_equal' => 'Less than or equal',
                        ];
                        ?>
                        <?php foreach (
                            $allowedOperators
                            as $operatorValue
                        ): ?>
                            <?php
                            $operatorLabel =
                                $operatorLabels[$operatorValue]
                                ?? $operatorValue;
                            ?>

                            <option
                                value="<?= builderEscape(
                                    $operatorValue
                                ) ?>"
                                <?= $operator === $operatorValue
                                    ? 'selected'
                                    : '' ?>
                            >
                                <?= builderEscape(
                                    $operatorLabel
                                ) ?>
                            </option>

                        <?php endforeach; ?>
                    </select>
                </label>

                <label data-condition-value-wrap>
                    Value

                    <input
                        type="<?= $dataType === 'number'
                            ? 'number'
                            : 'text' ?>"
                        <?= $dataType === 'number'
                            ? 'step="any"'
                            : '' ?>
                        name="<?= builderEscape(
                            $name
                        ) ?>[value]"
                        value="<?= builderEscape(
                            $value
                        ) ?>"
                        data-condition-value-input
                        <?= $valueOptions
                            ? 'hidden disabled'
                            : '' ?>
                    >

                    <select
                        name="<?= builderEscape(
                            $name
                        ) ?>[value]"
                        data-condition-value-select
                        <?= $valueOptions
                            ? ''
                            : 'hidden disabled' ?>
                    >
                        <?php foreach ($valueOptions as $optionValue => $optionLabel): ?>
                            <option
                                value="<?= builderEscape($optionValue) ?>"
                                <?= (string)$value === (string)$optionValue
                                    ? 'selected'
                                    : '' ?>
                            >
                                <?= builderEscape($optionLabel) ?>
                            </option>
                        <?php endforeach; ?>
                    </select>
                </label>

                <button
                    type="button"
                    class="secondary-button"
                    data-remove-condition-node
                >
                    Remove
                </button>

            </div>

            <?php

            return;
        }


        $mode =
            (string)(
                $node['mode']
                ?? 'all'
            );

        $children =
            isset(
                $node['children']
            ) &&
            is_array(
                $node['children']
            )
                ? array_values(
                    $node['children']
                )
                : [];

        ?>

        <div
            class="builder-condition-group<?= $isRoot
                ? ' builder-condition-group-root'
                : '' ?>"
            data-condition-node
            data-condition-type="group"
        >

            <input
                type="hidden"
                name="<?= builderEscape(
                    $name
                ) ?>[type]"
                value="group"
            >

            <div class="builder-condition-group-header">

                <label>
                    Match
                    <select
                        name="<?= builderEscape(
                            $name
                        ) ?>[mode]"
                    >
                        <option
                            value="all"
                            <?= $mode === 'all'
                                ? 'selected'
                                : '' ?>
                        >
                            ALL
                        </option>

                        <option
                            value="any"
                            <?= $mode === 'any'
                                ? 'selected'
                                : '' ?>
                        >
                            ANY
                        </option>
                    </select>
                </label>

                <span>
                    of the following
                </span>

                <?php if (!$isRoot): ?>
                    <button
                        type="button"
                        class="secondary-button"
                        data-remove-condition-node
                    >
                        Remove Group
                    </button>
                <?php endif; ?>

            </div>

            <div
                class="builder-condition-children"
                data-condition-children
            >

                <?php foreach (
                    $children
                    as $childIndex => $child
                ): ?>

                    <?php
                    echo '<div data-condition-existing-child="' .
                        (int)$childIndex .
                        '">';

                    wayfarerConditionEditorRenderNode(
                        $child,
                        $name .
                            '[children][' .
                            $childIndex .
                            ']',
                        $targets,
                        false
                    );

                    echo '</div>';
                    ?>

                <?php endforeach; ?>

            </div>

            <div class="builder-condition-actions">

                <button
                    type="button"
                    class="secondary-button"
                    data-add-condition
                >
                    + Add Condition
                </button>

                <button
                    type="button"
                    class="secondary-button"
                    data-add-condition-group
                >
                    + Add Group
                </button>

            </div>

        </div>

        <?php
    }
}


$conditionEditorNode =
    $conditionEditorNode
    ?? null;

$conditionEditorName =
    (string)(
        $conditionEditorName
        ?? 'conditions'
    );

$conditionEditorTargets =
    $conditionEditorTargets
    ?? [];

/*
 * WAYFARER_LOCATION_CONDITION_TARGETS_V75
 * WAYFARER_CONDITION_EDITOR_RECOVERY_V78
 *
 * Every shared Condition box receives the same navigation vocabulary without
 * changing the Effect target catalogs supplied by its parent editor.
 */
if (
    isset($pdo, $gameId) &&
    $pdo instanceof PDO &&
    function_exists(
        'gameplayNavigationConditionTargets'
    )
) {
    $conditionEditorTargets =
        array_replace(
            $conditionEditorTargets,
            gameplayNavigationConditionTargets(
                $pdo,
                (int)$gameId
            ),
            function_exists(
                'gameplayTimeConditionTargets'
            )
                ? gameplayTimeConditionTargets(
                    $pdo,
                    (int)$gameId
                )
                : []
        );
}

/*
 * A few pre-group Storylet Conditions were stored as a single root Condition.
 * Render them inside an ALL root group so Match / Add Condition / Add Group
 * are always present. Saving naturally persists the canonical group shape.
 */
if (
    is_array($conditionEditorNode) &&
    (
        $conditionEditorNode['type']
        ?? ''
    ) === 'condition'
) {
    $conditionEditorNode = [
        'type' => 'group',
        'mode' => 'all',
        'children' => [
            $conditionEditorNode,
        ],
    ];
}

?>

<div
    class="builder-condition-editor"
    data-condition-editor
>
    <!-- WAYFARER_GENERIC_CONDITION_INIT_V45_2 -->
    <script
        type="application/json"
        data-condition-editor-targets-json
    ><?= json_encode(
        $conditionEditorTargets,
        JSON_UNESCAPED_SLASHES |
        JSON_UNESCAPED_UNICODE |
        JSON_HEX_TAG |
        JSON_HEX_AMP |
        JSON_HEX_APOS |
        JSON_HEX_QUOT
    ) ?></script>

    <?php
    wayfarerConditionEditorRenderNode(
        $conditionEditorNode,
        $conditionEditorName,
        $conditionEditorTargets,
        true
    );
    ?>
</div>


==============================================================================
FILE: includes/gameplay/conditions.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Wayfarer Shared Condition Engine
|--------------------------------------------------------------------------
|
| WAYFARER_CONDITION_ENGINE_V26
|
| Canonical recursive schema:
|
| Group:
| {
|     "type": "group",
|     "mode": "all",
|     "children": [...]
| }
|
| Condition:
| {
|     "type": "condition",
|     "scope": "game",
|     "target_type": "trait",
|     "target_id": "travel_pace",
|     "operator": "equals",
|     "value": "grueling"
| }
|
| Empty/null conditions mean TRUE. This is important for backwards
| compatibility: existing Tick Effects with no conditions still always run.
|
| The evaluator does NOT know about databases, Regions, Storylets, or Tick
| Effects. Callers provide a resolver callback that returns the current value
| for a condition target.
|
*/


function wayfarerConditionOperators(): array
{
    return [
        'equals',
        'not_equals',
        'greater_than',
        'greater_than_or_equal',
        'less_than',
        'less_than_or_equal',
    ];
}


function wayfarerConditionGroupModes(): array
{
    return [
        'all',
        'any',
    ];
}


function wayfarerConditionEmptyGroup(
    string $mode = 'all'
): array {

    if (
        !in_array(
            $mode,
            wayfarerConditionGroupModes(),
            true
        )
    ) {
        $mode = 'all';
    }

    return [
        'type' => 'group',
        'mode' => $mode,
        'children' => [],
    ];
}


function wayfarerConditionNormalizeScalar(
    $value
) {
    if (is_bool($value)) {
        return $value;
    }

    if (
        is_int($value) ||
        is_float($value)
    ) {
        return $value;
    }

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

    $stringValue =
        trim(
            (string)$value
        );

    $lower =
        strtolower(
            $stringValue
        );

    if ($lower === 'true') {
        return true;
    }

    if ($lower === 'false') {
        return false;
    }

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

    if (
        $stringValue !== '' &&
        is_numeric($stringValue)
    ) {
        return
            strpos(
                $stringValue,
                '.'
            ) !== false
                ? (float)$stringValue
                : (int)$stringValue;
    }

    return $stringValue;
}


function wayfarerConditionCompare(
    $actual,
    string $operator,
    $expected
): bool {

    if (
        !in_array(
            $operator,
            wayfarerConditionOperators(),
            true
        )
    ) {
        return false;
    }

    $actual =
        wayfarerConditionNormalizeScalar(
            $actual
        );

    $expected =
        wayfarerConditionNormalizeScalar(
            $expected
        );

    /*
     * Numeric comparisons should be numeric when both sides are numeric.
     * Otherwise equality is strict after scalar normalization and ordering
     * comparisons use lexical string comparison.
     */
    $bothNumeric =
        is_numeric($actual) &&
        is_numeric($expected);

    if ($bothNumeric) {
        $left = (float)$actual;
        $right = (float)$expected;
    } else {
        $left = $actual;
        $right = $expected;
    }

    switch ($operator) {

        case 'equals':
            return $left === $right;

        case 'not_equals':
            return $left !== $right;

        case 'greater_than':
            return $bothNumeric
                ? $left > $right
                : strcmp(
                    (string)$left,
                    (string)$right
                ) > 0;

        case 'greater_than_or_equal':
            return $bothNumeric
                ? $left >= $right
                : strcmp(
                    (string)$left,
                    (string)$right
                ) >= 0;

        case 'less_than':
            return $bothNumeric
                ? $left < $right
                : strcmp(
                    (string)$left,
                    (string)$right
                ) < 0;

        case 'less_than_or_equal':
            return $bothNumeric
                ? $left <= $right
                : strcmp(
                    (string)$left,
                    (string)$right
                ) <= 0;
    }

    return false;
}


function wayfarerConditionValidateNode(
    $node,
    int $depth = 0
): array {

    if ($depth > 20) {
        return [
            'valid' => false,
            'error' =>
                'Condition nesting is too deep.',
            'node' => null,
        ];
    }

    /*
     * No condition tree means "always true".
     */
    if (
        $node === null ||
        $node === []
    ) {
        return [
            'valid' => true,
            'error' => '',
            'node' => null,
        ];
    }

    if (!is_array($node)) {
        return [
            'valid' => false,
            'error' =>
                'Condition data must be an object.',
            'node' => null,
        ];
    }

    $type =
        trim(
            (string)(
                $node['type']
                ?? ''
            )
        );

    if ($type === 'group') {

        $mode =
            trim(
                (string)(
                    $node['mode']
                    ?? 'all'
                )
            );

        if (
            !in_array(
                $mode,
                wayfarerConditionGroupModes(),
                true
            )
        ) {
            return [
                'valid' => false,
                'error' =>
                    'Condition groups must use ALL or ANY.',
                'node' => null,
            ];
        }

        $children =
            $node['children']
            ?? [];

        if (!is_array($children)) {
            return [
                'valid' => false,
                'error' =>
                    'Condition group children must be an array.',
                'node' => null,
            ];
        }

        $normalizedChildren = [];

        foreach ($children as $child) {

            $result =
                wayfarerConditionValidateNode(
                    $child,
                    $depth + 1
                );

            if (!$result['valid']) {
                return $result;
            }

            if ($result['node'] !== null) {
                $normalizedChildren[] =
                    $result['node'];
            }
        }

        return [
            'valid' => true,
            'error' => '',
            'node' => [
                'type' => 'group',
                'mode' => $mode,
                'children' =>
                    $normalizedChildren,
            ],
        ];
    }

    if ($type === 'condition') {

        $scope =
            trim(
                (string)(
                    $node['scope']
                    ?? ''
                )
            );

        $targetType =
            trim(
                (string)(
                    $node['target_type']
                    ?? ''
                )
            );

        $targetId =
            trim(
                (string)(
                    $node['target_id']
                    ?? ''
                )
            );

        $operator =
            trim(
                (string)(
                    $node['operator']
                    ?? ''
                )
            );

        if (
            $scope === '' ||
            $targetType === '' ||
            $targetId === ''
        ) {
            return [
                'valid' => false,
                'error' =>
                    'Each condition must identify a scope and target.',
                'node' => null,
            ];
        }

        if (
            !in_array(
                $operator,
                wayfarerConditionOperators(),
                true
            )
        ) {
            return [
                'valid' => false,
                'error' =>
                    'Invalid condition operator.',
                'node' => null,
            ];
        }

        if (!array_key_exists('value', $node)) {
            return [
                'valid' => false,
                'error' =>
                    'Each condition must include a comparison value.',
                'node' => null,
            ];
        }

        return [
            'valid' => true,
            'error' => '',
            'node' => [
                'type' => 'condition',
                'scope' => $scope,
                'target_type' => $targetType,
                'target_id' => $targetId,
                'operator' => $operator,
                'value' => $node['value'],
            ],
        ];
    }

    return [
        'valid' => false,
        'error' =>
            'Condition nodes must be a group or condition.',
        'node' => null,
    ];
}


function wayfarerConditionEvaluate(
    $node,
    callable $resolver,
    int $depth = 0
): bool {

    /*
     * Absence of conditions means unconditional / always true.
     */
    if (
        $node === null ||
        $node === []
    ) {
        return true;
    }

    if (
        $depth > 20 ||
        !is_array($node)
    ) {
        return false;
    }

    $type =
        (string)(
            $node['type']
            ?? ''
        );

    if ($type === 'condition') {

        $scope =
            (string)(
                $node['scope']
                ?? ''
            );

        $targetType =
            (string)(
                $node['target_type']
                ?? ''
            );

        $targetId =
            (string)(
                $node['target_id']
                ?? ''
            );

        $operator =
            (string)(
                $node['operator']
                ?? ''
            );

        if (
            $scope === '' ||
            $targetType === '' ||
            $targetId === '' ||
            !array_key_exists(
                'value',
                $node
            )
        ) {
            return false;
        }

        /*
         * Resolver contract:
         *
         * return [
         *     'found' => true,
         *     'value' => <current value>
         * ];
         *
         * Missing targets fail closed rather than silently passing.
         */
        $resolved =
            $resolver(
                $scope,
                $targetType,
                $targetId
            );

        if (
            !is_array($resolved) ||
            empty($resolved['found'])
        ) {
            return false;
        }

        /* WAYFARER_LIVE_LOCATION_ANCHORS_V76 */
        if (
            array_key_exists(
                'comparison_scope_match',
                $resolved
            ) &&
            !$resolved['comparison_scope_match']
        ) {
            return $operator === 'not_equals';
        }

        return
            wayfarerConditionCompare(
                $resolved['value']
                    ?? null,
                $operator,
                $node['value']
            );
    }

    if ($type === 'group') {

        $mode =
            (string)(
                $node['mode']
                ?? 'all'
            );

        $children =
            $node['children']
            ?? [];

        if (!is_array($children)) {
            return false;
        }

        /*
         * Empty groups are true. This keeps an empty root group equivalent
         * to "no conditions" and makes progressive authoring predictable.
         */
        if ($children === []) {
            return true;
        }

        if ($mode === 'all') {

            foreach ($children as $child) {

                if (
                    !wayfarerConditionEvaluate(
                        $child,
                        $resolver,
                        $depth + 1
                    )
                ) {
                    return false;
                }
            }

            return true;
        }

        if ($mode === 'any') {

            foreach ($children as $child) {

                if (
                    wayfarerConditionEvaluate(
                        $child,
                        $resolver,
                        $depth + 1
                    )
                ) {
                    return true;
                }
            }

            return false;
        }

        return false;
    }

    return false;
}


function wayfarerConditionsPass(
    $conditions,
    callable $resolver
): bool {

    $validation =
        wayfarerConditionValidateNode(
            $conditions
        );

    if (!$validation['valid']) {
        return false;
    }

    return
        wayfarerConditionEvaluate(
            $validation['node'],
            $resolver
        );
}


==============================================================================
FILE: includes/gameplay/effects-editor.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Shared Effects Editor
 * WAYFARER_ONE_TIME_EFFECTS_EDITOR_V42
 * WAYFARER_GENERALIZED_EFFECT_EDITOR_V43
 * --------------------------------------------------------------------------
 *
 * An Effect controls one target and owns ordered result branches:
 *
 *   WHEN conditions -> operation/value
 *   OTHERWISE       -> operation/value
 *
 * First matching result wins. Each result may use a Fixed value or roll a
 * Random Min-Max value once when the Effect executes.
 */

$gameplayEffects =
    isset(
        $gameplayEffects
    ) &&
    is_array(
        $gameplayEffects
    )
        ? array_values(
            $gameplayEffects
        )
        : [];

$gameplayGameTraitTargets =
    $gameplayGameTraitTargets
    ?? [];

$gameplayScopeTraitTargets =
    $gameplayScopeTraitTargets
    ?? [];

$gameplayScopeKey =
    (string)(
        $gameplayScopeKey
        ?? ''
    );

$gameplayScopeLabel =
    (string)(
        $gameplayScopeLabel
        ?? ''
    );

$gameplayAllowEffectNavigation =
    !empty(
        $gameplayAllowEffectNavigation
    );

$gameplayEffectDescription =
    (string)(
        $gameplayEffectDescription
        ?? 'These Effects run once when this object is triggered.'
    );

$gameplayConditionTargets =
    isset(
        $gameplayConditionTargets
    ) &&
    is_array(
        $gameplayConditionTargets
    )
        ? $gameplayConditionTargets
        : [];

/* WAYFARER_LIVE_LOCATION_ANCHORS_V76 */
if (
    isset($pdo, $gameId) &&
    $pdo instanceof PDO &&
    function_exists(
        'gameplayNavigationConditionTargets'
    )
) {
    $gameplayConditionTargets =
        array_replace(
            $gameplayConditionTargets,
            gameplayNavigationConditionTargets(
                $pdo,
                (int)$gameId
            ),
            function_exists(
                'gameplayTimeConditionTargets'
            )
                ? gameplayTimeConditionTargets(
                    $pdo,
                    (int)$gameId
                )
                : []
        );
}


/* WAYFARER_UNIVERSAL_EFFECT_TARGET_EDITOR_V56 */
$gameplayTargetCatalog =
    isset($gameplayTargetCatalog) &&
    is_array($gameplayTargetCatalog)
        ? $gameplayTargetCatalog
        : [];
$renderEffectTargetOptions =
    function (
        array $effect = []
    ) use (
        $gameplayAllowEffectNavigation,
        $gameplayGameTraitTargets,
        $gameplayScopeKey,
        $gameplayScopeLabel,
        $gameplayScopeTraitTargets,
        $gameplayTargetCatalog
    ): void {

        echo '<option value="">Select target...</option>';

        if ($gameplayTargetCatalog) {
            $selectedKey =
                (string)(
                    $effect['target_scope']
                    ?? ''
                ) .
                ':' .
                (string)(
                    $effect['target_type']
                    ?? ''
                ) .
                ':' .
                (string)(
                    $effect['target_id']
                    ?? ''
                );

            $grouped = [];

            foreach (
                $gameplayTargetCatalog
                as $value => $target
            ) {
                if (!is_array($target)) {
                    continue;
                }

                if (
                    !empty($target['effect_hidden']) &&
                    $value !== $selectedKey
                ) {
                    continue;
                }

                $group =
                    (string)(
                        $target['group']
                        ?? 'Targets'
                    );

                if (!isset($grouped[$group])) {
                    $grouped[$group] = [];
                }

                $grouped[$group][$value] =
                    $target;
            }

            foreach ($grouped as $group => $options) {
                echo '<optgroup label="' .
                    builderEscape($group) .
                    '">';

                foreach ($options as $value => $target) {
                    echo '<option value="' .
                        builderEscape($value) .
                        '"' .
                        (
                            $value === $selectedKey
                                ? ' selected'
                                : ''
                        ) .
                        '>' .
                        builderEscape(
                            (string)(
                                $target['label']
                                ?? $value
                            ) .
                            (
                                trim((string)($target['helper'] ?? '')) !== ''
                                    ? ' — ' . trim((string)$target['helper'])
                                    : ''
                            )
                        ) .
                        '</option>';
                }

                echo '</optgroup>';
            }

            return;
        }




        if ($gameplayAllowEffectNavigation) {

            echo '<optgroup label="Navigation">';

            echo '<option value="navigation:position"' .
                (
                    gameplayEffectSelected(
                        $effect,
                        'navigation',
                        'position'
                    )
                        ? ' selected'
                        : ''
                ) .
                '>';

            echo 'Navigation → Position';

            echo '</option>';
            echo '</optgroup>';
        }


        if ($gameplayGameTraitTargets) {

            echo '<optgroup label="Game Traits">';

            foreach (
                $gameplayGameTraitTargets
                as $targetTrait
            ) {

                echo '<option value="game:' .
                    builderEscape(
                        $targetTrait['id']
                    ) .
                    '"' .
                    (
                        gameplayEffectSelected(
                            $effect,
                            'game',
                            $targetTrait['id']
                        )
                            ? ' selected'
                            : ''
                    ) .
                    '>';

                echo 'Game → ' .
                    builderEscape(
                        $targetTrait['name']
                    );

                echo '</option>';
            }

            echo '</optgroup>';
        }


        if (
            $gameplayScopeKey !== '' &&
            $gameplayScopeTraitTargets
        ) {

            echo '<optgroup label="' .
                builderEscape(
                    $gameplayScopeLabel
                ) .
                ' Traits">';

            foreach (
                $gameplayScopeTraitTargets
                as $targetTrait
            ) {

                echo '<option value="' .
                    builderEscape(
                        $gameplayScopeKey
                    ) .
                    ':' .
                    builderEscape(
                        $targetTrait['id']
                    ) .
                    '"' .
                    (
                        gameplayEffectSelected(
                            $effect,
                            $gameplayScopeKey,
                            $targetTrait['id']
                        )
                            ? ' selected'
                            : ''
                    ) .
                    '>';

                echo builderEscape(
                    $gameplayScopeLabel
                ) .
                    ' → ' .
                    builderEscape(
                        $targetTrait['name']
                    );

                echo '</option>';
            }

            echo '</optgroup>';
        }
    };


$renderEffectResultFields =
    function (
        array $branch,
        string $name
    ): void {

        $operation =
            gameplayEffectBranchOperation(
                $branch
            );

        $valueMode =
            gameplayEffectBranchValueMode(
                $branch
            );

        $value =
            gameplayEffectBranchValue(
                $branch
            );

        $minimum =
            gameplayEffectBranchMin(
                $branch
            );

        $maximum =
            gameplayEffectBranchMax(
                $branch
            );

        $noChange =
            $operation ===
            'none';

        ?>

        <div class="builder-effect-value-fields">

            <label>
                Result

                <select
                    name="<?= builderEscape(
                        $name
                    ) ?>[operation]"
                    data-effect-branch-operation
                >
                    <?php foreach (
                        [
                            'add' =>
                                'Add',
                            'subtract' =>
                                'Subtract',
                            'set' =>
                                'Set',
                            'none' =>
                                'No Change',
                        ]
                        as $operationValue => $operationLabel
                    ): ?>

                        <option
                            value="<?= builderEscape(
                                $operationValue
                            ) ?>"
                            <?= $operation === $operationValue
                                ? 'selected'
                                : '' ?>
                        >
                            <?= builderEscape(
                                $operationLabel
                            ) ?>
                        </option>

                    <?php endforeach; ?>
                </select>
            </label>


            <label
                data-effect-value-mode-wrap
                <?= $noChange
                    ? 'hidden'
                    : '' ?>
            >
                Value Type

                <select
                    name="<?= builderEscape(
                        $name
                    ) ?>[value_mode]"
                    data-effect-value-mode
                    <?= $noChange
                        ? 'disabled'
                        : '' ?>
                >
                    <option
                        value="fixed"
                        <?= $valueMode === 'fixed'
                            ? 'selected'
                            : '' ?>
                    >
                        Fixed
                    </option>

                    <option
                        value="random"
                        <?= $valueMode === 'random'
                            ? 'selected'
                            : '' ?>
                    >
                        Random
                    </option>
                </select>
            </label>


            <label
                data-effect-fixed-wrap
                <?= (
                    $noChange ||
                    $valueMode !== 'fixed'
                )
                    ? 'hidden'
                    : '' ?>
            >
                Value

                <input
                    type="number"
                    step="any"
                    name="<?= builderEscape(
                        $name
                    ) ?>[value]"
                    value="<?= builderEscape(
                        $value
                    ) ?>"
                    <?= (
                        $noChange ||
                        $valueMode !== 'fixed'
                    )
                        ? 'disabled'
                        : '' ?>
                >
            </label>


            <div
                class="builder-effect-random-range"
                data-effect-random-wrap
                <?= (
                    $noChange ||
                    $valueMode !== 'random'
                )
                    ? 'hidden'
                    : '' ?>
            >
                <label>
                    Min

                    <input
                        type="number"
                        step="any"
                        name="<?= builderEscape(
                            $name
                        ) ?>[value_min]"
                        value="<?= builderEscape(
                            $minimum
                        ) ?>"
                        <?= (
                            $noChange ||
                            $valueMode !== 'random'
                        )
                            ? 'disabled'
                            : '' ?>
                    >
                </label>

                <label>
                    Max

                    <input
                        type="number"
                        step="any"
                        name="<?= builderEscape(
                            $name
                        ) ?>[value_max]"
                        value="<?= builderEscape(
                            $maximum
                        ) ?>"
                        <?= (
                            $noChange ||
                            $valueMode !== 'random'
                        )
                            ? 'disabled'
                            : '' ?>
                    >
                </label>
            </div>

        </div>

        <?php
    };

?>
<section
    data-builder-effects
>
    <h3>Effects</h3>

    <p>
        <?= builderEscape(
            $gameplayEffectDescription
        ) ?>
    </p>

    <p class="builder-field-help">
        Each Effect controls one target. Results are checked from top to bottom;
        the first matching result wins. Random values are rolled once when the
        Effect fires.
    </p>


    <div
        class="builder-effects-list"
        data-effects-list
    >

        <?php foreach (
            $gameplayEffects
            as $effectIndex => $effect
        ): ?>

            <?php
            $effect =
                is_array($effect)
                    ? $effect
                    : [];

            $branches =
                gameplayEffectNormalizeBranches(
                    $effect
                );
            ?>

            <div
                class="builder-tick-effect-row builder-effect-row"
                data-effect-row
                data-effect-index="<?= (int)$effectIndex ?>"
            >

                <div class="builder-tick-effect-header">

                    <label class="builder-tick-effect-target">
                        Target

                        <select
                            name="effects[<?= (int)$effectIndex ?>][target]"
                            data-effect-target
                        >
                            <?php
                            $renderEffectTargetOptions(
                                $effect
                            );
                            ?>
                        </select>
                    </label>


                    <button
                        type="button"
                        class="secondary-button"
                        data-remove-effect
                    >
                        Remove Effect
                    </button>

                </div>


                <div
                    class="builder-tick-result-list"
                    data-effect-branch-list
                >

                    <?php foreach (
                        $branches
                        as $branchIndex => $branch
                    ): ?>

                        <?php
                        $branchName =
                            'effects[' .
                            (int)$effectIndex .
                            '][branches][' .
                            (int)$branchIndex .
                            ']';

                        $isOtherwise =
                            gameplayEffectBranchIsOtherwise(
                                $branch
                            );
                        ?>

                        <div
                            class="builder-tick-result-branch<?= $isOtherwise
                                ? ' is-otherwise'
                                : '' ?>"
                            data-effect-branch
                            data-branch-kind="<?= $isOtherwise
                                ? 'otherwise'
                                : 'conditional' ?>"
                        >

                            <input
                                type="hidden"
                                name="<?= builderEscape(
                                    $branchName
                                ) ?>[kind]"
                                value="<?= $isOtherwise
                                    ? 'otherwise'
                                    : 'conditional' ?>"
                            >


                            <div class="builder-tick-result-heading">

                                <strong>
                                    <?= $isOtherwise
                                        ? 'OTHERWISE'
                                        : 'WHEN' ?>
                                </strong>


                                <div class="builder-tick-result-order">

                                    <?php if (!$isOtherwise): ?>

                                        <button
                                            type="button"
                                            class="secondary-button"
                                            data-move-effect-branch-up
                                            title="Move result up"
                                        >
                                            ↑
                                        </button>

                                        <button
                                            type="button"
                                            class="secondary-button"
                                            data-move-effect-branch-down
                                            title="Move result down"
                                        >
                                            ↓
                                        </button>

                                    <?php endif; ?>


                                    <button
                                        type="button"
                                        class="secondary-button"
                                        data-remove-effect-branch
                                    >
                                        Remove Result
                                    </button>

                                </div>

                            </div>


                            <?php if (!$isOtherwise): ?>

                                <div class="builder-tick-result-condition">

                                    <?php
                                    $conditionEditorNode =
                                        $branch[
                                            'conditions'
                                        ]
                                        ?? null;

                                    $conditionEditorName =
                                        $branchName .
                                        '[conditions]';

                                    $conditionEditorTargets =
                                        $gameplayConditionTargets;

                                    require __DIR__ .
                                        '/condition-editor.php';
                                    ?>

                                </div>


                                <div class="builder-tick-result-then">
                                    <strong>THEN</strong>
                                </div>

                            <?php endif; ?>


                            <?php
                            $renderEffectResultFields(
                                $branch,
                                $branchName
                            );
                            ?>

                        </div>

                    <?php endforeach; ?>

                </div>


                <div class="builder-tick-result-actions">

                    <button
                        type="button"
                        class="secondary-button"
                        data-add-effect-conditional
                    >
                        + Add Conditional Result
                    </button>

                    <button
                        type="button"
                        class="secondary-button"
                        data-add-effect-otherwise
                    >
                        + Add Otherwise
                    </button>

                </div>

            </div>

        <?php endforeach; ?>

    </div>


    <p>
        <button
            type="button"
            class="secondary-button"
            data-add-effect
        >
            + Add Effect
        </button>
    </p>


    <template data-effect-template>

        <div
            class="builder-tick-effect-row builder-effect-row"
            data-effect-row
            data-effect-index="__EFFECT_INDEX__"
        >

            <div class="builder-tick-effect-header">

                <label class="builder-tick-effect-target">
                    Target

                    <select
                        name="effects[__EFFECT_INDEX__][target]"
                        data-effect-target
                    >
                        <?php
                        $renderEffectTargetOptions(
                            []
                        );
                        ?>
                    </select>
                </label>


                <button
                    type="button"
                    class="secondary-button"
                    data-remove-effect
                >
                    Remove Effect
                </button>

            </div>


            <div
                class="builder-tick-result-list"
                data-effect-branch-list
            >

                <div
                    class="builder-tick-result-branch is-otherwise"
                    data-effect-branch
                    data-branch-kind="otherwise"
                >
                    <input
                        type="hidden"
                        name="effects[__EFFECT_INDEX__][branches][0][kind]"
                        value="otherwise"
                    >

                    <div class="builder-tick-result-heading">

                        <strong>OTHERWISE</strong>

                        <div class="builder-tick-result-order">

                            <button
                                type="button"
                                class="secondary-button"
                                data-remove-effect-branch
                            >
                                Remove Result
                            </button>

                        </div>

                    </div>


                    <div class="builder-effect-value-fields">

                        <label>
                            Result

                            <select
                                name="effects[__EFFECT_INDEX__][branches][0][operation]"
                                data-effect-branch-operation
                            >
                                <option value="add">Add</option>
                                <option value="subtract">Subtract</option>
                                <option value="set">Set</option>
                                <option value="none">No Change</option>
                            </select>
                        </label>


                        <label data-effect-value-mode-wrap>
                            Value Type

                            <select
                                name="effects[__EFFECT_INDEX__][branches][0][value_mode]"
                                data-effect-value-mode
                            >
                                <option value="fixed">Fixed</option>
                                <option value="random">Random</option>
                            </select>
                        </label>


                        <label data-effect-fixed-wrap>
                            Value

                            <input
                                type="number"
                                step="any"
                                name="effects[__EFFECT_INDEX__][branches][0][value]"
                            >
                        </label>


                        <div
                            class="builder-effect-random-range"
                            data-effect-random-wrap
                            hidden
                        >
                            <label>
                                Min

                                <input
                                    type="number"
                                    step="any"
                                    name="effects[__EFFECT_INDEX__][branches][0][value_min]"
                                    disabled
                                >
                            </label>

                            <label>
                                Max

                                <input
                                    type="number"
                                    step="any"
                                    name="effects[__EFFECT_INDEX__][branches][0][value_max]"
                                    disabled
                                >
                            </label>
                        </div>

                    </div>

                </div>

            </div>


            <div class="builder-tick-result-actions">

                <button
                    type="button"
                    class="secondary-button"
                    data-add-effect-conditional
                >
                    + Add Conditional Result
                </button>

                <button
                    type="button"
                    class="secondary-button"
                    data-add-effect-otherwise
                    disabled
                >
                    + Add Otherwise
                </button>

            </div>

        </div>

    </template>


    <template data-effect-conditional-template>

        <div
            class="builder-tick-result-branch"
            data-effect-branch
            data-branch-kind="conditional"
        >

            <input
                type="hidden"
                name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][kind]"
                value="conditional"
            >


            <div class="builder-tick-result-heading">

                <strong>WHEN</strong>


                <div class="builder-tick-result-order">

                    <button
                        type="button"
                        class="secondary-button"
                        data-move-effect-branch-up
                        title="Move result up"
                    >
                        ↑
                    </button>

                    <button
                        type="button"
                        class="secondary-button"
                        data-move-effect-branch-down
                        title="Move result down"
                    >
                        ↓
                    </button>

                    <button
                        type="button"
                        class="secondary-button"
                        data-remove-effect-branch
                    >
                        Remove Result
                    </button>

                </div>

            </div>


            <div
                class="builder-tick-result-condition"
                data-new-effect-condition-editor
            ></div>


            <div class="builder-tick-result-then">
                <strong>THEN</strong>
            </div>


            <div class="builder-effect-value-fields">

                <label>
                    Result

                    <select
                        name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][operation]"
                        data-effect-branch-operation
                    >
                        <option value="add">Add</option>
                        <option value="subtract">Subtract</option>
                        <option value="set">Set</option>
                        <option value="none">No Change</option>
                    </select>
                </label>


                <label data-effect-value-mode-wrap>
                    Value Type

                    <select
                        name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][value_mode]"
                        data-effect-value-mode
                    >
                        <option value="fixed">Fixed</option>
                        <option value="random">Random</option>
                    </select>
                </label>


                <label data-effect-fixed-wrap>
                    Value

                    <input
                        type="number"
                        step="any"
                        name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][value]"
                    >
                </label>


                <div
                    class="builder-effect-random-range"
                    data-effect-random-wrap
                    hidden
                >
                    <label>
                        Min

                        <input
                            type="number"
                            step="any"
                            name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][value_min]"
                            disabled
                        >
                    </label>

                    <label>
                        Max

                        <input
                            type="number"
                            step="any"
                            name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][value_max]"
                            disabled
                        >
                    </label>
                </div>

            </div>

        </div>

    </template>


    <template data-effect-otherwise-template>

        <div
            class="builder-tick-result-branch is-otherwise"
            data-effect-branch
            data-branch-kind="otherwise"
        >

            <input
                type="hidden"
                name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][kind]"
                value="otherwise"
            >


            <div class="builder-tick-result-heading">

                <strong>OTHERWISE</strong>


                <div class="builder-tick-result-order">

                    <button
                        type="button"
                        class="secondary-button"
                        data-remove-effect-branch
                    >
                        Remove Result
                    </button>

                </div>

            </div>


            <div class="builder-effect-value-fields">

                <label>
                    Result

                    <select
                        name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][operation]"
                        data-effect-branch-operation
                    >
                        <option value="add">Add</option>
                        <option value="subtract">Subtract</option>
                        <option value="set">Set</option>
                        <option value="none">No Change</option>
                    </select>
                </label>


                <label data-effect-value-mode-wrap>
                    Value Type

                    <select
                        name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][value_mode]"
                        data-effect-value-mode
                    >
                        <option value="fixed">Fixed</option>
                        <option value="random">Random</option>
                    </select>
                </label>


                <label data-effect-fixed-wrap>
                    Value

                    <input
                        type="number"
                        step="any"
                        name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][value]"
                    >
                </label>


                <div
                    class="builder-effect-random-range"
                    data-effect-random-wrap
                    hidden
                >
                    <label>
                        Min

                        <input
                            type="number"
                            step="any"
                            name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][value_min]"
                            disabled
                        >
                    </label>

                    <label>
                        Max

                        <input
                            type="number"
                            step="any"
                            name="effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][value_max]"
                            disabled
                        >
                    </label>
                </div>

            </div>

        </div>

    </template>


    <!-- WAYFARER_DATATYPE_EFFECT_UI_V58 -->
    <script
        type="application/json"
        data-effect-target-catalog-json
    ><?= json_encode(
        $gameplayTargetCatalog,
        JSON_UNESCAPED_SLASHES |
        JSON_UNESCAPED_UNICODE |
        JSON_HEX_TAG |
        JSON_HEX_AMP |
        JSON_HEX_APOS |
        JSON_HEX_QUOT
    ) ?></script>

    <script
        type="application/json"
        data-effect-condition-targets-json
    ><?= json_encode(
        $gameplayConditionTargets,
        JSON_UNESCAPED_SLASHES |
        JSON_UNESCAPED_UNICODE |
        JSON_HEX_TAG |
        JSON_HEX_AMP |
        JSON_HEX_APOS |
        JSON_HEX_QUOT
    ) ?></script>

</section>



==============================================================================
FILE: includes/gameplay/functions.php
==============================================================================

<?php

/* WAYFARER_CONDITION_ENGINE_V26 */
require_once __DIR__ . '/conditions.php';

/*
|--------------------------------------------------------------------------
| Shared Gameplay Functions
|--------------------------------------------------------------------------
|
| WAYFARER_GAMEPLAY_MODULAR_V25
|
| These functions intentionally know nothing about a particular admin page.
| Game and Region Gameplay editors can both use them.
|
*/

function gameplayNumericTraitTargets(
    array $traits,
    string $scope
): array {

    $targets = [];

    foreach ($traits as $trait) {

        if (!is_array($trait)) {
            continue;
        }

        if (
            isset($trait['active']) &&
            !$trait['active']
        ) {
            continue;
        }

        if (($trait['type'] ?? '') !== 'number') {
            continue;
        }

        $traitId =
            trim(
                (string)(
                    $trait['id']
                    ?? ''
                )
            );

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

        $targets[] = [
            'scope' => $scope,
            'id'    => $traitId,
            'name'  => (string)(
                $trait['name']
                ?? $traitId
            ),
        ];
    }

    return $targets;
}


function gameplayTickEffectAllowedTargets(
    array $gameTraits,
    array $scopeTraits = [],
    string $scope = '',
    bool $allowLinearNavigation = false
): array {

    $allowedTargets = [];

    if ($allowLinearNavigation) {

        $allowedTargets[
            'navigation:position'
        ] = [
            'target_scope' => 'navigation',
            'target_type'  => 'position',
            'target_id'    => 'position',
        ];
    }

    foreach (
        gameplayNumericTraitTargets(
            $gameTraits,
            'game'
        )
        as $target
    ) {

        $key =
            'game:' .
            $target['id'];

        $allowedTargets[$key] = [
            'target_scope' => 'game',
            'target_type'  => 'trait',
            'target_id'    => $target['id'],
        ];
    }

    if ($scope !== '') {

        foreach (
            gameplayNumericTraitTargets(
                $scopeTraits,
                $scope
            )
            as $target
        ) {

            $key =
                $scope .
                ':' .
                $target['id'];

            $allowedTargets[$key] = [
                'target_scope' => $scope,
                'target_type'  => 'trait',
                'target_id'    => $target['id'],
            ];
        }
    }

    return $allowedTargets;
}


/*
|--------------------------------------------------------------------------
| Tick Effect result branches
|--------------------------------------------------------------------------
|
| WAYFARER_TICK_EFFECT_BRANCHES_V28
|
| Canonical shape:
|
| {
|   "target_scope": "game",
|   "target_type": "trait",
|   "target_id": "water",
|   "branches": [
|     {
|       "conditions": { ... },
|       "operation": "subtract",
|       "value": 2
|     },
|     {
|       "conditions": null,
|       "operation": "subtract",
|       "value": 1
|     }
|   ]
| }
|
| A branch with conditions === null is OTHERWISE.
| Branches are ordered. Runtime will later use first-match-wins semantics.
|
*/

function gameplayTickEffectNormalizeBranches(
    array $effect
): array {

    if (
        isset(
            $effect['branches']
        ) &&
        is_array(
            $effect['branches']
        )
    ) {

        $branches = [];

        foreach (
            $effect['branches']
            as $branch
        ) {

            if (!is_array($branch)) {
                continue;
            }

            $operation =
                (string)(
                    $branch['operation']
                    ?? 'add'
                );

            $normalized = [
                'conditions' =>
                    $branch['conditions']
                    ?? null,
                'operation' =>
                    $operation,
            ];

            if ($operation !== 'none') {
                $valueMode =
                    strtolower(
                        trim(
                            (string)(
                                $branch['value_mode']
                                ?? 'fixed'
                            )
                        )
                    );

                if ($valueMode !== 'random') {
                    $valueMode = 'fixed';
                }

                $normalized['value_mode'] =
                    $valueMode;

                if ($valueMode === 'random') {
                    $normalized['value_min'] =
                        $branch['value_min']
                        ?? '';

                    $normalized['value_max'] =
                        $branch['value_max']
                        ?? '';
                } else {
                    $normalized['value'] =
                        $branch['value']
                        ?? '';
                }
            }

            $branches[] =
                $normalized;
        }

        return $branches;
    }


    /*
     * Legacy v27 single-result effect becomes one branch.
     */
    if (
        array_key_exists('operation', $effect) ||
        array_key_exists('value', $effect) ||
        array_key_exists('value_mode', $effect) ||
        array_key_exists('value_min', $effect) ||
        array_key_exists('value_max', $effect) ||
        array_key_exists('conditions', $effect)
    ) {

        $operation =
            (string)(
                $effect['operation']
                ?? 'add'
            );

        $branch = [
            'conditions' =>
                $effect['conditions']
                ?? null,
            'operation' =>
                $operation,
        ];

        if ($operation !== 'none') {
            $valueMode =
                strtolower(
                    trim(
                        (string)(
                            $effect['value_mode']
                            ?? 'fixed'
                        )
                    )
                );

            if ($valueMode !== 'random') {
                $valueMode = 'fixed';
            }

            $branch['value_mode'] =
                $valueMode;

            if ($valueMode === 'random') {
                $branch['value_min'] =
                    $effect['value_min']
                    ?? '';

                $branch['value_max'] =
                    $effect['value_max']
                    ?? '';
            } else {
                $branch['value'] =
                    $effect['value']
                    ?? '';
            }
        }

        return [
            $branch
        ];
    }

    return [];
}


function gameplayTickEffectBranchIsOtherwise(
    array $branch
): bool {

    return
        !isset(
            $branch['conditions']
        ) ||
        $branch['conditions'] === null ||
        $branch['conditions'] === [];
}


function gameplayTickEffectBranchOperation(
    array $branch
): string {

    return
        (string)(
            $branch['operation']
            ?? 'add'
        );
}


function gameplayTickEffectBranchValue(
    array $branch
) {
    return
        $branch['value']
        ?? '';
}


function gameplayTickEffectBranchValueMode(
    array $branch
): string {

    return
        strtolower(
            trim(
                (string)(
                    $branch['value_mode']
                    ?? 'fixed'
                )
            )
        ) === 'random'
            ? 'random'
            : 'fixed';
}


function gameplayTickEffectBranchMin(
    array $branch
) {

    return
        $branch['value_min']
        ?? '';
}


function gameplayTickEffectBranchMax(
    array $branch
) {

    return
        $branch['value_max']
        ?? '';
}


/*
|--------------------------------------------------------------------------
| One-time Effects
| WAYFARER_ONE_TIME_EFFECTS_V42
| WAYFARER_GENERALIZED_EFFECTS_V43
|--------------------------------------------------------------------------
|
| Effects use ordered first-match-wins result branches just like Tick Effects,
| but execute only when their containing object/event triggers.
|
| A result may use:
|   - fixed value
|   - random inclusive Min-Max value
|
*/

function gameplayEffectAllowedTargets(
    array $gameTraits,
    array $scopeTraits = [],
    string $scope = '',
    bool $allowLinearNavigation = false
): array {

    return
        gameplayTickEffectAllowedTargets(
            $gameTraits,
            $scopeTraits,
            $scope,
            $allowLinearNavigation
        );
}


function gameplayEffectNormalizeBranches(
    array $effect
): array {

    if (
        array_key_exists(
            'branches',
            $effect
        )
    ) {

        if (
            !is_array(
                $effect['branches']
            )
        ) {
            return [];
        }

        $branches = [];

        foreach (
            $effect['branches']
            as $branch
        ) {

            if (!is_array($branch)) {
                continue;
            }

            $operation =
                strtolower(
                    trim(
                        (string)(
                            $branch['operation']
                            ?? 'add'
                        )
                    )
                );

            $normalized = [
                'conditions' =>
                    $branch['conditions']
                    ?? null,

                'operation' =>
                    $operation,
            ];


            if ($operation !== 'none') {

                $valueMode =
                    strtolower(
                        trim(
                            (string)(
                                $branch['value_mode']
                                ?? 'fixed'
                            )
                        )
                    );

                if (
                    $valueMode !== 'random'
                ) {
                    $valueMode =
                        'fixed';
                }

                $normalized['value_mode'] =
                    $valueMode;


                if ($valueMode === 'random') {

                    $normalized['value_min'] =
                        $branch['value_min']
                        ?? '';

                    $normalized['value_max'] =
                        $branch['value_max']
                        ?? '';

                } else {

                    $normalized['value'] =
                        $branch['value']
                        ?? '';
                }
            }


            $branches[] =
                $normalized;
        }

        return $branches;
    }


    /*
     * v42 legacy one-result Effect becomes a single OTHERWISE result.
     */
    if (
        array_key_exists(
            'operation',
            $effect
        ) ||
        array_key_exists(
            'value',
            $effect
        ) ||
        array_key_exists(
            'value_mode',
            $effect
        ) ||
        array_key_exists(
            'value_min',
            $effect
        ) ||
        array_key_exists(
            'value_max',
            $effect
        )
    ) {

        $operation =
            strtolower(
                trim(
                    (string)(
                        $effect['operation']
                        ?? 'add'
                    )
                )
            );

        $branch = [
            'conditions' =>
                null,

            'operation' =>
                $operation,
        ];


        if ($operation !== 'none') {

            $valueMode =
                strtolower(
                    trim(
                        (string)(
                            $effect['value_mode']
                            ?? 'fixed'
                        )
                    )
                );

            if ($valueMode !== 'random') {
                $valueMode =
                    'fixed';
            }

            $branch['value_mode'] =
                $valueMode;


            if ($valueMode === 'random') {

                $branch['value_min'] =
                    $effect['value_min']
                    ?? '';

                $branch['value_max'] =
                    $effect['value_max']
                    ?? '';

            } else {

                $branch['value'] =
                    $effect['value']
                    ?? '';
            }
        }


        return [
            $branch
        ];
    }


    return [];
}


function gameplayEffectBranchIsOtherwise(
    array $branch
): bool {

    return
        !isset(
            $branch['conditions']
        ) ||
        $branch['conditions'] ===
            null ||
        $branch['conditions'] ===
            [];
}


function gameplayEffectBranchOperation(
    array $branch
): string {

    return
        strtolower(
            trim(
                (string)(
                    $branch['operation']
                    ?? 'add'
                )
            )
        );
}


function gameplayEffectBranchValueMode(
    array $branch
): string {

    return
        strtolower(
            trim(
                (string)(
                    $branch['value_mode']
                    ?? 'fixed'
                )
            )
        ) ===
            'random'
            ? 'random'
            : 'fixed';
}


function gameplayEffectBranchValue(
    array $branch
) {

    return
        $branch['value']
        ?? '';
}


function gameplayEffectBranchMin(
    array $branch
) {

    return
        $branch['value_min']
        ?? '';
}


function gameplayEffectBranchMax(
    array $branch
) {

    return
        $branch['value_max']
        ?? '';
}


function gameplayEffectNormalizeNumber(
    string $value
) {

    if (
        filter_var(
            $value,
            FILTER_VALIDATE_INT
        ) !== false
    ) {
        return
            (int)$value;
    }

    return
        (float)$value;
}


function gameplayBuildEffectsFromPost(
    array $allowedTargets,
    array $postedEffects,
    array $allowedConditionTargets = []
): array {

    $effects = [];


    foreach (
        array_values(
            $postedEffects
        )
        as $postedEffect
    ) {

        if (!is_array($postedEffect)) {
            continue;
        }


        $target =
            trim(
                (string)(
                    $postedEffect['target']
                    ?? ''
                )
            );


        $postedBranches =
            isset(
                $postedEffect['branches']
            ) &&
            is_array(
                $postedEffect['branches']
            )
                ? array_values(
                    $postedEffect['branches']
                )
                : [];


        /*
         * Completely blank newly-added Effect.
         */
        if (
            $target === '' &&
            $postedBranches === []
        ) {
            continue;
        }


        if (
            $target === '' ||
            !isset(
                $allowedTargets[$target]
            )
        ) {

            return [
                'effects' => [],
                'error' =>
                    'Each Effect must use a valid target.',
            ];
        }


        /* WAYFARER_DATATYPE_EFFECT_VALIDATION_V58 */
        $targetDefinition =
            $allowedTargets[$target];

        $targetDataType =
            strtolower(
                trim(
                    (string)(
                        $targetDefinition['data_type']
                        ?? $targetDefinition['trait_type']
                        ?? 'text'
                    )
                )
            );

        if ($targetDataType === 'binary') {
            $targetDataType = 'boolean';
        }

        $targetAllowedOperations =
            isset($targetDefinition['effect_operations']) &&
            is_array($targetDefinition['effect_operations'])
                ? array_values($targetDefinition['effect_operations'])
                : (
                    $targetDataType === 'number'
                        ? ['set', 'add', 'subtract']
                        : ['set']
                );

        $targetSupportsRandom =
            array_key_exists('supports_random', $targetDefinition)
                ? !empty($targetDefinition['supports_random'])
                : $targetDataType === 'number';

        $branches =
            [];

        $otherwiseSeen =
            false;


        foreach (
            $postedBranches
            as $branchIndex => $postedBranch
        ) {

            if (!is_array($postedBranch)) {
                continue;
            }


            $kind =
                strtolower(
                    trim(
                        (string)(
                            $postedBranch['kind']
                            ?? ''
                        )
                    )
                );


            if (
                $kind !== 'conditional' &&
                $kind !== 'otherwise'
            ) {

                /*
                 * Existing server-rendered branch structures can be inferred
                 * safely from whether conditions were supplied.
                 */
                $kind =
                    isset(
                        $postedBranch['conditions']
                    ) &&
                    $postedBranch['conditions'] !==
                        []
                        ? 'conditional'
                        : 'otherwise';
            }


            if ($kind === 'otherwise') {

                if ($otherwiseSeen) {

                    return [
                        'effects' => [],
                        'error' =>
                            'An Effect may have only one OTHERWISE result.',
                    ];
                }

                $otherwiseSeen =
                    true;

                $conditions =
                    null;

            } else {

                if ($otherwiseSeen) {

                    return [
                        'effects' => [],
                        'error' =>
                            'Conditional Effect results must appear before OTHERWISE.',
                    ];
                }


                $conditionResult =
                    gameplayBuildConditionNodeFromPost(
                        $postedBranch['conditions']
                            ?? null,
                        $allowedConditionTargets
                    );


                if (
                    $conditionResult['error'] !==
                    ''
                ) {

                    return [
                        'effects' => [],
                        'error' =>
                            $conditionResult[
                                'error'
                            ],
                    ];
                }


                if (
                    $conditionResult['node'] ===
                    null
                ) {

                    return [
                        'effects' => [],
                        'error' =>
                            'Each conditional Effect result must have at least one condition.',
                    ];
                }


                $conditions =
                    $conditionResult[
                        'node'
                    ];
            }


            $operation =
                strtolower(
                    trim(
                        (string)(
                            $postedBranch['operation']
                            ?? ''
                        )
                    )
                );


            if (
                $operation !== 'none' &&
                !in_array(
                    $operation,
                    $targetAllowedOperations,
                    true
                )
            ) {

                return [
                    'effects' => [],
                    'error' =>
                        'That Effect operation is not valid for the selected target.',
                ];
            }


            $storedBranch = [
                'conditions' =>
                    $conditions,

                'operation' =>
                    $operation,
            ];


            if ($operation !== 'none') {

                $valueMode =
                    strtolower(
                        trim(
                            (string)(
                                $postedBranch[
                                    'value_mode'
                                ]
                                ?? 'fixed'
                            )
                        )
                    );


                if (
                    !in_array(
                        $valueMode,
                        [
                            'fixed',
                            'random',
                        ],
                        true
                    ) ||
                    (
                        $valueMode === 'random' &&
                        !$targetSupportsRandom
                    )
                ) {

                    return [
                        'effects' => [],
                        'error' =>
                            $targetSupportsRandom
                                ? 'Effect value type must be Fixed or Random.'
                                : 'Random values are only available for numeric targets.',
                    ];
                }


                $storedBranch[
                    'value_mode'
                ] =
                    $valueMode;


                if (
                    $valueMode ===
                    'random'
                ) {

                    $minRaw =
                        trim(
                            (string)(
                                $postedBranch[
                                    'value_min'
                                ]
                                ?? ''
                            )
                        );

                    $maxRaw =
                        trim(
                            (string)(
                                $postedBranch[
                                    'value_max'
                                ]
                                ?? ''
                            )
                        );


                    if (
                        $minRaw === '' ||
                        $maxRaw === '' ||
                        !is_numeric(
                            $minRaw
                        ) ||
                        !is_numeric(
                            $maxRaw
                        )
                    ) {

                        return [
                            'effects' => [],
                            'error' =>
                                'Random Effect results require numeric Min and Max values.',
                        ];
                    }


                    $minimum =
                        gameplayEffectNormalizeNumber(
                            $minRaw
                        );

                    $maximum =
                        gameplayEffectNormalizeNumber(
                            $maxRaw
                        );


                    if (
                        (float)$minimum >
                        (float)$maximum
                    ) {

                        return [
                            'effects' => [],
                            'error' =>
                                'Random Effect Min cannot be greater than Max.',
                        ];
                    }


                    $storedBranch[
                        'value_min'
                    ] =
                        $minimum;

                    $storedBranch[
                        'value_max'
                    ] =
                        $maximum;


                } else {

                    $valueRaw =
                        trim(
                            (string)(
                                $postedBranch[
                                    'value'
                                ]
                                ?? ''
                            )
                        );


                    /* WAYFARER_GENERAL_EFFECT_SCALAR_VALUES_V56 */
                    if (
                        $targetDataType === 'number' &&
                        (
                            $valueRaw === '' ||
                            !is_numeric($valueRaw)
                        )
                    ) {
                        return [
                            'effects' => [],
                            'error' =>
                                'Numeric Effect results require a numeric value.',
                        ];
                    }

                    if (
                        $targetDataType === 'boolean' &&
                        !in_array(
                            strtolower($valueRaw),
                            ['0', '1', 'true', 'false'],
                            true
                        )
                    ) {
                        return [
                            'effects' => [],
                            'error' =>
                                'Boolean Effect results must use one of the available values.',
                        ];
                    }

                    if ($targetDataType === 'boolean') {
                        $lowerValue = strtolower($valueRaw);
                        $storedBranch['value'] =
                            ($lowerValue === '1' || $lowerValue === 'true')
                                ? 1
                                : 0;
                    } else {
                        $storedBranch['value'] =
                            is_numeric($valueRaw)
                                ? gameplayEffectNormalizeNumber(
                                    $valueRaw
                                )
                                : $valueRaw;
                    }
                }
            }


            $branches[] =
                $storedBranch;
        }


        if ($branches === []) {

            return [
                'effects' => [],
                'error' =>
                    'Each Effect must have at least one result.',
            ];
        }


        /*
         * Keep a top-level compatibility projection. v43 runtime reads the
         * branches directly; this merely keeps the canonical target/effect
         * record recognizable to older tooling.
         */
        $compatibilityBranch =
            $branches[0];

        foreach (
            $branches
            as $candidateBranch
        ) {

            if (
                gameplayEffectBranchIsOtherwise(
                    $candidateBranch
                )
            ) {

                $compatibilityBranch =
                    $candidateBranch;

                break;
            }
        }


        $targetDefinition =
            $allowedTargets[
                $target
            ];


        $storedEffect = [
            'target_scope' =>
                $targetDefinition[
                    'target_scope'
                ],

            'target_type' =>
                $targetDefinition[
                    'target_type'
                ],

            'target_id' =>
                $targetDefinition[
                    'target_id'
                ],

            'operation' =>
                (string)(
                    $compatibilityBranch[
                        'operation'
                    ]
                    ?? 'none'
                ),

            'branches' =>
                $branches,
        ];


        $compatibilityOperation =
            (string)(
                $compatibilityBranch[
                    'operation'
                ]
                ?? 'none'
            );


        if (
            $compatibilityOperation !==
            'none'
        ) {

            $compatibilityMode =
                gameplayEffectBranchValueMode(
                    $compatibilityBranch
                );

            $storedEffect[
                'value_mode'
            ] =
                $compatibilityMode;


            if (
                $compatibilityMode ===
                'random'
            ) {

                $storedEffect[
                    'value_min'
                ] =
                    $compatibilityBranch[
                        'value_min'
                    ];

                $storedEffect[
                    'value_max'
                ] =
                    $compatibilityBranch[
                        'value_max'
                    ];

            } else {

                $storedEffect[
                    'value'
                ] =
                    $compatibilityBranch[
                        'value'
                    ];
            }
        }


        /* WAYFARER_EFFECT_TARGET_METADATA_V56 */
        if (!empty($targetDefinition['target_system_key'])) {
            $storedEffect['target_system_key'] =
                (string)$targetDefinition['target_system_key'];
        }
        $effects[] =
            $storedEffect;
    }


    return [
        'effects' =>
            $effects,

        'error' =>
            '',
    ];
}


function gameplayEffectSelected(
    array $effect,
    string $scope,
    string $targetId
): bool {

    return
        (string)(
            $effect['target_scope']
            ?? ''
        ) ===
            $scope
        &&
        (string)(
            $effect['target_id']
            ?? ''
        ) ===
            $targetId;
}
function gameplayBuildTickEffectsFromPost(
    array $allowedTargets,
    array $postedEffects,
    array $allowedConditionTargets = []
): array {

    $effects = [];

    foreach (
        $postedEffects
        as $postedEffect
    ) {

        if (!is_array($postedEffect)) {
            continue;
        }

        $target =
            trim(
                (string)(
                    $postedEffect['target']
                    ?? ''
                )
            );


        /*
         * v28 posts branches. Keep a compatibility path for a cached v27
         * page that still submits operation/value/conditions at effect level.
         */
        if (
            isset(
                $postedEffect['branches']
            ) &&
            is_array(
                $postedEffect['branches']
            )
        ) {

            $postedBranches =
                array_values(
                    $postedEffect['branches']
                );

        } elseif (
            array_key_exists(
                'operation',
                $postedEffect
            ) ||
            array_key_exists(
                'value',
                $postedEffect
            ) ||
            array_key_exists(
                'conditions',
                $postedEffect
            )
        ) {

            $postedBranches = [
                [
                    'kind' =>
                        !empty(
                            $postedEffect['conditions']['children']
                        )
                            ? 'conditional'
                            : 'otherwise',
                    'conditions' =>
                        $postedEffect['conditions']
                        ?? null,
                    'operation' =>
                        $postedEffect['operation']
                        ?? '',
                    'value' =>
                        $postedEffect['value']
                        ?? '',
                ]
            ];

        } else {
            $postedBranches = [];
        }


        /*
         * Completely empty newly-added row: ignore it.
         */
        if (
            $target === '' &&
            $postedBranches === []
        ) {
            continue;
        }


        if (
            $target === '' ||
            !isset(
                $allowedTargets[$target]
            )
        ) {
            return [
                'effects' => [],
                'error' =>
                    'Each Tick Effect must use a valid target.',
            ];
        }


        if ($postedBranches === []) {
            return [
                'effects' => [],
                'error' =>
                    'Each Tick Effect must have at least one result.',
            ];
        }


        /* WAYFARER_DATATYPE_TICK_EFFECT_VALIDATION_V58 */
        $targetDefinition =
            $allowedTargets[$target];

        $targetDataType =
            strtolower(
                trim(
                    (string)(
                        $targetDefinition['data_type']
                        ?? $targetDefinition['trait_type']
                        ?? 'text'
                    )
                )
            );

        if ($targetDataType === 'binary') {
            $targetDataType = 'boolean';
        }

        $targetAllowedOperations =
            isset($targetDefinition['effect_operations']) &&
            is_array($targetDefinition['effect_operations'])
                ? array_values($targetDefinition['effect_operations'])
                : (
                    $targetDataType === 'number'
                        ? ['set', 'add', 'subtract']
                        : ['set']
                );

        $targetSupportsRandom =
            array_key_exists('supports_random', $targetDefinition)
                ? !empty($targetDefinition['supports_random'])
                : $targetDataType === 'number';


        $branches = [];
        $otherwiseSeen = false;

        foreach (
            $postedBranches
            as $branchIndex => $postedBranch
        ) {

            if (!is_array($postedBranch)) {
                continue;
            }

            $kind =
                trim(
                    (string)(
                        $postedBranch['kind']
                        ?? 'conditional'
                    )
                );

            if (
                !in_array(
                    $kind,
                    [
                        'conditional',
                        'otherwise',
                    ],
                    true
                )
            ) {
                return [
                    'effects' => [],
                    'error' =>
                        'Invalid Tick Effect result type.',
                ];
            }


            if ($otherwiseSeen) {
                return [
                    'effects' => [],
                    'error' =>
                        'Otherwise must be the final result in a Tick Effect.',
                ];
            }


            $conditions = null;

            if ($kind === 'otherwise') {

                if ($otherwiseSeen) {
                    return [
                        'effects' => [],
                        'error' =>
                            'A Tick Effect can have only one Otherwise result.',
                    ];
                }

                $otherwiseSeen = true;

            } else {

                $conditionResult =
                    gameplayBuildConditionNodeFromPost(
                        $postedBranch['conditions']
                            ?? null,
                        $allowedConditionTargets
                    );

                if (
                    $conditionResult['error'] !== ''
                ) {
                    return [
                        'effects' => [],
                        'error' =>
                            $conditionResult['error'],
                    ];
                }

                if (
                    $conditionResult['node'] === null
                ) {
                    return [
                        'effects' => [],
                        'error' =>
                            'Each conditional Tick Effect result must have at least one condition.',
                    ];
                }

                $conditions =
                    $conditionResult['node'];
            }


            $operation =
                trim(
                    (string)(
                        $postedBranch['operation']
                        ?? ''
                    )
                );

            if (
                $operation !== 'none' &&
                !in_array(
                    $operation,
                    $targetAllowedOperations,
                    true
                )
            ) {
                return [
                    'effects' => [],
                    'error' =>
                        'That Tick Effect operation is not valid for the selected target.',
                ];
            }


            $storedBranch = [
                'conditions' =>
                    $conditions,
                'operation' =>
                    $operation,
            ];


            if ($operation !== 'none') {

                $valueMode =
                    strtolower(
                        trim(
                            (string)(
                                $postedBranch['value_mode']
                                ?? 'fixed'
                            )
                        )
                    );

                if (
                    !in_array(
                        $valueMode,
                        ['fixed', 'random'],
                        true
                    ) ||
                    (
                        $valueMode === 'random' &&
                        !$targetSupportsRandom
                    )
                ) {
                    return [
                        'effects' => [],
                        'error' =>
                            $targetSupportsRandom
                                ? 'Tick Effect value type must be Fixed or Random.'
                                : 'Random values are only available for numeric targets.',
                    ];
                }

                $storedBranch['value_mode'] =
                    $valueMode;

                if ($valueMode === 'random') {
                    $minRaw =
                        trim(
                            (string)(
                                $postedBranch['value_min']
                                ?? ''
                            )
                        );

                    $maxRaw =
                        trim(
                            (string)(
                                $postedBranch['value_max']
                                ?? ''
                            )
                        );

                    if (
                        $minRaw === '' ||
                        $maxRaw === '' ||
                        !is_numeric($minRaw) ||
                        !is_numeric($maxRaw)
                    ) {
                        return [
                            'effects' => [],
                            'error' =>
                                'Random Tick Effect results require numeric Min and Max values.',
                        ];
                    }

                    $minimum =
                        gameplayEffectNormalizeNumber(
                            $minRaw
                        );

                    $maximum =
                        gameplayEffectNormalizeNumber(
                            $maxRaw
                        );

                    if ((float)$minimum > (float)$maximum) {
                        return [
                            'effects' => [],
                            'error' =>
                                'Random Tick Effect Min cannot be greater than Max.',
                        ];
                    }

                    $storedBranch['value_min'] =
                        $minimum;

                    $storedBranch['value_max'] =
                        $maximum;

                } else {
                    $valueRaw =
                        trim(
                            (string)(
                                $postedBranch['value']
                                ?? ''
                            )
                        );

                    if (
                        $targetDataType === 'number' &&
                        (
                            $valueRaw === '' ||
                            !is_numeric($valueRaw)
                        )
                    ) {
                        return [
                            'effects' => [],
                            'error' =>
                                'Numeric Tick Effect results require a numeric value.',
                        ];
                    }

                    if (
                        $targetDataType === 'boolean' &&
                        !in_array(
                            strtolower($valueRaw),
                            ['0', '1', 'true', 'false'],
                            true
                        )
                    ) {
                        return [
                            'effects' => [],
                            'error' =>
                                'Boolean Tick Effect results must use one of the available values.',
                        ];
                    }

                    if ($targetDataType === 'boolean') {
                        $lowerValue = strtolower($valueRaw);
                        $storedBranch['value'] =
                            ($lowerValue === '1' || $lowerValue === 'true')
                                ? 1
                                : 0;
                    } else {
                        $storedBranch['value'] =
                            is_numeric($valueRaw)
                                ? gameplayEffectNormalizeNumber(
                                    $valueRaw
                                )
                                : $valueRaw;
                    }
                }
            }


            $branches[] =
                $storedBranch;
        }


        if ($branches === []) {
            return [
                'effects' => [],
                'error' =>
                    'Each Tick Effect must have at least one result.',
            ];
        }


        /*
         * Keep a legacy top-level projection until runtime is upgraded.
         * If an OTHERWISE branch exists, it is the safest representation of
         * the current base behavior. Otherwise use the first branch, matching
         * the pre-v28 single-result behavior.
         *
         * "No Change" projects as Add 0 because the old runtime does not know
         * the v28 "none" operation yet.
         */
        $compatibilityBranch =
            $branches[0];

        foreach ($branches as $candidateBranch) {

            if (
                gameplayTickEffectBranchIsOtherwise(
                    $candidateBranch
                )
            ) {
                $compatibilityBranch =
                    $candidateBranch;
                break;
            }
        }

        $compatibilityOperation =
            (string)(
                $compatibilityBranch['operation']
                ?? 'add'
            );

        $storedEffect = [
            'target_scope' =>
                $targetDefinition['target_scope'],

            'target_type' =>
                $targetDefinition['target_type'],

            'target_id' =>
                $targetDefinition['target_id'],

            'operation' =>
                $compatibilityOperation === 'none'
                    ? 'add'
                    : $compatibilityOperation,

            'value' =>
                $compatibilityOperation === 'none'
                    ? 0
                    : (
                        $compatibilityBranch['value']
                        ?? 0
                    ),

            'branches' =>
                $branches,
        ];

        if (
            $compatibilityOperation !== 'none' &&
            ($compatibilityBranch['value_mode'] ?? 'fixed') === 'random'
        ) {
            $storedEffect['value_mode'] = 'random';
            $storedEffect['value_min'] =
                $compatibilityBranch['value_min'] ?? 0;
            $storedEffect['value_max'] =
                $compatibilityBranch['value_max'] ?? 0;
        }

        if (
            !gameplayTickEffectBranchIsOtherwise(
                $compatibilityBranch
            )
        ) {
            $storedEffect['conditions'] =
                $compatibilityBranch['conditions'];
        }

        $effects[] =
            $storedEffect;
    }


    return [
        'effects' => $effects,
        'error' => '',
    ];
}

function gameplayTickEffectSelected(
    array $effect,
    string $scope,
    string $targetId
): bool {

    if (
        isset($effect['target_scope']) ||
        isset($effect['target_id'])
    ) {
        return
            (string)(
                $effect['target_scope']
                ?? ''
            ) === $scope
            &&
            (string)(
                $effect['target_id']
                ?? ''
            ) === $targetId;
    }

    return
        (string)(
            $effect['target']
            ?? ''
        ) ===
        $scope .
        ':' .
        $targetId;
}


function gameplayTickEffectValue(
    array $effect
) {
    return
        $effect['value']
        ?? '';
}


function gameplayTickEffectOperation(
    array $effect
): string {
    return
        (string)(
            $effect['operation']
            ?? 'add'
        );
}

/*
|--------------------------------------------------------------------------
| Shared condition authoring support
|--------------------------------------------------------------------------
|
| WAYFARER_CONDITION_EDITOR_V27
|
*/

/*
|--------------------------------------------------------------------------
| Universal Runtime-State Targets
| WAYFARER_UNIVERSAL_RUNTIME_TARGETS_V56
|--------------------------------------------------------------------------
|
| Every Condition and general Effect editor should see the same addressable
| runtime state. Authoring metadata (min/max, display flags, type declarations,
| visibility rules, etc.) is intentionally NOT exposed as a target.
|
*/

function gameplayRuntimeStateDecodeConfig($raw): array
{
    if (is_array($raw)) {
        return $raw;
    }

    if ($raw === null || $raw === '') {
        return [];
    }

    $decoded =
        json_decode(
            (string)$raw,
            true
        );

    return is_array($decoded)
        ? $decoded
        : [];
}


function gameplayRuntimeStateAddTraitTarget(
    array &$targets,
    string $scope,
    string $group,
    string $ownerLabel,
    array $trait,
    ?string $displayName = null,
    ?string $systemKey = null
): void {

    if (
        array_key_exists('active', $trait) &&
        !$trait['active']
    ) {
        return;
    }

    $traitId =
        trim(
            (string)(
                $trait['id']
                ?? $trait['system_key']
                ?? ''
            )
        );

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

    $traitName =
        trim(
            (string)(
                $displayName
                ?? $trait['name']
                ?? $traitId
            )
        );

    if ($traitName === '') {
        $traitName =
            $traitId;
    }

    $key =
        $scope .
        ':trait:' .
        $traitId;

    /* WAYFARER_TARGET_METADATA_V58 */
    $traitType =
        strtolower(
            trim(
                (string)(
                    $trait['type']
                    ?? 'text'
                )
            )
        );

    $dataType =
        in_array(
            $traitType,
            ['boolean', 'binary'],
            true
        )
            ? 'boolean'
            : $traitType;

    $semanticType =
        $systemKey === 'quantity'
            ? 'item_quantity'
            : (
                $systemKey === 'party_member'
                    ? 'party_membership'
                    : 'trait'
            );

    $helper =
        $semanticType === 'party_membership'
            ? '1 = Joined / 0 = Not Joined'
            : (
                $dataType === 'boolean'
                    ? '1 = True / 0 = False'
                    : (
                        $dataType === 'number'
                            ? 'Number'
                            : ucfirst($dataType)
                    )
            );

    $conditionOperators =
        $dataType === 'number'
            ? wayfarerConditionOperators()
            : [
                'equals',
                'not_equals',
            ];

    $effectOperations =
        $dataType === 'number'
            ? [
                'set',
                'add',
                'subtract',
            ]
            : [
                'set',
            ];

    $targets[$key] = [
        'scope' =>
            $scope,
        'target_scope' =>
            $scope,
        'target_type' =>
            'trait',
        'target_id' =>
            $traitId,
        'trait_type' =>
            $traitType,
        'data_type' =>
            $dataType,
        'semantic_type' =>
            $semanticType,
        'helper' =>
            $helper,
        'condition_operators' =>
            $conditionOperators,
        'effect_operations' =>
            $effectOperations,
        'supports_random' =>
            $dataType === 'number',
        'group' =>
            $group,
        'label' =>
            $ownerLabel .
            ' → ' .
            $traitName,
    ];

    if ($dataType === 'boolean') {
        $targets[$key]['value_options'] =
            $semanticType === 'party_membership'
                ? [
                    '0' => 'Not Joined',
                    '1' => 'Joined',
                ]
                : [
                    '0' => 'False',
                    '1' => 'True',
                ];
    }

    if ($systemKey !== null && $systemKey !== '') {
        $targets[$key]['target_system_key'] =
            $systemKey;
    }
}


/*
|--------------------------------------------------------------------------
| Party-member Trait catalog
| WAYFARER_PARTY_TARGETS_V85
|--------------------------------------------------------------------------
|
| Player Traits and authored Character Entity Traits may represent the same
| logical per-person property (for example, Health). Party-level authoring
| addresses that property by normalized name so one Effect can operate across
| the current party without exposing runtime player-slot numbers.
|
*/

function gameplayPartyTraitNormalizeName(
    string $value
): string {
    $value =
        trim(
            preg_replace(
                '/\\s+/u',
                ' ',
                $value
            ) ?? $value
        );

    if (function_exists('mb_strtolower')) {
        return mb_strtolower(
            $value,
            'UTF-8'
        );
    }

    return strtolower($value);
}


function gameplayPartyTraitTargetId(
    string $traitName
): string {
    return
        'party_name_' .
        bin2hex(
            gameplayPartyTraitNormalizeName(
                $traitName
            )
        );
}


function gameplayPartyTraitCatalog(
    PDO $pdo,
    int $gameId,
    ?array $playerTraitsOverride = null
): array {
    if ($gameId <= 0) {
        return [];
    }

    $catalog = [];

    $append =
        static function (
            array &$catalog,
            array $trait
        ): void {
            if (
                !is_array($trait) ||
                !empty($trait['system']) ||
                (
                    array_key_exists('active', $trait) &&
                    !$trait['active']
                )
            ) {
                return;
            }

            $name =
                trim(
                    (string)(
                        $trait['name']
                        ?? ''
                    )
                );

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

            $type =
                strtolower(
                    trim(
                        (string)(
                            $trait['type']
                            ?? 'text'
                        )
                    )
                );

            if ($type === 'binary') {
                $type = 'boolean';
            }

            if (
                !in_array(
                    $type,
                    ['number', 'boolean'],
                    true
                )
            ) {
                return;
            }

            $normalized =
                gameplayPartyTraitNormalizeName(
                    $name
                );

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

            if (!isset($catalog[$normalized])) {
                $catalog[$normalized] = [
                    'name' => $name,
                    'data_type' => $type,
                    'conflict' => false,
                ];
                return;
            }

            if (
                (string)$catalog[$normalized]['data_type'] !==
                $type
            ) {
                $catalog[$normalized]['conflict'] = true;
            }
        };

    if ($playerTraitsOverride === null) {
        $stmt =
            $pdo->prepare(
                'SELECT config FROM wf_games WHERE id = ? LIMIT 1'
            );
        $stmt->execute([$gameId]);
        $raw = $stmt->fetchColumn();
        $config =
            $raw === false
                ? []
                : gameplayRuntimeStateDecodeConfig(
                    $raw
                );
        $playerTraits =
            isset($config['player_traits']) &&
            is_array($config['player_traits'])
                ? $config['player_traits']
                : [];
    } else {
        $playerTraits =
            $playerTraitsOverride;
    }

    foreach ($playerTraits as $trait) {
        if (is_array($trait)) {
            $append(
                $catalog,
                $trait
            );
        }
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_entities
            WHERE game_id = ?
              AND status = 'active'
              AND LOWER(entity_type) = 'character'
            ORDER BY id
            "
        );
    $stmt->execute([$gameId]);

    foreach (
        $stmt->fetchAll(PDO::FETCH_ASSOC)
        as $row
    ) {
        $config =
            gameplayRuntimeStateDecodeConfig(
                $row['config']
                ?? null
            );

        $traits =
            isset($config['traits']) &&
            is_array($config['traits'])
                ? $config['traits']
                : [];

        foreach ($traits as $trait) {
            if (is_array($trait)) {
                $append(
                    $catalog,
                    $trait
                );
            }
        }
    }

    foreach ($catalog as $normalized => $definition) {
        if (!empty($definition['conflict'])) {
            unset($catalog[$normalized]);
        }
    }

    uasort(
        $catalog,
        static function (
            array $a,
            array $b
        ): int {
            return strcasecmp(
                (string)$a['name'],
                (string)$b['name']
            );
        }
    );

    return $catalog;
}


/*
 * WAYFARER_CANONICAL_REGION_TARGETS_V68
 *
 * Region authoring now uses explicit universal Region identities such as
 * region:12:trait:weather. The bare "region" scope remains runtime-compatible
 * only for legacy data. These helpers convert that legacy shape at the Region
 * editor/save boundary so every new save becomes canonical.
 */
function gameplayCanonicalRegionTargetKey(
    string $targetKey,
    int $regionId
): string {
    $targetKey = trim($targetKey);

    if ($targetKey === '' || $regionId <= 0) {
        return $targetKey;
    }

    if (
        preg_match(
            '/^region:trait:(.+)$/',
            $targetKey,
            $match
        ) === 1
    ) {
        return
            'region:' .
            $regionId .
            ':trait:' .
            $match[1];
    }

    if (
        preg_match(
            '/^region:([^:]+)$/',
            $targetKey,
            $match
        ) === 1
    ) {
        return
            'region:' .
            $regionId .
            ':trait:' .
            $match[1];
    }

    return $targetKey;
}


function gameplayCanonicalizeLegacyCurrentRegionConditionNode(
    $node,
    int $regionId
) {
    if (!is_array($node) || $regionId <= 0) {
        return $node;
    }

    $type =
        (string)(
            $node['type']
            ?? ''
        );

    if ($type === 'condition') {
        if (isset($node['target'])) {
            $node['target'] =
                gameplayCanonicalRegionTargetKey(
                    (string)$node['target'],
                    $regionId
                );
        }

        if (
            (string)($node['scope'] ?? '') === 'region' &&
            trim((string)($node['target_id'] ?? '')) !== ''
        ) {
            $node['scope'] =
                'region:' . $regionId;

            if (
                trim((string)($node['target_type'] ?? '')) === ''
            ) {
                $node['target_type'] =
                    'trait';
            }
        }

        return $node;
    }

    if (
        isset($node['children']) &&
        is_array($node['children'])
    ) {
        foreach (
            $node['children']
            as $index => $child
        ) {
            $node['children'][$index] =
                gameplayCanonicalizeLegacyCurrentRegionConditionNode(
                    $child,
                    $regionId
                );
        }
    }

    return $node;
}


function gameplayCanonicalizeLegacyCurrentRegionTickEffects(
    array $effects,
    int $regionId
): array {
    if ($regionId <= 0) {
        return $effects;
    }

    foreach (
        $effects
        as $effectIndex => $effect
    ) {
        if (!is_array($effect)) {
            continue;
        }

        if (isset($effect['target'])) {
            $effect['target'] =
                gameplayCanonicalRegionTargetKey(
                    (string)$effect['target'],
                    $regionId
                );
        }

        if (
            (string)($effect['target_scope'] ?? '') === 'region' &&
            trim((string)($effect['target_id'] ?? '')) !== ''
        ) {
            $effect['target_scope'] =
                'region:' . $regionId;

            if (
                trim((string)($effect['target_type'] ?? '')) === ''
            ) {
                $effect['target_type'] =
                    'trait';
            }
        }

        if (
            isset($effect['conditions']) &&
            is_array($effect['conditions'])
        ) {
            $effect['conditions'] =
                gameplayCanonicalizeLegacyCurrentRegionConditionNode(
                    $effect['conditions'],
                    $regionId
                );
        }

        if (
            isset($effect['branches']) &&
            is_array($effect['branches'])
        ) {
            foreach (
                $effect['branches']
                as $branchIndex => $branch
            ) {
                if (!is_array($branch)) {
                    continue;
                }

                if (
                    isset($branch['conditions']) &&
                    is_array($branch['conditions'])
                ) {
                    $branch['conditions'] =
                        gameplayCanonicalizeLegacyCurrentRegionConditionNode(
                            $branch['conditions'],
                            $regionId
                        );
                }

                $effect['branches'][$branchIndex] =
                    $branch;
            }
        }

        $effects[$effectIndex] =
            $effect;
    }

    return $effects;
}

/*
|--------------------------------------------------------------------------
| Status definitions / target metadata
| WAYFARER_STATUSES_AUTHORING_V87
|--------------------------------------------------------------------------
*/
function gameplayStatusDefinitions(
    PDO $pdo,
    int $gameId,
    bool $activeOnly = true
): array {
    if ($gameId <= 0) {
        return [];
    }

    $sql = "
        SELECT
            id,
            name,
            description,
            config,
            status
        FROM wf_statuses
        WHERE game_id = ?
    ";

    if ($activeOnly) {
        $sql .= " AND status = 'active'";
    }

    $sql .= " ORDER BY name, id";

    $stmt = $pdo->prepare($sql);
    $stmt->execute([$gameId]);

    $definitions = [];

    foreach ($stmt->fetchAll(PDO::FETCH_ASSOC) as $row) {
        $id = (int)($row['id'] ?? 0);
        if ($id <= 0) {
            continue;
        }

        $config = gameplayRuntimeStateDecodeConfig(
            $row['config'] ?? null
        );

        $normalizeBoolean = static function ($value, bool $default): bool {
            if ($value === null || $value === '') {
                return $default;
            }

            if (is_bool($value)) {
                return $value;
            }

            return in_array(
                strtolower(trim((string)$value)),
                ['1', 'true', 'yes', 'on'],
                true
            );
        };

        $definitions[(string)$id] = [
            'id' => $id,
            'name' => trim((string)($row['name'] ?? ('Status ' . $id))),
            'description' => trim((string)($row['description'] ?? '')),
            'status' => strtolower(trim((string)($row['status'] ?? 'draft'))),
            'show_to_player' =>
                $normalizeBoolean(
                    $config['show_to_player'] ?? null,
                    true
                ),
            /* WAYFARER_STATUS_LIFECYCLE_AUTHORING_V88 */
            'show_stage_to_player' =>
                $normalizeBoolean(
                    $config['show_stage_to_player'] ?? null,
                    true
                ),
            'show_time_remaining' =>
                $normalizeBoolean(
                    $config['show_time_remaining'] ?? null,
                    false
                ),
            'lifecycle' =>
                isset($config['lifecycle']) &&
                is_array($config['lifecycle'])
                    ? $config['lifecycle']
                    : null,
        ];
    }

    return $definitions;
}


function gameplayStatusTargetDefinition(
    string $scope,
    int $statusId,
    string $statusName,
    array $hierarchy,
    array $extra = []
): array {
    return array_merge(
        [
            'scope' => $scope,
            'target_scope' => $scope,
            'target_type' => 'status',
            'target_id' => (string)$statusId,
            'trait_type' => 'boolean',
            'data_type' => 'boolean',
            'semantic_type' => 'status',
            'helper' => 'Persistent Status: Active / Inactive',
            'condition_operators' => [
                'equals',
                'not_equals',
            ],
            'effect_operations' => [
                'set',
            ],
            'supports_random' => false,
            'value_options' => [
                '0' => 'Inactive',
                '1' => 'Active',
            ],
            'group' => 'Statuses',
            'label' => $statusName,
            'hierarchy' => $hierarchy,
        ],
        $extra
    );
}


function gameplayRuntimeStateTargets(
    PDO $pdo,
    int $gameId,
    ?array $gameTraitsOverride = null,
    ?array $playerTraitsOverride = null,
    ?int $playerSlotsOverride = null
): array {

    $targets = [];

    /*
     * Navigation Position is runtime state rather than a Trait, but it belongs
     * in the same searchable state catalog. It may simply be unresolved in a
     * playthrough/navigation mode where Position does not exist.
     */
    $targets['navigation:position:position'] = [
        'scope' => 'navigation',
        'target_scope' => 'navigation',
        'target_type' => 'position',
        'target_id' => 'position',
        'trait_type' => 'number',
        'data_type' => 'number',
        'semantic_type' => 'navigation_position',
        'helper' => 'Number',
        'condition_operators' => wayfarerConditionOperators(),
        'effect_operations' => ['set', 'add', 'subtract'],
        'supports_random' => true,
        'group' => 'Navigation',
        'label' => 'Navigation → Position',
    ];


    $gameConfig = [];
    $playerSlots =
        $playerSlotsOverride;

    if ($gameId > 0) {
        $stmt =
            $pdo->prepare(
                "
                SELECT
                    config,
                    player_slots
                FROM wf_games
                WHERE id = ?
                LIMIT 1
                "
            );

        $stmt->execute([
            $gameId
        ]);

        $gameRow =
            $stmt->fetch(
                PDO::FETCH_ASSOC
            );

        if ($gameRow) {
            $gameConfig =
                gameplayRuntimeStateDecodeConfig(
                    $gameRow['config']
                        ?? null
                );

            if ($playerSlots === null) {
                $playerSlots =
                    max(
                        0,
                        (int)(
                            $gameRow['player_slots']
                            ?? 0
                        )
                    );
            }
        }
    }

    $gameTraits =
        $gameTraitsOverride !== null
            ? $gameTraitsOverride
            : (
                isset($gameConfig['traits']) &&
                is_array($gameConfig['traits'])
                    ? $gameConfig['traits']
                    : []
            );

    $playerTraits =
        $playerTraitsOverride !== null
            ? $playerTraitsOverride
            : (
                isset($gameConfig['player_traits']) &&
                is_array($gameConfig['player_traits'])
                    ? $gameConfig['player_traits']
                    : []
            );

    $playerSlots =
        max(
            0,
            (int)($playerSlots ?? 0)
        );


    foreach ($gameTraits as $trait) {
        if (!is_array($trait)) {
            continue;
        }

        gameplayRuntimeStateAddTraitTarget(
            $targets,
            'game',
            'Game Traits',
            'Game',
            $trait
        );
    }


    /* WAYFARER_PARTY_TARGETS_V85 */
    foreach (
        gameplayPartyTraitCatalog(
            $pdo,
            $gameId,
            $playerTraits
        )
        as $partyTrait
    ) {
        $partyName =
            (string)(
                $partyTrait['name']
                ?? ''
            );

        $partyDataType =
            (string)(
                $partyTrait['data_type']
                ?? 'text'
            );

        if (
            $partyName === '' ||
            !in_array(
                $partyDataType,
                ['number', 'boolean'],
                true
            )
        ) {
            continue;
        }

        $partyTargetId =
            gameplayPartyTraitTargetId(
                $partyName
            );

        $partyKey =
            'party:trait:' .
            $partyTargetId;

        $targets[$partyKey] = [
            'scope' => 'party',
            'target_scope' => 'party',
            'target_type' => 'trait',
            'target_id' => $partyTargetId,
            'trait_type' => $partyDataType,
            'data_type' => $partyDataType,
            'semantic_type' => 'party_all_trait',
            'helper' =>
                'Every current party member that exposes this Trait',
            'condition_operators' =>
                $partyDataType === 'number'
                    ? wayfarerConditionOperators()
                    : [
                        'equals',
                        'not_equals',
                    ],
            'effect_operations' =>
                $partyDataType === 'number'
                    ? [
                        'set',
                        'add',
                        'subtract',
                    ]
                    : [
                        'set',
                    ],
            'supports_random' =>
                $partyDataType === 'number',
            /*
             * A Party Condition needs an explicit Any/All quantifier model.
             * Until that exists, this aggregate target is Effect-only.
             */
            'condition_hidden' => true,
            'group' => 'Party',
            'label' =>
                'All Party Members → ' .
                $partyName,
            'hierarchy' => [
                [
                    'key' => 'party',
                    'label' => 'Party',
                ],
                [
                    'key' => 'all_party_members',
                    'label' => 'All Party Members',
                ],
                [
                    'key' => $partyTargetId,
                    'label' => $partyName,
                ],
            ],
        ];

        if ($partyDataType === 'boolean') {
            $targets[$partyKey]['value_options'] = [
                '0' => 'False',
                '1' => 'True',
            ];
        }
    }


    /* WAYFARER_STATUS_TARGETS_V87 */
    $statusDefinitions =
        gameplayStatusDefinitions(
            $pdo,
            $gameId,
            true
        );

    foreach ($statusDefinitions as $statusDefinition) {
        $statusId =
            (int)($statusDefinition['id'] ?? 0);
        $statusName =
            trim((string)($statusDefinition['name'] ?? ''));

        if ($statusId <= 0 || $statusName === '') {
            continue;
        }

        $partyStatusKey =
            'party:status:' . $statusId;

        $targets[$partyStatusKey] =
            gameplayStatusTargetDefinition(
                'party',
                $statusId,
                $statusName,
                [
                    [
                        'key' => 'party',
                        'label' => 'Party',
                    ],
                    [
                        'key' => 'all_party_members',
                        'label' => 'All Party Members',
                    ],
                    [
                        'key' => 'status:' . $statusId,
                        'label' => 'Status — ' . $statusName,
                    ],
                ],
                [
                    /* Party Status Conditions need explicit Any/All semantics. */
                    'condition_hidden' => true,
                    'group' => 'Party',
                    'label' =>
                        'All Party Members → Status — ' .
                        $statusName,
                ]
            );

        for ($slot = 0; $slot < $playerSlots; $slot++) {
            $playerStatusKey =
                'player:' . $slot . ':status:' . $statusId;

            $targets[$playerStatusKey] =
                gameplayStatusTargetDefinition(
                    'player:' . $slot,
                    $statusId,
                    $statusName,
                    [
                        [
                            'key' => 'player',
                            'label' => 'Player Character',
                        ],
                        [
                            'key' => 'player:' . $slot,
                            'label' => 'Player ' . ($slot + 1),
                        ],
                        [
                            'key' => 'status:' . $statusId,
                            'label' => 'Status — ' . $statusName,
                        ],
                    ],
                    [
                        /* Player slots remain a runtime compatibility address. */
                        'condition_hidden' => true,
                        'effect_hidden' => true,
                    ]
                );
        }
    }


    /*
     * Numbered Player slots remain runtime-compatible for existing authored
     * data, but they are implementation slots rather than useful new targets.
     * New authoring uses Storylet Binding -> Random Party Member or
     * Party -> All Party Members instead.
     */
    for ($slot = 0; $slot < $playerSlots; $slot++) {
        foreach ($playerTraits as $trait) {
            if (!is_array($trait)) {
                continue;
            }

            gameplayRuntimeStateAddTraitTarget(
                $targets,
                'player:' . $slot,
                'Player Character ' . ($slot + 1),
                'Player ' . ($slot + 1),
                $trait
            );

            $traitId =
                trim(
                    (string)(
                        $trait['id']
                        ?? $trait['system_key']
                        ?? ''
                    )
                );

            $playerKey =
                'player:' .
                $slot .
                ':trait:' .
                $traitId;

            if (
                $traitId !== '' &&
                isset($targets[$playerKey])
            ) {
                $targets[$playerKey]['condition_hidden'] = true;
                $targets[$playerKey]['effect_hidden'] = true;
            }
        }
    }


    if ($gameId <= 0) {
        return $targets;
    }


    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                name,
                config
            FROM wf_regions
            WHERE game_id = ?
            ORDER BY name, id
            "
        );

    $stmt->execute([
        $gameId
    ]);

    foreach (
        $stmt->fetchAll(PDO::FETCH_ASSOC)
        as $row
    ) {
        $id =
            (int)($row['id'] ?? 0);

        if ($id <= 0) {
            continue;
        }

        $name =
            trim(
                (string)(
                    $row['name']
                    ?? ('Region ' . $id)
                )
            );

        $config =
            gameplayRuntimeStateDecodeConfig(
                $row['config']
                    ?? null
            );

        $traits =
            isset($config['traits']) &&
            is_array($config['traits'])
                ? $config['traits']
                : [];

        foreach ($traits as $trait) {
            if (!is_array($trait)) {
                continue;
            }

            gameplayRuntimeStateAddTraitTarget(
                $targets,
                'region:' . $id,
                'Region — ' . $name,
                $name,
                $trait
            );
        }
    }


    $stmt =
        $pdo->prepare(
            "
            SELECT
                l.id,
                l.name,
                l.config,
                r.name AS region_name
            FROM wf_locations l
            INNER JOIN wf_regions r
                ON r.id = l.region_id
            WHERE r.game_id = ?
            ORDER BY r.name, l.name, l.id
            "
        );

    $stmt->execute([
        $gameId
    ]);

    foreach (
        $stmt->fetchAll(PDO::FETCH_ASSOC)
        as $row
    ) {
        $id =
            (int)($row['id'] ?? 0);

        if ($id <= 0) {
            continue;
        }

        $name =
            trim(
                (string)(
                    $row['name']
                    ?? ('Location ' . $id)
                )
            );

        $regionName =
            trim(
                (string)(
                    $row['region_name']
                    ?? ''
                )
            );

        $group =
            'Location — ' .
            (
                $regionName !== ''
                    ? $regionName . ' / '
                    : ''
            ) .
            $name;

        $config =
            gameplayRuntimeStateDecodeConfig(
                $row['config']
                    ?? null
            );

        $traits =
            isset($config['traits']) &&
            is_array($config['traits'])
                ? $config['traits']
                : [];

        foreach ($traits as $trait) {
            if (!is_array($trait)) {
                continue;
            }

            gameplayRuntimeStateAddTraitTarget(
                $targets,
                'location:' . $id,
                $group,
                $name,
                $trait
            );
        }
    }


    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                name,
                entity_type,
                config
            FROM wf_entities
            WHERE game_id = ?
            ORDER BY entity_type, name, id
            "
        );

    $stmt->execute([
        $gameId
    ]);

    foreach (
        $stmt->fetchAll(PDO::FETCH_ASSOC)
        as $row
    ) {
        $id =
            (int)($row['id'] ?? 0);

        if ($id <= 0) {
            continue;
        }

        $name =
            trim(
                (string)(
                    $row['name']
                    ?? ('Entity ' . $id)
                )
            );

        $entityType =
            strtolower(
                trim(
                    (string)(
                        $row['entity_type']
                        ?? ''
                    )
                )
            );

        $config =
            gameplayRuntimeStateDecodeConfig(
                $row['config']
                    ?? null
            );

        if ($entityType === 'item') {
            gameplayRuntimeStateAddTraitTarget(
                $targets,
                'entity:' . $id,
                'Items',
                $name,
                [
                    'id' => 'sys_item_quantity',
                    'name' => 'Quantity',
                    'type' => 'number',
                    'active' => true,
                ],
                'Quantity',
                'quantity'
            );
        }

        if ($entityType === 'character') {
            gameplayRuntimeStateAddTraitTarget(
                $targets,
                'entity:' . $id,
                'Characters',
                $name,
                [
                    'id' => 'sys_character_party_member',
                    'name' => 'Party Membership',
                    'type' => 'binary',
                    'active' => true,
                ],
                'Party Membership',
                'party_member'
            );
        }

        $traits =
            isset($config['traits']) &&
            is_array($config['traits'])
                ? $config['traits']
                : [];

        foreach ($traits as $trait) {
            if (
                !is_array($trait) ||
                !empty($trait['system'])
            ) {
                continue;
            }

            gameplayRuntimeStateAddTraitTarget(
                $targets,
                'entity:' . $id,
                $entityType === 'character'
                    ? 'Characters'
                    : (
                        $entityType === 'item'
                            ? 'Items'
                            : 'Entities'
                    ),
                $name,
                $trait
            );
        }

        if ($entityType === 'character') {
            foreach ($statusDefinitions as $statusDefinition) {
                $statusId =
                    (int)($statusDefinition['id'] ?? 0);
                $statusName =
                    trim((string)($statusDefinition['name'] ?? ''));

                if ($statusId <= 0 || $statusName === '') {
                    continue;
                }

                $statusKey =
                    'entity:' . $id . ':status:' . $statusId;

                $targets[$statusKey] =
                    gameplayStatusTargetDefinition(
                        'entity:' . $id,
                        $statusId,
                        $statusName,
                        [
                            [
                                'key' => 'character',
                                'label' => 'Character',
                            ],
                            [
                                'key' => 'entity:' . $id,
                                'label' => $name,
                            ],
                            [
                                'key' => 'status:' . $statusId,
                                'label' => 'Status — ' . $statusName,
                            ],
                        ],
                        [
                            'group' => 'Characters',
                            'label' =>
                                $name .
                                ' → Status — ' .
                                $statusName,
                        ]
                    );
            }
        }
    }


    return $targets;
}

function gameplayConditionTraitTargets(
    array $traits,
    string $scope,
    string $groupLabel
): array {

    $targets = [];

    foreach ($traits as $trait) {

        if (!is_array($trait)) {
            continue;
        }

        if (
            isset(
                $trait['active']
            ) &&
            !$trait['active']
        ) {
            continue;
        }

        $traitId =
            trim(
                (string)(
                    $trait['id']
                    ?? ''
                )
            );

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

        $key =
            $scope .
            ':trait:' .
            $traitId;

        $targets[$key] = [
            'scope' => $scope,
            'target_type' => 'trait',
            'target_id' => $traitId,
            'trait_type' =>
                (string)(
                    $trait['type']
                    ?? 'text'
                ),
            'group' => $groupLabel,
            'label' =>
                (string)(
                    $trait['name']
                    ?? $traitId
                ),
        ];
    }

    return $targets;
}


function gameplayConditionAllowedTargets(
    array $gameTraits,
    array $scopeTraits = [],
    string $scope = '',
    string $scopeLabel = ''
): array {

    $targets =
        gameplayConditionTraitTargets(
            $gameTraits,
            'game',
            'Game Traits'
        );

    if ($scope !== '') {

        $targets =
            array_merge(
                $targets,
                gameplayConditionTraitTargets(
                    $scopeTraits,
                    $scope,
                    $scopeLabel !== ''
                        ? $scopeLabel . ' Traits'
                        : ucfirst($scope) . ' Traits'
                )
            );
    }

    return $targets;
}


/*
|--------------------------------------------------------------------------
| Game-wide condition targets
|--------------------------------------------------------------------------
| WAYFARER_GAME_WIDE_CONDITION_TARGETS_V46
|
| Global rules may inspect persistent state anywhere in the Game.
|
| Game Traits use their existing scope:
|     game
|
| A specific Region's Traits use:
|     region:<region id>
|
| The existing plain "region" scope is intentionally left untouched. It
| continues to mean the context Region for Region/Location-scoped rules.
|
*/

/* WAYFARER_GAME_WIDE_TARGETS_ARE_UNIVERSAL_V56 */

/*
|--------------------------------------------------------------------------
| Navigation Condition Targets
|--------------------------------------------------------------------------
| WAYFARER_LOCATION_CONDITION_TARGETS_V75
| WAYFARER_LIVE_LOCATION_ANCHORS_V76
|
| Numeric Position Conditions are Region-qualified.
|
| New Location Conditions reference wf_locations.id as target_id. The
| comparison itself is against zero because runtime resolves the target to:
|
|     current position - current anchor position
|
| That makes a Location a live spatial anchor:
|
|     =  0  => At
|     != 0  => Not at
|     <  0  => Before
|     <= 0  => At or before
|     >  0  => After
|     >= 0  => At or after
|
| The V75 snapshot target navigation:location:location remains hidden for
| backward compatibility only.
|
*/

function gameplayConditionNavigationPositionToken(
    $value
): string {

    if (!is_numeric($value)) {
        return '';
    }

    $number = (float)$value;

    if (is_finite($number) && floor($number) == $number) {
        return (string)((int)$number);
    }

    $token =
        rtrim(
            rtrim(
                sprintf('%.12F', $number),
                '0'
            ),
            '.'
        );

    return $token === '-0'
        ? '0'
        : $token;
}


function gameplayNavigationConditionTargets(
    PDO $pdo,
    int $gameId
): array {

    $targets = [];

    /*
     * Compatibility only. Existing saved unqualified Position Conditions
     * still render and save, but cannot be newly authored.
     */
    $targets['navigation:position:position'] = [
        'scope' => 'navigation',
        'target_scope' => 'navigation',
        'target_type' => 'position',
        'target_id' => 'position',
        'trait_type' => 'number',
        'data_type' => 'number',
        'semantic_type' => 'navigation_position_legacy',
        'helper' => 'Number',
        'condition_operators' => wayfarerConditionOperators(),
        'group' => 'Navigation',
        'label' => 'Position (legacy unqualified)',
        'condition_hidden' => true,
    ];

    /*
     * Compatibility only. V75 stored Region + Position in the value itself.
     * New V76 Conditions never use this target.
     */
    $targets['navigation:location:location'] = [
        'scope' => 'navigation',
        'target_scope' => 'navigation',
        'target_type' => 'location',
        'target_id' => 'location',
        'trait_type' => 'text',
        'data_type' => 'text',
        'semantic_type' => 'navigation_location_v75_snapshot',
        'helper' => 'V75 snapshot',
        'condition_operators' => [
            'equals',
            'not_equals',
        ],
        'group' => 'Navigation',
        'label' => 'Location (legacy V75 snapshot)',
        'condition_hidden' => true,
    ];

    if ($gameId <= 0) {
        return $targets;
    }


    /*
     * Fixed numeric Position, explicitly qualified to one linear Region.
     */
    $regionStmt =
        $pdo->prepare(
            "
            SELECT
                id,
                name,
                navigation_type
            FROM wf_regions
            WHERE game_id = ?
            ORDER BY name, id
            "
        );

    $regionStmt->execute([
        $gameId
    ]);

    foreach (
        $regionStmt->fetchAll(PDO::FETCH_ASSOC)
        as $region
    ) {
        $regionId =
            (int)($region['id'] ?? 0);

        if ($regionId <= 0) {
            continue;
        }

        if (
            strtolower(
                trim(
                    (string)(
                        $region['navigation_type']
                        ?? ''
                    )
                )
            ) !== 'linear'
        ) {
            continue;
        }

        $regionName =
            trim(
                (string)(
                    $region['name']
                    ?? ('Region ' . $regionId)
                )
            );

        $scope =
            'navigation:' .
            $regionId;

        $key =
            $scope .
            ':position:position';

        $targets[$key] = [
            'scope' => $scope,
            'target_scope' => $scope,
            'target_type' => 'position',
            'target_id' => 'position',
            'trait_type' => 'number',
            'data_type' => 'number',
            'semantic_type' => 'navigation_region_position',
            'helper' => 'Number',
            'condition_operators' => wayfarerConditionOperators(),
            'group' => 'Navigation — Positions',
            'label' => $regionName,
        ];
    }


    /*
     * Named Locations are LIVE references. Each Location is its own target,
     * identified by wf_locations.id. Position is shown only as authoring help;
     * it is resolved again from current Location config at runtime.
     */
    $locationStmt =
        $pdo->prepare(
            "
            SELECT
                l.id,
                l.name,
                l.config,
                l.region_id,
                r.name AS region_name,
                r.navigation_type
            FROM wf_locations l
            INNER JOIN wf_regions r
                ON r.id = l.region_id
            WHERE r.game_id = ?
            ORDER BY r.name, l.name, l.id
            "
        );

    $locationStmt->execute([
        $gameId
    ]);

    foreach (
        $locationStmt->fetchAll(PDO::FETCH_ASSOC)
        as $location
    ) {
        if (
            strtolower(
                trim(
                    (string)(
                        $location['navigation_type']
                        ?? ''
                    )
                )
            ) !== 'linear'
        ) {
            continue;
        }

        $locationId =
            (int)(
                $location['id']
                ?? 0
            );

        if ($locationId <= 0) {
            continue;
        }

        $config =
            gameplayRuntimeStateDecodeConfig(
                $location['config']
                ?? null
            );

        if (
            !array_key_exists(
                'position',
                $config
            ) ||
            !is_numeric(
                $config['position']
            )
        ) {
            continue;
        }

        $position =
            gameplayConditionNavigationPositionToken(
                $config['position']
            );

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

        $locationName =
            trim(
                (string)(
                    $location['name']
                    ?? ('Location ' . $locationId)
                )
            );

        $regionName =
            trim(
                (string)(
                    $location['region_name']
                    ?? 'Region'
                )
            );

        $key =
            'navigation:location:' .
            $locationId;

        $targets[$key] = [
            'scope' => 'navigation',
            'target_scope' => 'navigation',
            'target_type' => 'location',
            'target_id' => (string)$locationId,
            'trait_type' => 'number',
            'data_type' => 'number',
            'semantic_type' => 'navigation_location_anchor',
            'helper' =>
                $regionName .
                ' · Position ' .
                $position,
            'condition_operators' => [
                'equals',
                'not_equals',
                'less_than',
                'less_than_or_equal',
                'greater_than',
                'greater_than_or_equal',
            ],
            'condition_operator_labels' => [
                'equals' => 'At',
                'not_equals' => 'Not at',
                'less_than' => 'Before',
                'less_than_or_equal' => 'At or before',
                'greater_than' => 'After',
                'greater_than_or_equal' => 'At or after',
            ],
            /*
             * The runtime value is a signed delta from this anchor, so every
             * comparison is against zero. Keep that implementation detail out
             * of the authoring UI while still posting a normal Condition value.
             */
            'value_options' => [
                '0' => 'Anchor',
            ],
            'condition_hide_value' => true,
            'group' => 'Navigation — Locations',
            'label' => $locationName,
        ];
    }

    return $targets;
}


/*
 * Allows Condition POST validation to recognize V76 navigation-only target
 * shapes even when a caller supplied the older universal Effect catalog.
 */

/*
|--------------------------------------------------------------------------
| Storylet Navigation Effect targets
| WAYFARER_STORYLET_ROOT_CONNECTIONS_V82
|--------------------------------------------------------------------------
|
| Explicit Storylet navigation is an Effect-only target. A Storylet may
| continue directly to another root Storylet after its other Effects resolve.
| Child Storylets remain structural Branches and are deliberately not exposed
| as destinations here.
*/

function gameplayStoryletNavigationEffectTargets(
    PDO $pdo,
    int $gameId,
    int $currentStoryletId = 0
): array {

    $targets = [];

    if ($gameId <= 0) {
        return $targets;
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                name,
                status
            FROM wf_storylets
            WHERE game_id = ?
              AND (
                    parent_storylet_id IS NULL
                    OR parent_storylet_id = 0
                  )
            ORDER BY name, id
            "
        );

    $stmt->execute([
        $gameId
    ]);

    foreach (
        $stmt->fetchAll(PDO::FETCH_ASSOC)
        as $storylet
    ) {
        $storyletId =
            (int)(
                $storylet['id']
                ?? 0
            );

        if (
            $storyletId <= 0 ||
            (
                $currentStoryletId > 0 &&
                $storyletId === $currentStoryletId
            )
        ) {
            continue;
        }

        $name =
            trim(
                (string)(
                    $storylet['name']
                    ?? ''
                )
            );

        if ($name === '') {
            $name =
                'Storylet ' .
                $storyletId;
        }

        $status =
            strtolower(
                trim(
                    (string)(
                        $storylet['status']
                        ?? ''
                    )
                )
            );

        $helper =
            $status !== ''
                ? ucfirst($status) . ' root Storylet'
                : 'Root Storylet';

        $key =
            'storylet:transition:' .
            $storyletId;

        $targets[$key] = [
            'scope' =>
                'storylet',
            'target_scope' =>
                'storylet',
            'target_type' =>
                'transition',
            'target_id' =>
                (string)$storyletId,
            'trait_type' =>
                'text',
            'data_type' =>
                'text',
            'semantic_type' =>
                'storylet_transition',
            'helper' =>
                $helper,
            'effect_operations' => [
                'continue',
            ],
            'supports_random' =>
                false,
            'group' =>
                'Storylet Navigation',
            'label' =>
                $name .
                ' → Continue To',
            'hierarchy' => [
                [
                    'key' =>
                        'storylet',
                    'label' =>
                        'Storylet',
                ],
                [
                    'key' =>
                        'storylet:' .
                        $storyletId,
                    'label' =>
                        $name,
                ],
                [
                    'key' =>
                        'continue_to',
                    'label' =>
                        'Continue To',
                ],
            ],
        ];
    }

    return $targets;
}


/*
|--------------------------------------------------------------------------
| Hierarchical target-ready Time Conditions
| WAYFARER_HIERARCHICAL_TARGETS_V80
|--------------------------------------------------------------------------
|
| The hierarchy UI consumes a generic target catalog. New systems can opt in
| simply by supplying a three-level hierarchy array:
|
|   Type -> Specific Target -> Property
|
| Current Game Time is Condition-only. Effects do not modify the clock here.
| Calendar / Seasons can later register additional Time properties without
| changing the picker.
*/

function gameplayTimeConditionTargets(
    PDO $pdo,
    int $gameId
): array {

    $targets = [];

    if ($gameId <= 0) {
        return $targets;
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_games
            WHERE id = ?
            LIMIT 1
            "
        );

    $stmt->execute([
        $gameId
    ]);

    $raw =
        $stmt->fetchColumn();

    if ($raw === false) {
        return $targets;
    }

    $config =
        gameplayRuntimeStateDecodeConfig(
            $raw
        );

    $time =
        isset($config['time']) &&
        is_array($config['time'])
            ? $config['time']
            : [];

    $mode =
        strtolower(
            trim(
                (string)(
                    $time['mode']
                    ?? 'none'
                )
            )
        );

    if (
        $mode !== 'days' &&
        $mode !== 'hours'
    ) {
        return $targets;
    }

    $base = [
        'scope' => 'time',
        'target_scope' => 'time',
        'target_type' => 'clock',
        'trait_type' => 'number',
        'data_type' => 'number',
        'semantic_type' => 'game_time',
        'helper' => 'Number',
        'condition_operators' => wayfarerConditionOperators(),
        'group' => 'Time',
    ];

    $targets['time:clock:day'] =
        array_merge(
            $base,
            [
                'target_id' => 'day',
                'label' => 'Game Clock → Day',
                'hierarchy' => [
                    [
                        'key' => 'time',
                        'label' => 'Time',
                    ],
                    [
                        'key' => 'game_clock',
                        'label' => 'Game Clock',
                    ],
                    [
                        'key' => 'day',
                        'label' => 'Day',
                    ],
                ],
            ]
        );

    if ($mode === 'hours') {
        $targets['time:clock:hour'] =
            array_merge(
                $base,
                [
                    'target_id' => 'hour',
                    'label' => 'Game Clock → Hour',
                    'hierarchy' => [
                        [
                            'key' => 'time',
                            'label' => 'Time',
                        ],
                        [
                            'key' => 'game_clock',
                            'label' => 'Game Clock',
                        ],
                        [
                            'key' => 'hour',
                            'label' => 'Hour',
                        ],
                    ],
                ]
            );
    }

    return $targets;
}


function gameplaySyntheticTimeConditionTarget(
    string $target
): ?array {

    if ($target === 'time:clock:day') {
        return [
            'scope' => 'time',
            'target_scope' => 'time',
            'target_type' => 'clock',
            'target_id' => 'day',
            'trait_type' => 'number',
            'data_type' => 'number',
            'semantic_type' => 'game_time',
            'condition_operators' => wayfarerConditionOperators(),
        ];
    }

    if ($target === 'time:clock:hour') {
        return [
            'scope' => 'time',
            'target_scope' => 'time',
            'target_type' => 'clock',
            'target_id' => 'hour',
            'trait_type' => 'number',
            'data_type' => 'number',
            'semantic_type' => 'game_time',
            'condition_operators' => wayfarerConditionOperators(),
        ];
    }

    return null;
}

function gameplaySyntheticNavigationConditionTarget(
    string $target
): ?array {

    if (
        preg_match(
            '/^navigation:([1-9][0-9]*):position:position$/',
            $target,
            $match
        ) === 1
    ) {
        $scope =
            'navigation:' .
            (int)$match[1];

        return [
            'scope' => $scope,
            'target_scope' => $scope,
            'target_type' => 'position',
            'target_id' => 'position',
            'trait_type' => 'number',
            'data_type' => 'number',
            'semantic_type' => 'navigation_region_position',
            'condition_operators' => wayfarerConditionOperators(),
        ];
    }

    if (
        preg_match(
            '/^navigation:location:([1-9][0-9]*)$/',
            $target,
            $match
        ) === 1
    ) {
        return [
            'scope' => 'navigation',
            'target_scope' => 'navigation',
            'target_type' => 'location',
            'target_id' => (string)((int)$match[1]),
            'trait_type' => 'number',
            'data_type' => 'number',
            'semantic_type' => 'navigation_location_anchor',
            'condition_operators' => [
                'equals',
                'not_equals',
                'less_than',
                'less_than_or_equal',
                'greater_than',
                'greater_than_or_equal',
            ],
        ];
    }

    /* V75 snapshot compatibility. */
    if ($target === 'navigation:location:location') {
        return [
            'scope' => 'navigation',
            'target_scope' => 'navigation',
            'target_type' => 'location',
            'target_id' => 'location',
            'trait_type' => 'text',
            'data_type' => 'text',
            'semantic_type' => 'navigation_location_v75_snapshot',
            'condition_operators' => [
                'equals',
                'not_equals',
            ],
        ];
    }

    return null;
}

function gameplayConditionGameWideTargets(
    PDO $pdo,
    int $gameId,
    array $gameTraits
): array {

    return
        array_replace(
            gameplayRuntimeStateTargets(
                $pdo,
                $gameId,
                $gameTraits,
                null,
                null
            ),
            gameplayNavigationConditionTargets(
                $pdo,
                $gameId
            ),
            gameplayTimeConditionTargets(
                $pdo,
                $gameId
            )
        );
}


function gameplayBuildConditionNodeFromPost(
    $postedNode,
    array $allowedTargets,
    int $depth = 0
): array {

    if (
        $postedNode === null ||
        $postedNode === []
    ) {
        return [
            'node' => null,
            'error' => '',
        ];
    }

    if (
        $depth > 20 ||
        !is_array(
            $postedNode
        )
    ) {
        return [
            'node' => null,
            'error' =>
                'Invalid condition structure.',
        ];
    }

    $type =
        trim(
            (string)(
                $postedNode['type']
                ?? ''
            )
        );

    if ($type === 'group') {

        $mode =
            trim(
                (string)(
                    $postedNode['mode']
                    ?? 'all'
                )
            );

        if (
            !in_array(
                $mode,
                wayfarerConditionGroupModes(),
                true
            )
        ) {
            return [
                'node' => null,
                'error' =>
                    'Condition groups must use ALL or ANY.',
            ];
        }

        $postedChildren =
            $postedNode['children']
            ?? [];

        if (!is_array($postedChildren)) {
            return [
                'node' => null,
                'error' =>
                    'Invalid condition group.',
            ];
        }

        $children = [];

        foreach ($postedChildren as $postedChild) {

            $result =
                gameplayBuildConditionNodeFromPost(
                    $postedChild,
                    $allowedTargets,
                    $depth + 1
                );

            if ($result['error'] !== '') {
                return $result;
            }

            if ($result['node'] !== null) {
                $children[] =
                    $result['node'];
            }
        }

        /*
         * An empty root/group is equivalent to no conditions.
         */
        if ($children === []) {
            return [
                'node' => null,
                'error' => '',
            ];
        }

        return [
            'node' => [
                'type' => 'group',
                'mode' => $mode,
                'children' => $children,
            ],
            'error' => '',
        ];
    }

    if ($type === 'condition') {

        $target =
            trim(
                (string)(
                    $postedNode['target']
                    ?? ''
                )
            );

        $operator =
            trim(
                (string)(
                    $postedNode['operator']
                    ?? ''
                )
            );

        $value =
            $postedNode['value']
            ?? '';

        /*
         * WAYFARER_LOCATION_CONDITION_TARGETS_V75
         *
         * Older callers may still pass the universal Effect target catalog.
         * Region-qualified Position and Location targets are Condition-only,
         * so synthesize their definitions here when needed.
         */
        if (
            $target !== '' &&
            !isset($allowedTargets[$target])
        ) {
            $syntheticTarget =
                gameplaySyntheticNavigationConditionTarget(
                    $target
                );

            if (
                $syntheticTarget === null &&
                function_exists(
                    'gameplaySyntheticTimeConditionTarget'
                )
            ) {
                $syntheticTarget =
                    gameplaySyntheticTimeConditionTarget(
                        $target
                    );
            }

            if ($syntheticTarget !== null) {
                $allowedTargets[$target] =
                    $syntheticTarget;
            }
        }

        if (
            $target === '' &&
            trim(
                (string)$value
            ) === ''
        ) {
            return [
                'node' => null,
                'error' => '',
            ];
        }

        if (
            $target === '' ||
            !isset(
                $allowedTargets[$target]
            )
        ) {
            return [
                'node' => null,
                'error' =>
                    'Each condition must use a valid target.',
            ];
        }

        if (
            !in_array(
                $operator,
                wayfarerConditionOperators(),
                true
            )
        ) {
            return [
                'node' => null,
                'error' =>
                    'Invalid condition comparison.',
            ];
        }

        if (
            trim(
                (string)$value
            ) === ''
        ) {
            return [
                'node' => null,
                'error' =>
                    'Each condition must include a comparison value.',
            ];
        }

        $definition =
            $allowedTargets[$target];

        /* WAYFARER_DATATYPE_CONDITION_VALIDATION_V58 */
        $conditionOperators =
            isset($definition['condition_operators']) &&
            is_array($definition['condition_operators'])
                ? array_values($definition['condition_operators'])
                : wayfarerConditionOperators();

        if (!in_array($operator, $conditionOperators, true)) {
            return [
                'node' => null,
                'error' =>
                    'That comparison is not valid for the selected condition target.',
            ];
        }

        $conditionDataType =
            strtolower(
                trim(
                    (string)(
                        $definition['data_type']
                        ?? $definition['trait_type']
                        ?? 'text'
                    )
                )
            );

        if ($conditionDataType === 'binary') {
            $conditionDataType = 'boolean';
        }

        if (
            $conditionDataType === 'number' &&
            !is_numeric($value)
        ) {
            return [
                'node' => null,
                'error' =>
                    'Numeric conditions require a numeric comparison value.',
            ];
        }

        if (
            $conditionDataType === 'boolean' &&
            !in_array(
                strtolower(trim((string)$value)),
                ['0', '1', 'true', 'false'],
                true
            )
        ) {
            return [
                'node' => null,
                'error' =>
                    'Boolean conditions must use one of the available values.',
            ];
        }

        $normalizedConditionValue =
            $conditionDataType === 'boolean'
                ? (
                    in_array(
                        strtolower(trim((string)$value)),
                        ['1', 'true'],
                        true
                    )
                        ? 1
                        : 0
                )
                : wayfarerConditionNormalizeScalar(
                    $value
                );

        return [
            'node' => [
                'type' => 'condition',
                'scope' =>
                    $definition['scope'],
                'target_type' =>
                    $definition['target_type'],
                'target_id' =>
                    $definition['target_id'],
                'operator' =>
                    $operator,
                'value' =>
                    $normalizedConditionValue,
            ],
            'error' => '',
        ];
    }

    return [
        'node' => null,
        'error' =>
            'Invalid condition node.',
    ];
}



==============================================================================
FILE: includes/gameplay/game-endings.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Game Endings
 * WAYFARER_GAME_ENDINGS_V45
 * --------------------------------------------------------------------------
 */

function wayfarerEndingMakeId(): string
{
    return
        'ending_' .
        bin2hex(
            random_bytes(8)
        );
}


function wayfarerBuildGameEndingsFromPost(
    PDO $pdo,
    int $gameId,
    array $postedEndings,
    array $gameTraits
): array {

    /* WAYFARER_GAME_WIDE_ENDING_CONDITIONS_V46 */
    $allowedTargets =
        gameplayConditionGameWideTargets(
            $pdo,
            $gameId,
            $gameTraits
        );

    $endings =
        [];

    $seenIds =
        [];


    foreach (
        array_values(
            $postedEndings
        )
        as $postedEnding
    ) {

        if (!is_array($postedEnding)) {
            continue;
        }


        $title =
            trim(
                (string)(
                    $postedEnding['title']
                    ?? ''
                )
            );

        $text =
            trim(
                (string)(
                    $postedEnding['text']
                    ?? ''
                )
            );

        $priorityRaw =
            trim(
                (string)(
                    $postedEnding['priority']
                    ?? '0'
                )
            );

        $imageMediaId =
            (int)(
                $postedEnding['image_media_id']
                ?? 0
            );

        $postedConditions =
            $postedEnding['conditions']
            ?? null;


        if (
            $title === '' &&
            $text === '' &&
            $imageMediaId <= 0 &&
            (
                $postedConditions === null ||
                $postedConditions === []
            )
        ) {
            continue;
        }


        if ($title === '') {

            return [
                'endings' => [],
                'error' =>
                    'Each Ending must have a Title.',
            ];
        }


        if (
            $priorityRaw === '' ||
            filter_var(
                $priorityRaw,
                FILTER_VALIDATE_INT
            ) === false
        ) {

            return [
                'endings' => [],
                'error' =>
                    'Ending Priority must be a whole number.',
            ];
        }


        $conditionResult =
            gameplayBuildConditionNodeFromPost(
                $postedConditions,
                $allowedTargets
            );


        if (
            $conditionResult['error'] !==
            ''
        ) {

            return [
                'endings' => [],
                'error' =>
                    $conditionResult['error'],
            ];
        }


        if (
            $conditionResult['node'] ===
            null
        ) {

            return [
                'endings' => [],
                'error' =>
                    'Each Ending must have at least one Condition.',
            ];
        }


        if ($imageMediaId > 0) {

            if ($gameId <= 0) {

                return [
                    'endings' => [],
                    'error' =>
                        'Save the Game before assigning an Ending image.',
                ];
            }


            $mediaStmt =
                $pdo->prepare(
                    "
                    SELECT id
                    FROM wf_media
                    WHERE id = ?
                      AND game_id = ?
                      AND media_type = 'image'
                    LIMIT 1
                    "
                );

            $mediaStmt->execute([
                $imageMediaId,
                $gameId,
            ]);

            if (
                $mediaStmt->fetchColumn() ===
                false
            ) {

                return [
                    'endings' => [],
                    'error' =>
                        'An Ending uses an invalid image asset.',
                ];
            }
        }


        $id =
            trim(
                (string)(
                    $postedEnding['id']
                    ?? ''
                )
            );

        if (
            $id === '' ||
            !preg_match(
                '/^ending_[A-Za-z0-9_-]+$/',
                $id
            )
        ) {
            $id =
                wayfarerEndingMakeId();
        }


        if (isset($seenIds[$id])) {

            return [
                'endings' => [],
                'error' =>
                    'Ending IDs must be unique.',
            ];
        }

        $seenIds[$id] =
            true;


        $endings[] = [
            'id' =>
                $id,

            'title' =>
                $title,

            'text' =>
                $text,

            'image_media_id' =>
                $imageMediaId,

            'priority' =>
                (int)$priorityRaw,

            'conditions' =>
                $conditionResult['node'],
        ];
    }


    return [
        'endings' =>
            $endings,

        'error' =>
            '',
    ];
}


function wayfarerRenderGameEndingsEditor(
    PDO $pdo,
    int $gameId,
    array $endings,
    array $gameTraits
): void {

    $imageAssets =
        [];

    if ($gameId > 0) {

        $stmt =
            $pdo->prepare(
                "
                SELECT id, name
                FROM wf_media
                WHERE game_id = ?
                  AND media_type = 'image'
                ORDER BY name, id
                "
            );

        $stmt->execute([
            $gameId
        ]);

        $imageAssets =
            $stmt->fetchAll(
                PDO::FETCH_ASSOC
            );
    }


    $conditionTargets =
        gameplayConditionGameWideTargets(
            $pdo,
            $gameId,
            $gameTraits
        );

    ?>
    <section
        class="builder-game-endings"
        data-game-endings-editor
    >
        <input
            type="hidden"
            name="endings_present"
            value="1"
        >

        <div data-game-endings-list>

            <?php foreach (
                array_values($endings)
                as $endingIndex => $ending
            ): ?>

                <?php
                $ending =
                    is_array($ending)
                        ? $ending
                        : [];

                $endingId =
                    (string)(
                        $ending['id']
                        ?? ''
                    );

                $endingName =
                    'endings[' .
                    (int)$endingIndex .
                    ']';
                ?>

                <section
                    class="builder-starting-choice builder-game-ending"
                    data-game-ending
                    data-ending-index="<?= (int)$endingIndex ?>"
                >
                    <input
                        type="hidden"
                        name="<?= builderEscape($endingName) ?>[id]"
                        value="<?= builderEscape($endingId) ?>"
                        data-ending-field="id"
                    >

                    <div class="builder-starting-choice-header">
                        <strong>Ending</strong>

                        <button
                            type="button"
                            class="secondary-button"
                            data-remove-game-ending
                        >
                            Remove Ending
                        </button>
                    </div>

                    <div class="builder-starting-choice-fields">
                        <label>
                            Title
                            <input
                                type="text"
                                name="<?= builderEscape($endingName) ?>[title]"
                                value="<?= builderEscape(
                                    $ending['title']
                                    ?? ''
                                ) ?>"
                            >
                        </label>

                        <label>
                            Priority
                            <input
                                type="number"
                                step="1"
                                name="<?= builderEscape($endingName) ?>[priority]"
                                value="<?= builderEscape(
                                    $ending['priority']
                                    ?? 0
                                ) ?>"
                            >
                        </label>
                    </div>

                    <p>
                        <label>
                            Ending Text
                            <br>

                            <textarea
                                name="<?= builderEscape($endingName) ?>[text]"
                                rows="5"
                            ><?= builderEscape(
                                $ending['text']
                                ?? ''
                            ) ?></textarea>
                        </label>
                    </p>

                    <p>
                        <label>
                            Image
                            <br>

                            <select
                                name="<?= builderEscape($endingName) ?>[image_media_id]"
                            >
                                <option value="0">
                                    -- No Image --
                                </option>

                                <?php foreach (
                                    $imageAssets
                                    as $asset
                                ): ?>

                                    <option
                                        value="<?= (int)$asset['id'] ?>"
                                        <?= (int)(
                                            $ending['image_media_id']
                                            ?? 0
                                        ) ===
                                        (int)$asset['id']
                                            ? 'selected'
                                            : '' ?>
                                    >
                                        <?= builderEscape(
                                            $asset['name']
                                        ) ?>
                                    </option>

                                <?php endforeach; ?>
                            </select>
                        </label>
                    </p>

                    <h4>Conditions</h4>

                    <p class="builder-field-help">
                        Required. When these conditions become true, this
                        Ending becomes terminal. Higher Priority wins if more
                        than one Ending becomes true at the same time.
                    </p>

                    <?php
                    $conditionEditorNode =
                        $ending['conditions']
                        ?? null;

                    $conditionEditorName =
                        $endingName .
                        '[conditions]';

                    $conditionEditorTargets =
                        $conditionTargets;

                    require __DIR__ .
                        '/condition-editor.php';
                    ?>

                </section>

            <?php endforeach; ?>

        </div>


        <p>
            <button
                type="button"
                class="secondary-button"
                data-add-game-ending
            >
                + Add Ending
            </button>
        </p>


        <template data-game-ending-template>
            <section
                class="builder-starting-choice builder-game-ending"
                data-game-ending
                data-ending-index="__INDEX__"
            >
                <input
                    type="hidden"
                    name="endings[__INDEX__][id]"
                    value=""
                    data-ending-field="id"
                >

                <div class="builder-starting-choice-header">
                    <strong>Ending</strong>

                    <button
                        type="button"
                        class="secondary-button"
                        data-remove-game-ending
                    >
                        Remove Ending
                    </button>
                </div>

                <div class="builder-starting-choice-fields">
                    <label>
                        Title
                        <input
                            type="text"
                            name="endings[__INDEX__][title]"
                        >
                    </label>

                    <label>
                        Priority
                        <input
                            type="number"
                            step="1"
                            name="endings[__INDEX__][priority]"
                            value="0"
                        >
                    </label>
                </div>

                <p>
                    <label>
                        Ending Text
                        <br>
                        <textarea
                            name="endings[__INDEX__][text]"
                            rows="5"
                        ></textarea>
                    </label>
                </p>

                <p>
                    <label>
                        Image
                        <br>

                        <select
                            name="endings[__INDEX__][image_media_id]"
                        >
                            <option value="0">
                                -- No Image --
                            </option>

                            <?php foreach (
                                $imageAssets
                                as $asset
                            ): ?>

                                <option value="<?= (int)$asset['id'] ?>">
                                    <?= builderEscape(
                                        $asset['name']
                                    ) ?>
                                </option>

                            <?php endforeach; ?>
                        </select>
                    </label>
                </p>

                <h4>Conditions</h4>

                <p class="builder-field-help">
                    Add at least one condition.
                </p>

                <div
                    data-new-ending-condition-editor
                ></div>
            </section>
        </template>


        <script
            type="application/json"
            data-game-ending-condition-targets
        ><?= json_encode(
            $conditionTargets,
            JSON_UNESCAPED_SLASHES |
            JSON_UNESCAPED_UNICODE |
            JSON_HEX_TAG |
            JSON_HEX_AMP |
            JSON_HEX_APOS |
            JSON_HEX_QUOT
        ) ?></script>
    </section>
    <?php
}


==============================================================================
FILE: includes/gameplay/starting-choices.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Starting Choices
|--------------------------------------------------------------------------
|
| WAYFARER_STARTING_CHOICES_V36
| WAYFARER_STARTING_CHOICE_PLAYER_TARGETS_V53
|
| Author-defined one-of-many choices presented before runtime initialization.
| Choice effects may target numeric Game Traits or numeric Player Traits.
| Player Trait effects may affect all built-in Player Characters or one
| authored Player Character Slot. The selected option ID is persisted
| separately from its effects so later Storylet conditions can inspect the
| actual choice.
|
*/

require_once __DIR__ . '/functions.php';


function wayfarerStartingChoiceMakeId(string $prefix): string
{
    return
        $prefix .
        '_' .
        bin2hex(
            random_bytes(6)
        );
}


function wayfarerStartingChoiceValidId($value): bool
{
    return
        is_string($value) &&
        preg_match(
            '/^[A-Za-z0-9_-]+$/',
            $value
        ) === 1;
}



/*
 * WAYFARER_STARTING_CHOICE_ITEM_QUANTITY_V54
 *
 * Load active Item Entities that expose the canonical system Quantity Trait.
 * The returned records are authoring targets, not runtime state.
 */
function wayfarerStartingChoiceItemQuantityTargets(
    PDO $pdo,
    int $gameId
): array {
    if ($gameId <= 0) {
        return [];
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                name,
                config
            FROM wf_entities
            WHERE game_id = ?
              AND status = 'active'
              AND LOWER(entity_type) = 'item'
            ORDER BY name, id
            "
        );

    $stmt->execute([
        $gameId
    ]);

    $rows =
        $stmt->fetchAll(
            PDO::FETCH_ASSOC
        );

    $targets = [];

    foreach ($rows as $row) {

        $entityId =
            (int)(
                $row['id']
                ?? 0
            );

        if ($entityId <= 0) {
            continue;
        }

        $config = [];

        if (
            isset($row['config']) &&
            $row['config'] !== null &&
            $row['config'] !== ''
        ) {
            $decoded =
                json_decode(
                    (string)$row['config'],
                    true
                );

            if (is_array($decoded)) {
                $config =
                    $decoded;
            }
        }

        /*
         * WAYFARER_ENTITY_SYSTEM_CONFIG_V55
         *
         * Quantity is universal for Item Entities. Its definition is Wayfarer
         * schema, while this Item's initial/max values live in config.system.
         */
        $quantityTraitId =
            'sys_item_quantity';

        $targets[] = [
            'entity_id' =>
                $entityId,

            'name' =>
                trim(
                    (string)(
                        $row['name']
                        ?? (
                            'Item ' .
                            $entityId
                        )
                    )
                ),

            'target_scope' =>
                'entity:' .
                $entityId,

            'target_type' =>
                'trait',

            'target_id' =>
                $quantityTraitId,

            'target_system_key' =>
                'quantity',
        ];
    }

    return $targets;
}

function wayfarerStartingChoiceEffectTarget(
    array $effect
): string {
    if (!empty($effect['target'])) {
        return (string)$effect['target'];
    }

    $scope =
        (string)(
            $effect['target_scope']
            ?? ''
        );

    $type =
        (string)(
            $effect['target_type']
            ?? ''
        );

    $targetId =
        trim(
            (string)(
                $effect['target_id']
                ?? ''
            )
        );

    if (
        $scope !== '' &&
        $type !== '' &&
        $targetId !== ''
    ) {
        $canonical =
            $scope .
            ':' .
            $type .
            ':' .
            $targetId;

        $runtimeTargets =
            $GLOBALS[
                'wayfarer_starting_runtime_targets'
            ]
            ?? [];

        if (
            is_array($runtimeTargets) &&
            isset($runtimeTargets[$canonical])
        ) {
            return $canonical;
        }
    }

    /*
     * Legacy setup targets remain readable.
     */
    if (
        $scope === 'game' &&
        $type === 'trait' &&
        $targetId !== ''
    ) {
        return
            'game:' .
            $targetId;
    }

    if (
        $scope === 'player' &&
        $type === 'trait' &&
        $targetId !== ''
    ) {
        $selector =
            strtolower(
                trim(
                    (string)(
                        $effect['target_selector']
                        ?? ''
                    )
                )
            );

        if ($selector === 'all') {
            return
                'player_all:' .
                $targetId;
        }

        if (
            $selector === 'slot' &&
            array_key_exists(
                'target_slot',
                $effect
            )
        ) {
            return
                'player_slot:' .
                max(
                    0,
                    (int)$effect['target_slot']
                ) .
                ':' .
                $targetId;
        }
    }


    if (
        $type === 'trait' &&
        $targetId !== '' &&
        preg_match(
            '/^entity:([1-9][0-9]*)$/',
            $scope
        ) === 1
    ) {
        return
            $scope .
            ':' .
            $targetId;
    }
    return '';
}


/*
 * Build the complete target map used by both authoring validation and the
 * Starting Choice target selector.
 */
function wayfarerStartingChoiceAllowedTargets(
    array $gameTraits,
    array $playerTraits = [],
    int $playerSlots = 0,
    array $itemQuantityTargets = [],
    array $runtimeTargets = []
): array {
    /* WAYFARER_STARTING_CHOICES_UNIVERSAL_TARGETS_V56 */
    if ($runtimeTargets) {
        return $runtimeTargets;
    }

    $allowed = [];

    foreach (
        gameplayNumericTraitTargets(
            $gameTraits,
            'game'
        )
        as $trait
    ) {
        $traitId =
            (string)(
                $trait['id']
                ?? ''
            );

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

        $allowed[
            'game:' .
            $traitId
        ] = [
            'target_scope' =>
                'game',
            'target_type' =>
                'trait',
            'target_id' =>
                $traitId,
            'group' =>
                'Game Traits',
            'label' =>
                'Game → ' .
                (string)(
                    $trait['name']
                    ?? $traitId
                ),
        ];
    }

    $playerTargets =
        gameplayNumericTraitTargets(
            $playerTraits,
            'player'
        );

    $playerSlots =
        max(
            0,
            $playerSlots
        );

    if (
        $playerSlots > 0 &&
        !empty($playerTargets)
    ) {
        foreach ($playerTargets as $trait) {

            $traitId =
                (string)(
                    $trait['id']
                    ?? ''
                );

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

            $allowed[
                'player_all:' .
                $traitId
            ] = [
                'target_scope' =>
                    'player',
                'target_type' =>
                    'trait',
                'target_id' =>
                    $traitId,
                'target_selector' =>
                    'all',
                'group' =>
                    'Player Traits — All Players',
                'label' =>
                    'All Players → ' .
                    (string)(
                        $trait['name']
                        ?? $traitId
                    ),
            ];
        }

        for (
            $slot = 0;
            $slot < $playerSlots;
            $slot++
        ) {
            foreach ($playerTargets as $trait) {

                $traitId =
                    (string)(
                        $trait['id']
                        ?? ''
                    );

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

                $allowed[
                    'player_slot:' .
                    $slot .
                    ':' .
                    $traitId
                ] = [
                    'target_scope' =>
                        'player',
                    'target_type' =>
                        'trait',
                    'target_id' =>
                        $traitId,
                    'target_selector' =>
                        'slot',
                    'target_slot' =>
                        $slot,
                    'group' =>
                        'Player Character ' .
                        ($slot + 1),
                    'label' =>
                        'Player ' .
                        ($slot + 1) .
                        ' → ' .
                        (string)(
                            $trait['name']
                            ?? $traitId
                        ),
                ];
            }
        }
    }


    foreach ($itemQuantityTargets as $itemTarget) {

        if (!is_array($itemTarget)) {
            continue;
        }

        $scope =
            trim(
                (string)(
                    $itemTarget['target_scope']
                    ?? ''
                )
            );

        $targetId =
            trim(
                (string)(
                    $itemTarget['target_id']
                    ?? ''
                )
            );

        $entityId =
            (int)(
                $itemTarget['entity_id']
                ?? 0
            );

        if (
            $entityId <= 0 ||
            !preg_match(
                '/^entity:[1-9][0-9]*$/',
                $scope
            ) ||
            $targetId === ''
        ) {
            continue;
        }

        $key =
            $scope .
            ':' .
            $targetId;

        $allowed[$key] = [
            'target_scope' =>
                $scope,

            'target_type' =>
                'trait',

            'target_id' =>
                $targetId,

            'target_system_key' =>
                'quantity',

            'group' =>
                'Items',

            'label' =>
                (string)(
                    $itemTarget['name']
                    ?? (
                        'Item ' .
                        $entityId
                    )
                ) .
                ' → Quantity',
        ];
    }

    return $allowed;
}

function wayfarerBuildStartingChoicesFromPost(
    array $postedChoices,
    array $gameTraits,
    array $playerTraits = [],
    int $playerSlots = 0,
    array $itemQuantityTargets = [],
    array $runtimeTargets = []
): array {

    $allowedTargets =
        wayfarerStartingChoiceAllowedTargets(
            $gameTraits,
            $playerTraits,
            $playerSlots,
            $itemQuantityTargets,
            $runtimeTargets
        );

    /*
     * Legacy migration map:
     *
     * V52 allowed authors to move a definition from Game Traits to Player
     * Traits while keeping its Trait ID, but V36 Starting Choices still held
     * game:TRAIT_ID. When that exact ID is now a Player Trait, interpret the
     * old target as All Player Characters.
     */
    $legacyPlayerTraitTargets = [];

    foreach (
        gameplayNumericTraitTargets(
            $playerTraits,
            'player'
        )
        as $trait
    ) {
        $traitId =
            (string)(
                $trait['id']
                ?? ''
            );

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

        $legacyPlayerTraitTargets[
            'game:' .
            $traitId
        ] =
            'player_all:' .
            $traitId;
    }

    $choices = [];
    $seenChoiceIds = [];

    foreach (
        array_values($postedChoices)
        as $choiceIndex => $postedChoice
    ) {
        if (!is_array($postedChoice)) {
            continue;
        }

        $prompt =
            trim(
                (string)(
                    $postedChoice['prompt']
                    ?? ''
                )
            );

        $postedOptions =
            isset($postedChoice['options']) &&
            is_array($postedChoice['options'])
                ? array_values(
                    $postedChoice['options']
                )
                : [];

        /*
         * Completely blank newly-added card: ignore it.
         */
        if (
            $prompt === '' &&
            $postedOptions === []
        ) {
            continue;
        }

        if ($prompt === '') {
            return [
                'choices' => [],
                'error' =>
                    'Each Starting Choice must have a prompt.',
            ];
        }

        $choiceId =
            wayfarerStartingChoiceValidId(
                $postedChoice['id']
                ?? null
            )
                ? (string)$postedChoice['id']
                : wayfarerStartingChoiceMakeId(
                    'choice'
                );

        if (isset($seenChoiceIds[$choiceId])) {
            return [
                'choices' => [],
                'error' =>
                    'Starting Choice IDs must be unique.',
            ];
        }

        $seenChoiceIds[$choiceId] =
            true;

        $required =
            !empty(
                $postedChoice['required']
            );

        $options = [];
        $seenOptionIds = [];

        foreach (
            $postedOptions
            as $optionIndex => $postedOption
        ) {
            if (!is_array($postedOption)) {
                continue;
            }

            $label =
                trim(
                    (string)(
                        $postedOption['label']
                        ?? ''
                    )
                );

            $description =
                trim(
                    (string)(
                        $postedOption['description']
                        ?? ''
                    )
                );

            $postedEffects =
                isset($postedOption['effects']) &&
                is_array($postedOption['effects'])
                    ? array_values(
                        $postedOption['effects']
                    )
                    : [];

            if (
                $label === '' &&
                $description === '' &&
                $postedEffects === []
            ) {
                continue;
            }

            if ($label === '') {
                return [
                    'choices' => [],
                    'error' =>
                        'Each Starting Choice option must have a label.',
                ];
            }

            $optionId =
                wayfarerStartingChoiceValidId(
                    $postedOption['id']
                    ?? null
                )
                    ? (string)$postedOption['id']
                    : wayfarerStartingChoiceMakeId(
                        'option'
                    );

            if (isset($seenOptionIds[$optionId])) {
                return [
                    'choices' => [],
                    'error' =>
                        'Starting Choice option IDs must be unique within a choice.',
                ];
            }

            $seenOptionIds[$optionId] =
                true;

            $effects = [];

            foreach (
                $postedEffects
                as $postedEffect
            ) {
                if (!is_array($postedEffect)) {
                    continue;
                }

                $target =
                    trim(
                        (string)(
                            $postedEffect['target']
                            ?? ''
                        )
                    );

                $operation =
                    strtolower(
                        trim(
                            (string)(
                                $postedEffect['operation']
                                ?? ''
                            )
                        )
                    );

                $valueMode =
                    strtolower(
                        trim(
                            (string)(
                                $postedEffect['value_mode']
                                ?? 'fixed'
                            )
                        )
                    );

                $valueRaw =
                    trim(
                        (string)(
                            $postedEffect['value']
                            ?? ''
                        )
                    );

                $minRaw =
                    trim(
                        (string)(
                            $postedEffect['value_min']
                            ?? ''
                        )
                    );

                $maxRaw =
                    trim(
                        (string)(
                            $postedEffect['value_max']
                            ?? ''
                        )
                    );

                /*
                 * Empty newly-added effect row.
                 */
                if (
                    $target === '' &&
                    $operation === '' &&
                    $valueRaw === '' &&
                    $minRaw === '' &&
                    $maxRaw === ''
                ) {
                    continue;
                }

                /*
                 * Preserve the intent of a Trait moved from Game -> Player.
                 */
                if (
                    !isset($allowedTargets[$target]) &&
                    isset(
                        $legacyPlayerTraitTargets[$target]
                    ) &&
                    isset(
                        $allowedTargets[
                            $legacyPlayerTraitTargets[$target]
                        ]
                    )
                ) {
                    $target =
                        $legacyPlayerTraitTargets[$target];
                }

                if (
                    $target === '' ||
                    !isset(
                        $allowedTargets[$target]
                    )
                ) {
                    return [
                        'choices' => [],
                        'error' =>
                            'Each Starting Choice effect must use a valid runtime-state target.',
                    ];
                }

                /* WAYFARER_STARTING_CHOICE_DATATYPE_EFFECTS_V58 */
                $targetDefinition =
                    $allowedTargets[$target];

                $targetDataType =
                    strtolower(
                        trim(
                            (string)(
                                $targetDefinition['data_type']
                                ?? $targetDefinition['trait_type']
                                ?? 'text'
                            )
                        )
                    );

                if ($targetDataType === 'binary') {
                    $targetDataType = 'boolean';
                }

                $allowedOperations =
                    isset($targetDefinition['effect_operations']) &&
                    is_array($targetDefinition['effect_operations'])
                        ? array_values($targetDefinition['effect_operations'])
                        : (
                            $targetDataType === 'number'
                                ? ['set', 'add', 'subtract']
                                : ['set']
                        );

                if (
                    !in_array(
                        $operation,
                        $allowedOperations,
                        true
                    )
                ) {
                    return [
                        'choices' => [],
                        'error' =>
                            'That Starting Choice operation is not valid for the selected target.',
                    ];
                }

                $supportsRandom =
                    array_key_exists('supports_random', $targetDefinition)
                        ? !empty($targetDefinition['supports_random'])
                        : $targetDataType === 'number';

                if (
                    !in_array(
                        $valueMode,
                        ['fixed', 'random'],
                        true
                    ) ||
                    (
                        $valueMode === 'random' &&
                        !$supportsRandom
                    )
                ) {
                    return [
                        'choices' => [],
                        'error' =>
                            $supportsRandom
                                ? 'Starting Choice value type must be Fixed or Random.'
                                : 'Random values are only available for numeric targets.',
                    ];
                }

                $effect = [
                    'target_scope' =>
                        (string)$targetDefinition['target_scope'],
                    'target_type' =>
                        (string)(
                            $targetDefinition['target_type']
                            ?? 'trait'
                        ),
                    'target_id' =>
                        (string)$targetDefinition['target_id'],
                    'operation' =>
                        $operation,
                    'value_mode' =>
                        $valueMode,
                ];

                if ($valueMode === 'random') {
                    if (
                        $minRaw === '' ||
                        $maxRaw === '' ||
                        !is_numeric($minRaw) ||
                        !is_numeric($maxRaw)
                    ) {
                        return [
                            'choices' => [],
                            'error' =>
                                'Random Starting Choice effects require numeric Min and Max values.',
                        ];
                    }

                    $minimum =
                        gameplayEffectNormalizeNumber(
                            $minRaw
                        );

                    $maximum =
                        gameplayEffectNormalizeNumber(
                            $maxRaw
                        );

                    if ((float)$minimum > (float)$maximum) {
                        return [
                            'choices' => [],
                            'error' =>
                                'Random Starting Choice Min cannot be greater than Max.',
                        ];
                    }

                    $effect['value_min'] =
                        $minimum;

                    $effect['value_max'] =
                        $maximum;

                } else {
                    if (
                        $targetDataType === 'number' &&
                        (
                            $valueRaw === '' ||
                            !is_numeric($valueRaw)
                        )
                    ) {
                        return [
                            'choices' => [],
                            'error' =>
                                'Numeric Starting Choice effects require a numeric value.',
                        ];
                    }

                    if (
                        $targetDataType === 'boolean' &&
                        !in_array(
                            strtolower($valueRaw),
                            ['0', '1', 'true', 'false'],
                            true
                        )
                    ) {
                        return [
                            'choices' => [],
                            'error' =>
                                'Boolean Starting Choice effects must use one of the available values.',
                        ];
                    }

                    if ($targetDataType === 'boolean') {
                        $lowerValue = strtolower($valueRaw);
                        $effect['value'] =
                            ($lowerValue === '1' || $lowerValue === 'true')
                                ? 1
                                : 0;
                    } else {
                        $effect['value'] =
                            is_numeric($valueRaw)
                                ? gameplayEffectNormalizeNumber(
                                    $valueRaw
                                )
                                : $valueRaw;
                    }
                }



                if (
                    !empty(
                        $targetDefinition[
                            'target_system_key'
                        ]
                    )
                ) {
                    $effect['target_system_key'] =
                        (string)$targetDefinition[
                            'target_system_key'
                        ];
                }
                if (
                    $targetDefinition['target_scope'] ===
                    'player'
                ) {
                    $effect['target_selector'] =
                        (string)(
                            $targetDefinition[
                                'target_selector'
                            ]
                            ?? 'all'
                        );

                    if (
                        $effect['target_selector'] ===
                        'slot'
                    ) {
                        $effect['target_slot'] =
                            (int)(
                                $targetDefinition[
                                    'target_slot'
                                ]
                                ?? 0
                            );
                    }
                }

                $effects[] =
                    $effect;
            }

            $options[] = [
                'id' =>
                    $optionId,
                'label' =>
                    $label,
                'description' =>
                    $description,
                'effects' =>
                    $effects,
            ];
        }

        if ($options === []) {
            return [
                'choices' => [],
                'error' =>
                    'Each Starting Choice must have at least one option.',
            ];
        }

        $choices[] = [
            'id' =>
                $choiceId,
            'prompt' =>
                $prompt,
            'required' =>
                $required,
            'options' =>
                $options,
        ];
    }

    return [
        'choices' =>
            $choices,
        'error' =>
            '',
    ];
}

function wayfarerRenderStartingChoiceTargetOptions(
    array $gameTraits,
    array $playerTraits = [],
    int $playerSlots = 0,
    array $itemQuantityTargets = [],
    string $selected = '',
    array $runtimeTargets = []
): void {

    $targets =
        wayfarerStartingChoiceAllowedTargets(
            $gameTraits,
            $playerTraits,
            $playerSlots,
            $itemQuantityTargets,
            $runtimeTargets
        );

    /*
     * If an existing option still stores game:TRAIT_ID but that ID now lives
     * under Player Traits, present it as All Players instead of losing the
     * selection in the editor.
     */
    if (
        $selected !== '' &&
        !isset($targets[$selected]) &&
        strpos(
            $selected,
            'game:'
        ) === 0
    ) {
        $traitId =
            substr(
                $selected,
                strlen('game:')
            );

        $candidate =
            'player_all:' .
            $traitId;

        if (isset($targets[$candidate])) {
            $selected =
                $candidate;
        }
    }

    echo '<option value="">Select target...</option>';

    $grouped = [];

    foreach ($targets as $value => $target) {
        $group =
            (string)(
                $target['group']
                ?? 'Traits'
            );

        if (!isset($grouped[$group])) {
            $grouped[$group] = [];
        }

        $grouped[$group][$value] =
            $target;
    }

    foreach ($grouped as $group => $options) {

        echo
            '<optgroup label="' .
            builderEscape($group) .
            '">';

        foreach ($options as $value => $target) {

            echo
                '<option value="' .
                builderEscape($value) .
                '"' .
                (
                    $value === $selected
                        ? ' selected'
                        : ''
                ) .
                '>' .
                builderEscape(
                    (string)(
                        $target['label']
                        ?? $value
                    ) .
                    (
                        trim((string)($target['helper'] ?? '')) !== ''
                            ? ' — ' . trim((string)$target['helper'])
                            : ''
                    )
                ) .
                '</option>';
        }

        echo '</optgroup>';
    }
}

function wayfarerRenderStartingChoiceEffect(
    array $effect = []
): void {

    $target =
        wayfarerStartingChoiceEffectTarget(
            $effect
        );

    $operation =
        (string)(
            $effect['operation']
            ?? 'set'
        );

    $valueMode =
        strtolower(
            trim(
                (string)(
                    $effect['value_mode']
                    ?? 'fixed'
                )
            )
        ) === 'random'
            ? 'random'
            : 'fixed';

    $value =
        $effect['value']
        ?? '';

    $minimum =
        $effect['value_min']
        ?? '';

    $maximum =
        $effect['value_max']
        ?? '';

    ?>
    <div
        class="builder-starting-effect"
        data-starting-effect
    >
        <label>
            Target
            <select
                data-starting-effect-field="target"
                data-starting-effect-target
            >
                <?php
                wayfarerRenderStartingChoiceTargetOptions(
                    $GLOBALS['traits'] ?? [],
                    $GLOBALS[
                        'wayfarer_starting_player_traits'
                    ] ?? [],
                    (int)(
                        $GLOBALS[
                            'wayfarer_starting_player_slots'
                        ]
                        ?? 0
                    ),
                    $GLOBALS[
                        'wayfarer_starting_item_quantity_targets'
                    ] ?? [],
                    $target,
                    $GLOBALS[
                        'wayfarer_starting_runtime_targets'
                    ] ?? []
                );
                ?>
            </select>
        </label>

        <label>
            Operation
            <select
                data-starting-effect-field="operation"
                data-starting-effect-operation
            >
                <?php foreach (
                    [
                        'set' => 'Set',
                        'add' => 'Add',
                        'subtract' => 'Subtract',
                    ]
                    as $operationValue => $operationLabel
                ): ?>
                    <option
                        value="<?= builderEscape($operationValue) ?>"
                        <?= $operation === $operationValue
                            ? 'selected'
                            : '' ?>
                    >
                        <?= builderEscape($operationLabel) ?>
                    </option>
                <?php endforeach; ?>
            </select>
        </label>

        <label data-starting-value-mode-wrap>
            Value Type
            <select
                data-starting-effect-field="value_mode"
                data-starting-value-mode
            >
                <option
                    value="fixed"
                    <?= $valueMode === 'fixed'
                        ? 'selected'
                        : '' ?>
                >Fixed</option>
                <option
                    value="random"
                    <?= $valueMode === 'random'
                        ? 'selected'
                        : '' ?>
                >Random</option>
            </select>
        </label>

        <label
            data-starting-fixed-wrap
            <?= $valueMode === 'random'
                ? 'hidden'
                : '' ?>
        >
            Value
            <input
                type="number"
                step="any"
                value="<?= builderEscape($value) ?>"
                data-starting-effect-field="value"
                data-starting-fixed-input
                <?= $valueMode === 'random'
                    ? 'disabled'
                    : '' ?>
            >
        </label>

        <div
            class="builder-effect-random-range"
            data-starting-random-wrap
            <?= $valueMode === 'random'
                ? ''
                : 'hidden' ?>
        >
            <label>
                Min
                <input
                    type="number"
                    step="any"
                    value="<?= builderEscape($minimum) ?>"
                    data-starting-effect-field="value_min"
                    <?= $valueMode === 'random'
                        ? ''
                        : 'disabled' ?>
                >
            </label>

            <label>
                Max
                <input
                    type="number"
                    step="any"
                    value="<?= builderEscape($maximum) ?>"
                    data-starting-effect-field="value_max"
                    <?= $valueMode === 'random'
                        ? ''
                        : 'disabled' ?>
                >
            </label>
        </div>

        <button
            type="button"
            class="secondary-button"
            data-remove-starting-effect
        >
            Remove Effect
        </button>
    </div>
    <?php
}


function wayfarerRenderStartingChoiceOption(
    array $option = []
): void {

    $optionId =
        (string)(
            $option['id']
            ?? ''
        );

    $label =
        (string)(
            $option['label']
            ?? ''
        );

    $description =
        (string)(
            $option['description']
            ?? ''
        );

    $effects =
        isset($option['effects']) &&
        is_array($option['effects'])
            ? array_values(
                $option['effects']
            )
            : [];

    ?>
    <div
        class="builder-starting-option"
        data-starting-option
    >
        <input
            type="hidden"
            value="<?= builderEscape($optionId) ?>"
            data-starting-option-field="id"
        >

        <div class="builder-starting-option-header">
            <strong>Option</strong>

            <button
                type="button"
                class="secondary-button"
                data-remove-starting-option
            >
                Remove Option
            </button>
        </div>

        <div class="builder-starting-option-fields">
            <label>
                Label
                <input
                    type="text"
                    value="<?= builderEscape($label) ?>"
                    data-starting-option-field="label"
                >
            </label>

            <label>
                Description
                <textarea
                    rows="2"
                    data-starting-option-field="description"
                ><?= builderEscape($description) ?></textarea>
            </label>
        </div>

        <div class="builder-starting-effects">
            <div class="builder-starting-effects-heading">
                <strong>Starting Effects</strong>
                <small>
                    Optional. Effects may target any runtime-state target. Numeric targets support Fixed or Random values.
                </small>
            </div>

            <div data-starting-effects-list>
                <?php foreach ($effects as $effect): ?>
                    <?php
                    wayfarerRenderStartingChoiceEffect(
                        is_array($effect)
                            ? $effect
                            : []
                    );
                    ?>
                <?php endforeach; ?>
            </div>

            <button
                type="button"
                class="secondary-button"
                data-add-starting-effect
            >
                + Add Effect
            </button>
        </div>
    </div>
    <?php
}


function wayfarerRenderStartingChoice(
    array $choice = []
): void {

    $choiceId =
        (string)(
            $choice['id']
            ?? ''
        );

    $prompt =
        (string)(
            $choice['prompt']
            ?? ''
        );

    $required =
        array_key_exists(
            'required',
            $choice
        )
            ? !empty(
                $choice['required']
            )
            : true;

    $options =
        isset($choice['options']) &&
        is_array($choice['options'])
            ? array_values(
                $choice['options']
            )
            : [];

    ?>
    <section
        class="builder-starting-choice"
        data-starting-choice
    >
        <input
            type="hidden"
            value="<?= builderEscape($choiceId) ?>"
            data-starting-choice-field="id"
        >

        <div class="builder-starting-choice-header">
            <strong>Starting Choice</strong>

            <button
                type="button"
                class="secondary-button"
                data-remove-starting-choice
            >
                Remove Choice
            </button>
        </div>

        <div class="builder-starting-choice-fields">
            <label>
                Prompt
                <input
                    type="text"
                    value="<?= builderEscape($prompt) ?>"
                    placeholder="What is your occupation?"
                    data-starting-choice-field="prompt"
                >
            </label>

            <label>
                Required
                <select
                    data-starting-choice-field="required"
                >
                    <option
                        value="1"
                        <?= $required ? 'selected' : '' ?>
                    >
                        Yes
                    </option>

                    <option
                        value="0"
                        <?= !$required ? 'selected' : '' ?>
                    >
                        No
                    </option>
                </select>
            </label>
        </div>

        <div
            class="builder-starting-options"
            data-starting-options-list
        >
            <?php foreach ($options as $option): ?>
                <?php
                wayfarerRenderStartingChoiceOption(
                    is_array($option)
                        ? $option
                        : []
                );
                ?>
            <?php endforeach; ?>
        </div>

        <button
            type="button"
            class="secondary-button"
            data-add-starting-option
        >
            + Add Option
        </button>
    </section>
    <?php
}


function wayfarerRenderStartingChoicesEditor(
    array $choices,
    array $gameTraits,
    array $playerTraits = [],
    int $playerSlots = 0,
    array $runtimeTargets = []
): void {

    /*
     * WAYFARER_STARTING_CHOICE_PLAYER_TARGETS_V53
     *
     * Rendering helpers use globals only while the nested templates render.
     * Preserve any previous values because the same reusable helpers may be
     * invoked elsewhere on the page.
     */
    $previousTraits =
        $GLOBALS['traits']
        ?? null;

    $previousPlayerTraits =
        $GLOBALS[
            'wayfarer_starting_player_traits'
        ]
        ?? null;

    $previousPlayerSlots =
        $GLOBALS[
            'wayfarer_starting_player_slots'
        ]
        ?? null;

    $GLOBALS['traits'] =
        $gameTraits;

    $GLOBALS[
        'wayfarer_starting_player_traits'
    ] =
        $playerTraits;

    $GLOBALS[
        'wayfarer_starting_player_slots'
    ] =
        max(
            0,
            $playerSlots
        );

    $previousRuntimeTargets =
        $GLOBALS[
            'wayfarer_starting_runtime_targets'
        ]
        ?? null;

    $GLOBALS[
        'wayfarer_starting_runtime_targets'
    ] =
        $runtimeTargets;

    ?>
    <section
        class="builder-starting-choices-editor"
        data-starting-choices-editor
    >
        <!-- WAYFARER_STARTING_CHOICES_EMPTY_DELETE_V36_1 -->
        <input
            type="hidden"
            name="setup_choices_present"
            value="1"
        >

        <!-- WAYFARER_STARTING_CHOICE_DATATYPE_UI_V58 -->
        <script
            type="application/json"
            data-starting-runtime-targets-json
        ><?= json_encode(
            $runtimeTargets,
            JSON_UNESCAPED_SLASHES |
            JSON_UNESCAPED_UNICODE |
            JSON_HEX_TAG |
            JSON_HEX_AMP |
            JSON_HEX_APOS |
            JSON_HEX_QUOT
        ) ?></script>

        <div class="builder-starting-choices-heading">
            <div>
                <h3>Starting Choices</h3>
                <p class="builder-field-help">
                    Optional one-of-many questions shown before the game begins.
                    The selected option is saved in runtime state. Option effects
                    can update any addressable runtime-state target during initialization.
                </p>
            </div>

            <button
                type="button"
                class="secondary-button"
                data-add-starting-choice
            >
                + Add Starting Choice
            </button>
        </div>

        <div data-starting-choices-list>
            <?php foreach (
                array_values($choices)
                as $choice
            ): ?>
                <?php
                wayfarerRenderStartingChoice(
                    is_array($choice)
                        ? $choice
                        : []
                );
                ?>
            <?php endforeach; ?>
        </div>

        <template data-starting-choice-template>
            <?php
            wayfarerRenderStartingChoice(
                []
            );
            ?>
        </template>

        <template data-starting-option-template>
            <?php
            wayfarerRenderStartingChoiceOption(
                []
            );
            ?>
        </template>

        <template data-starting-effect-template>
            <?php
            wayfarerRenderStartingChoiceEffect(
                []
            );
            ?>
        </template>
    </section>
    <?php

    if ($previousTraits === null) {
        unset(
            $GLOBALS['traits']
        );
    } else {
        $GLOBALS['traits'] =
            $previousTraits;
    }

    if ($previousPlayerTraits === null) {
        unset(
            $GLOBALS[
                'wayfarer_starting_player_traits'
            ]
        );
    } else {
        $GLOBALS[
            'wayfarer_starting_player_traits'
        ] =
            $previousPlayerTraits;
    }

    if ($previousPlayerSlots === null) {
        unset(
            $GLOBALS[
                'wayfarer_starting_player_slots'
            ]
        );
    } else {
        $GLOBALS[
            'wayfarer_starting_player_slots'
        ] =
            $previousPlayerSlots;
    }

    if ($previousRuntimeTargets === null) {
        unset(
            $GLOBALS[
                'wayfarer_starting_runtime_targets'
            ]
        );
    } else {
        $GLOBALS[
            'wayfarer_starting_runtime_targets'
        ] =
            $previousRuntimeTargets;
    }
}



==============================================================================
FILE: includes/gameplay/status-lifecycle.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Status lifecycle authoring
| WAYFARER_STATUS_LIFECYCLE_AUTHORING_V88
| WAYFARER_STATUS_SUBJECT_EFFECTS_AUTHORING_V89
|--------------------------------------------------------------------------
|
| Statuses may remain manual, or define ordered timed stages. The first stage
| is entered when the Status becomes active. Each stage owns a fixed/random
| duration and weighted outcomes whose chances must total 100.
|
*/

function gameplayStatusLifecycleNormalizeKey(
    string $value
): string {
    return strtolower(trim($value));
}


function gameplayStatusLifecycleStorylets(
    PDO $pdo,
    int $gameId
): array {
    if ($gameId <= 0) {
        return [];
    }

    $stmt = $pdo->prepare(
        "
        SELECT
            id,
            name,
            trigger_type,
            status
        FROM wf_storylets
        WHERE game_id = ?
          AND parent_storylet_id IS NULL
        ORDER BY name, id
        "
    );

    $stmt->execute([$gameId]);

    $rows = [];

    foreach ($stmt->fetchAll(PDO::FETCH_ASSOC) as $row) {
        $id = (int)($row['id'] ?? 0);
        if ($id <= 0) {
            continue;
        }

        $rows[$id] = [
            'id' => $id,
            'name' => trim((string)($row['name'] ?? ('Storylet ' . $id))),
            'trigger_type' => strtolower(trim((string)($row['trigger_type'] ?? 'manual'))),
            'status' => strtolower(trim((string)($row['status'] ?? 'draft'))),
        ];
    }

    return $rows;
}


/*
|--------------------------------------------------------------------------
| Status Subject Trait Effects
| WAYFARER_STATUS_SUBJECT_EFFECTS_AUTHORING_V89
|--------------------------------------------------------------------------
|
| Lifecycle Effects address the person who owns the Status rather than an
| authored Player slot or Entity. Trait identity is therefore stored by the
| same normalized authored-name key used by Party Trait targeting and is
| resolved to the subject's actual Trait ID at runtime.
|
*/
function gameplayStatusLifecycleSubjectTraitCatalog(
    PDO $pdo,
    int $gameId
): array {
    $catalog = [];

    foreach (
        gameplayPartyTraitCatalog($pdo, $gameId)
        as $definition
    ) {
        if (!is_array($definition)) {
            continue;
        }

        $name = trim((string)($definition['name'] ?? ''));
        $dataType = strtolower(trim((string)($definition['data_type'] ?? '')));

        if (
            $name === '' ||
            !in_array($dataType, ['number', 'boolean'], true)
        ) {
            continue;
        }

        $targetId = gameplayPartyTraitTargetId($name);

        $catalog[$targetId] = [
            'target_id' => $targetId,
            'name' => $name,
            'data_type' => $dataType,
        ];
    }

    uasort(
        $catalog,
        static function (array $a, array $b): int {
            return strcasecmp(
                (string)($a['name'] ?? ''),
                (string)($b['name'] ?? '')
            );
        }
    );

    return $catalog;
}


function gameplayStatusLifecycleBuildEffects(
    $postedEffects,
    array $traitCatalog,
    bool $recurring,
    string $context
): array {
    $postedEffects = is_array($postedEffects)
        ? array_values($postedEffects)
        : [];

    $effects = [];
    $effectKeys = [];

    foreach ($postedEffects as $effectIndex => $postedEffect) {
        if (!is_array($postedEffect)) {
            continue;
        }

        $targetId = trim((string)($postedEffect['target_id'] ?? ''));
        $operation = strtolower(trim((string)($postedEffect['operation'] ?? '')));

        if ($targetId === '' && $operation === '') {
            continue;
        }

        $number = $effectIndex + 1;

        if ($targetId === '' || !isset($traitCatalog[$targetId])) {
            return [
                'effects' => [],
                'error' => $context . ', Effect ' . $number .
                    ' must select a valid Status Subject Trait.',
            ];
        }

        $definition = $traitCatalog[$targetId];
        $dataType = (string)$definition['data_type'];

        $key = strtolower(trim((string)($postedEffect['key'] ?? '')));
        if ($key === '') {
            try {
                $key = 'effect_' . bin2hex(random_bytes(6));
            } catch (Throwable $exception) {
                $key = 'effect_' . substr(sha1(uniqid('', true)), 0, 12);
            }
        }

        if (preg_match('/^[a-z][a-z0-9_]{0,47}$/', $key) !== 1) {
            return [
                'effects' => [],
                'error' => $context . ', Effect ' . $number .
                    ' has an invalid internal key. Remove and re-add that Effect.',
            ];
        }

        if (isset($effectKeys[$key])) {
            return [
                'effects' => [],
                'error' => $context . ' has duplicate Effect keys.',
            ];
        }
        $effectKeys[$key] = true;

        $allowedOperations = $dataType === 'number'
            ? [
                'set',
                'add',
                'subtract',
                'subtract_percent_current',
                'subtract_percent_max',
                'add_percent_max',
            ]
            : ['set'];

        if (!in_array($operation, $allowedOperations, true)) {
            return [
                'effects' => [],
                'error' => $context . ', Effect ' . $number .
                    ' uses an operation that is not valid for the selected Trait.',
            ];
        }

        $stored = [
            'key' => $key,
            'target_id' => $targetId,
            'trait_name' => (string)$definition['name'],
            'data_type' => $dataType,
            'operation' => $operation,
        ];

        if ($recurring) {
            $interval = $postedEffect['interval_ticks'] ?? '';
            if (
                filter_var($interval, FILTER_VALIDATE_INT) === false ||
                (int)$interval < 1
            ) {
                return [
                    'effects' => [],
                    'error' => $context . ', Effect ' . $number .
                        ' Every value must be at least 1 tick.',
                ];
            }
            $stored['interval_ticks'] = (int)$interval;
        }

        if ($dataType === 'boolean') {
            $raw = strtolower(trim((string)($postedEffect['value'] ?? '')));
            if (!in_array($raw, ['0', '1', 'true', 'false'], true)) {
                return [
                    'effects' => [],
                    'error' => $context . ', Effect ' . $number .
                        ' must set the selected boolean Trait to True or False.',
                ];
            }

            $stored['value_mode'] = 'fixed';
            $stored['value'] = ($raw === '1' || $raw === 'true') ? 1 : 0;
            $effects[] = $stored;
            continue;
        }

        $valueMode = strtolower(trim((string)($postedEffect['value_mode'] ?? 'fixed')));
        if (!in_array($valueMode, ['fixed', 'random'], true)) {
            return [
                'effects' => [],
                'error' => $context . ', Effect ' . $number .
                    ' Value Type must be Fixed or Random Min–Max.',
            ];
        }

        $percentOperation = in_array(
            $operation,
            ['subtract_percent_current', 'subtract_percent_max', 'add_percent_max'],
            true
        );

        $stored['value_mode'] = $valueMode;

        if ($valueMode === 'random') {
            $minRaw = trim((string)($postedEffect['value_min'] ?? ''));
            $maxRaw = trim((string)($postedEffect['value_max'] ?? ''));

            if (
                $minRaw === '' ||
                $maxRaw === '' ||
                !is_numeric($minRaw) ||
                !is_numeric($maxRaw)
            ) {
                return [
                    'effects' => [],
                    'error' => $context . ', Effect ' . $number .
                        ' Random Min–Max requires numeric values.',
                ];
            }

            $minimum = (float)$minRaw;
            $maximum = (float)$maxRaw;

            if ($minimum > $maximum) {
                return [
                    'effects' => [],
                    'error' => $context . ', Effect ' . $number .
                        ' Random Min cannot be greater than Max.',
                ];
            }

            if ($percentOperation && $minimum < 0) {
                return [
                    'effects' => [],
                    'error' => $context . ', Effect ' . $number .
                        ' percentage values cannot be negative.',
                ];
            }

            $stored['value_min'] = gameplayEffectNormalizeNumber($minimum);
            $stored['value_max'] = gameplayEffectNormalizeNumber($maximum);
        } else {
            $valueRaw = trim((string)($postedEffect['value'] ?? ''));
            if ($valueRaw === '' || !is_numeric($valueRaw)) {
                return [
                    'effects' => [],
                    'error' => $context . ', Effect ' . $number .
                        ' requires a numeric value.',
                ];
            }

            $value = (float)$valueRaw;
            if ($percentOperation && $value < 0) {
                return [
                    'effects' => [],
                    'error' => $context . ', Effect ' . $number .
                        ' percentage values cannot be negative.',
                ];
            }

            $stored['value'] = gameplayEffectNormalizeNumber($value);
        }

        $effects[] = $stored;
    }

    return [
        'effects' => $effects,
        'error' => '',
    ];
}


function gameplayBuildStatusLifecycleFromPost(
    PDO $pdo,
    int $gameId,
    $postedLifecycle
): array {
    $postedLifecycle = is_array($postedLifecycle)
        ? $postedLifecycle
        : [];

    $mode = strtolower(trim((string)($postedLifecycle['mode'] ?? 'manual')));

    if (!in_array($mode, ['manual', 'progression'], true)) {
        return [
            'lifecycle' => null,
            'editor' => $postedLifecycle,
            'error' => 'Status Progression Mode must be Manual or Timed Stages.',
        ];
    }

    if ($mode === 'manual') {
        return [
            'lifecycle' => null,
            'editor' => [
                'mode' => 'manual',
                'stages' => [],
            ],
            'error' => '',
        ];
    }

    $postedStages = isset($postedLifecycle['stages']) &&
        is_array($postedLifecycle['stages'])
            ? array_values($postedLifecycle['stages'])
            : [];

    if ($postedStages === []) {
        return [
            'lifecycle' => null,
            'editor' => $postedLifecycle,
            'error' => 'Timed Status progression needs at least one Stage.',
        ];
    }

    $stageKeys = [];
    $stages = [];

    foreach ($postedStages as $stageIndex => $postedStage) {
        if (!is_array($postedStage)) {
            continue;
        }

        $stageNumber = $stageIndex + 1;
        $key = gameplayStatusLifecycleNormalizeKey(
            (string)($postedStage['key'] ?? '')
        );

        if (
            $key === '' ||
            preg_match('/^[a-z][a-z0-9_]{0,47}$/', $key) !== 1
        ) {
            return [
                'lifecycle' => null,
                'editor' => $postedLifecycle,
                'error' =>
                    'Status Stage ' . $stageNumber .
                    ' has an invalid internal key. Remove and re-add that Stage.',
            ];
        }

        if (isset($stageKeys[$key])) {
            return [
                'lifecycle' => null,
                'editor' => $postedLifecycle,
                'error' => 'Status Stage keys must be unique.',
            ];
        }

        $name = trim((string)($postedStage['name'] ?? ''));
        if ($name === '') {
            return [
                'lifecycle' => null,
                'editor' => $postedLifecycle,
                'error' => 'Status Stage ' . $stageNumber . ' needs a Stage Name.',
            ];
        }

        $nameLength = function_exists('mb_strlen')
            ? mb_strlen($name, 'UTF-8')
            : strlen($name);

        if ($nameLength > 80) {
            return [
                'lifecycle' => null,
                'editor' => $postedLifecycle,
                'error' => 'Status Stage ' . $stageNumber . ' name must be 80 characters or fewer.',
            ];
        }

        $durationMode = strtolower(trim((string)($postedStage['duration_mode'] ?? 'fixed')));
        if (!in_array($durationMode, ['fixed', 'random'], true)) {
            return [
                'lifecycle' => null,
                'editor' => $postedLifecycle,
                'error' => 'Status Stage ' . $stageNumber . ' has an invalid Duration Mode.',
            ];
        }

        if ($durationMode === 'fixed') {
            $value = $postedStage['duration_value'] ?? '';
            if (
                filter_var($value, FILTER_VALIDATE_INT) === false ||
                (int)$value < 1
            ) {
                return [
                    'lifecycle' => null,
                    'editor' => $postedLifecycle,
                    'error' => 'Status Stage ' . $stageNumber . ' Fixed Duration must be at least 1 tick.',
                ];
            }

            $duration = [
                'mode' => 'fixed',
                'value' => (int)$value,
            ];
        } else {
            $min = $postedStage['duration_min'] ?? '';
            $max = $postedStage['duration_max'] ?? '';

            if (
                filter_var($min, FILTER_VALIDATE_INT) === false ||
                filter_var($max, FILTER_VALIDATE_INT) === false ||
                (int)$min < 1 ||
                (int)$max < 1 ||
                (int)$min > (int)$max
            ) {
                return [
                    'lifecycle' => null,
                    'editor' => $postedLifecycle,
                    'error' =>
                        'Status Stage ' . $stageNumber .
                        ' Random Duration needs whole-number Min/Max ticks of at least 1, with Min no greater than Max.',
                ];
            }

            $duration = [
                'mode' => 'random',
                'min' => (int)$min,
                'max' => (int)$max,
            ];
        }

        $stageKeys[$key] = true;

        $stages[] = [
            'key' => $key,
            'name' => $name,
            'duration' => $duration,
            '_posted_entry_effects' => isset($postedStage['entry_effects']) &&
                is_array($postedStage['entry_effects'])
                    ? array_values($postedStage['entry_effects'])
                    : [],
            '_posted_tick_effects' => isset($postedStage['tick_effects']) &&
                is_array($postedStage['tick_effects'])
                    ? array_values($postedStage['tick_effects'])
                    : [],
            '_posted_outcomes' => isset($postedStage['outcomes']) &&
                is_array($postedStage['outcomes'])
                    ? array_values($postedStage['outcomes'])
                    : [],
        ];
    }

    if ($stages === []) {
        return [
            'lifecycle' => null,
            'editor' => $postedLifecycle,
            'error' => 'Timed Status progression needs at least one valid Stage.',
        ];
    }

    $storylets = gameplayStatusLifecycleStorylets(
        $pdo,
        $gameId
    );

    /* WAYFARER_STATUS_SUBJECT_EFFECTS_AUTHORING_V89 */
    $subjectTraitCatalog = gameplayStatusLifecycleSubjectTraitCatalog(
        $pdo,
        $gameId
    );

    foreach ($stages as $stageIndex => &$stage) {
        $stageNumber = $stageIndex + 1;

        $entryEffectResult = gameplayStatusLifecycleBuildEffects(
            $stage['_posted_entry_effects'] ?? [],
            $subjectTraitCatalog,
            false,
            'Status Stage ' . $stageNumber . ' On Enter Effects'
        );
        if ($entryEffectResult['error'] !== '') {
            return [
                'lifecycle' => null,
                'editor' => $postedLifecycle,
                'error' => $entryEffectResult['error'],
            ];
        }

        $tickEffectResult = gameplayStatusLifecycleBuildEffects(
            $stage['_posted_tick_effects'] ?? [],
            $subjectTraitCatalog,
            true,
            'Status Stage ' . $stageNumber . ' While in Stage Effects'
        );
        if ($tickEffectResult['error'] !== '') {
            return [
                'lifecycle' => null,
                'editor' => $postedLifecycle,
                'error' => $tickEffectResult['error'],
            ];
        }

        $stage['entry_effects'] = $entryEffectResult['effects'];
        $stage['tick_effects'] = $tickEffectResult['effects'];

        $postedOutcomes = $stage['_posted_outcomes'];
        unset(
            $stage['_posted_entry_effects'],
            $stage['_posted_tick_effects'],
            $stage['_posted_outcomes']
        );

        if ($postedOutcomes === []) {
            return [
                'lifecycle' => null,
                'editor' => $postedLifecycle,
                'error' =>
                    'Status Stage ' . $stageNumber .
                    ' needs at least one Outcome.',
            ];
        }

        $outcomes = [];
        $outcomeKeys = [];
        $chanceTotal = 0;

        foreach ($postedOutcomes as $outcomeIndex => $postedOutcome) {
            if (!is_array($postedOutcome)) {
                continue;
            }

            $outcomeNumber = $outcomeIndex + 1;
            $key = gameplayStatusLifecycleNormalizeKey(
                (string)($postedOutcome['key'] ?? '')
            );

            if (
                $key === '' ||
                preg_match('/^[a-z][a-z0-9_]{0,47}$/', $key) !== 1
            ) {
                return [
                    'lifecycle' => null,
                    'editor' => $postedLifecycle,
                    'error' =>
                        'Status Stage ' . $stageNumber . ', Outcome ' . $outcomeNumber .
                        ' has an invalid internal key. Remove and re-add that Outcome.',
                ];
            }

            if (isset($outcomeKeys[$key])) {
                return [
                    'lifecycle' => null,
                    'editor' => $postedLifecycle,
                    'error' =>
                        'Status Stage ' . $stageNumber .
                        ' has duplicate Outcome keys.',
                ];
            }

            $label = trim((string)($postedOutcome['label'] ?? ''));
            if ($label === '') {
                return [
                    'lifecycle' => null,
                    'editor' => $postedLifecycle,
                    'error' =>
                        'Status Stage ' . $stageNumber . ', Outcome ' . $outcomeNumber .
                        ' needs an Outcome Name.',
                ];
            }

            $chance = $postedOutcome['chance'] ?? '';
            if (
                filter_var($chance, FILTER_VALIDATE_INT) === false ||
                (int)$chance < 1 ||
                (int)$chance > 100
            ) {
                return [
                    'lifecycle' => null,
                    'editor' => $postedLifecycle,
                    'error' =>
                        'Status Stage ' . $stageNumber . ', Outcome ' . $outcomeNumber .
                        ' Chance must be a whole number from 1 to 100.',
                ];
            }
            $chance = (int)$chance;
            $chanceTotal += $chance;

            $result = strtolower(trim((string)($postedOutcome['result'] ?? 'inactive')));
            if (
                !in_array($result, ['inactive', 'stay'], true) &&
                preg_match('/^stage:([a-z][a-z0-9_]{0,47})$/', $result, $match) !== 1
            ) {
                return [
                    'lifecycle' => null,
                    'editor' => $postedLifecycle,
                    'error' =>
                        'Status Stage ' . $stageNumber . ', Outcome ' . $outcomeNumber .
                        ' has an invalid Result.',
                ];
            }

            if (
                strpos($result, 'stage:') === 0 &&
                !isset($stageKeys[substr($result, 6)])
            ) {
                return [
                    'lifecycle' => null,
                    'editor' => $postedLifecycle,
                    'error' =>
                        'Status Stage ' . $stageNumber . ', Outcome ' . $outcomeNumber .
                        ' points to a Stage that no longer exists.',
                ];
            }

            $presentation = strtolower(trim((string)($postedOutcome['presentation'] ?? 'silent')));
            if (!in_array($presentation, ['silent', 'storylet'], true)) {
                return [
                    'lifecycle' => null,
                    'editor' => $postedLifecycle,
                    'error' =>
                        'Status Stage ' . $stageNumber . ', Outcome ' . $outcomeNumber .
                        ' has an invalid Presentation Mode.',
                ];
            }

            $storyletId = 0;
            if ($presentation === 'storylet') {
                $storyletId = (int)($postedOutcome['storylet_id'] ?? 0);
                if ($storyletId <= 0 || !isset($storylets[$storyletId])) {
                    return [
                        'lifecycle' => null,
                        'editor' => $postedLifecycle,
                        'error' =>
                            'Status Stage ' . $stageNumber . ', Outcome ' . $outcomeNumber .
                            ' must select a root Storylet from this Game.',
                    ];
                }
            }

            $outcomeEffectResult = gameplayStatusLifecycleBuildEffects(
                $postedOutcome['effects'] ?? [],
                $subjectTraitCatalog,
                false,
                'Status Stage ' . $stageNumber . ', Outcome ' . $outcomeNumber . ' Effects'
            );

            if ($outcomeEffectResult['error'] !== '') {
                return [
                    'lifecycle' => null,
                    'editor' => $postedLifecycle,
                    'error' => $outcomeEffectResult['error'],
                ];
            }

            $outcomeKeys[$key] = true;

            $outcomes[] = [
                'key' => $key,
                'label' => $label,
                'chance' => $chance,
                'result' => $result,
                'effects' => $outcomeEffectResult['effects'],
                'presentation' => $presentation,
                'storylet_id' => $presentation === 'storylet'
                    ? $storyletId
                    : null,
            ];
        }

        if ($outcomes === []) {
            return [
                'lifecycle' => null,
                'editor' => $postedLifecycle,
                'error' => 'Status Stage ' . $stageNumber . ' needs at least one valid Outcome.',
            ];
        }

        if ($chanceTotal !== 100) {
            return [
                'lifecycle' => null,
                'editor' => $postedLifecycle,
                'error' =>
                    'Status Stage ' . $stageNumber .
                    ' Outcome chances must total exactly 100%. Current total: ' .
                    $chanceTotal . '%.',
            ];
        }

        $stage['outcomes'] = $outcomes;
    }
    unset($stage);

    $lifecycle = [
        'mode' => 'progression',
        'stages' => $stages,
    ];

    return [
        'lifecycle' => $lifecycle,
        'editor' => $lifecycle,
        'error' => '',
    ];
}



==============================================================================
FILE: includes/gameplay/storylet-bindings.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Storylet Bindings — authoring
| WAYFARER_STORYLET_BINDINGS_V79
| WAYFARER_STORYLET_BINDING_UI_V83
|--------------------------------------------------------------------------
|
| A Binding selects one runtime subject when a Storylet is entered. A Party
| binding may resolve to a named Player Character or an authored Character Entity.
| The same resolved subject is reused by every binding-aware Effect and narrative
| placeholders for that Storylet occurrence.
|
| V79 selectors:
|   random_party_character
|   random_possessed_item
|
*/

function gameplayStoryletBindingSelectorOptions(): array
{
    return [
        'random_party_character' =>
            'Random Party Member',
        'random_possessed_item' =>
            'Random Possessed Item',
    ];
}


function gameplayStoryletBindingNormalizeKey(
    string $value
): string {
    return strtolower(
        trim($value)
    );
}


function gameplayStoryletBindingNormalizeTraitName(
    string $value
): string {
    $value =
        trim(
            preg_replace(
                '/\s+/u',
                ' ',
                $value
            ) ?? $value
        );

    if (function_exists('mb_strtolower')) {
        return mb_strtolower(
            $value,
            'UTF-8'
        );
    }

    return strtolower($value);
}


function gameplayStoryletBindingNamedTraitId(
    string $traitName
): string {
    return
        'binding_name_' .
        bin2hex(
            gameplayStoryletBindingNormalizeTraitName(
                $traitName
            )
        );
}


function gameplayBuildStoryletBindingsFromPost(
    $postedBindings
): array {
    $bindings = [];
    $error = '';

    if ($postedBindings === null || $postedBindings === '') {
        return [
            'bindings' => [],
            'error' => '',
        ];
    }

    if (!is_array($postedBindings)) {
        return [
            'bindings' => [],
            'error' =>
                'Storylet Bindings must be a list.',
        ];
    }

    $selectors =
        gameplayStoryletBindingSelectorOptions();

    $seen = [];

    foreach (
        array_values($postedBindings)
        as $index => $row
    ) {
        if (!is_array($row)) {
            continue;
        }

        $key =
            gameplayStoryletBindingNormalizeKey(
                (string)(
                    $row['key']
                    ?? ''
                )
            );

        $label =
            trim(
                (string)(
                    $row['label']
                    ?? ''
                )
            );

        $selector =
            strtolower(
                trim(
                    (string)(
                        $row['selector']
                        ?? ''
                    )
                )
            );

        /*
         * Ignore a completely blank newly-added row.
         */
        if (
            $key === '' &&
            $label === '' &&
            $selector === ''
        ) {
            continue;
        }

        $rowNumber =
            $index + 1;

        if (
            $key === '' ||
            preg_match(
                '/^[a-z][a-z0-9_]{0,31}$/',
                $key
            ) !== 1
        ) {
            $error =
                'Binding ' .
                $rowNumber .
                ' needs a Key beginning with a letter and containing only lowercase letters, numbers, and underscores (maximum 32 characters).';
            break;
        }

        if (isset($seen[$key])) {
            $error =
                'Binding Keys must be unique. "' .
                $key .
                '" is used more than once.';
            break;
        }

        if ($label === '') {
            $error =
                'Binding ' .
                $rowNumber .
                ' needs a Binding Name.';
            break;
        }

        $labelLength =
            function_exists('mb_strlen')
                ? mb_strlen(
                    $label,
                    'UTF-8'
                )
                : strlen($label);

        if ($labelLength > 80) {
            $error =
                'Binding ' .
                $rowNumber .
                ' Binding Name must be 80 characters or fewer.';
            break;
        }

        if (!isset($selectors[$selector])) {
            $error =
                'Binding ' .
                $rowNumber .
                ' must use a valid Selection Rule.';
            break;
        }

        $seen[$key] = true;

        $bindings[] = [
            'key' => $key,
            'label' => $label,
            'selector' => $selector,
        ];
    }

    return [
        'bindings' => $bindings,
        'error' => $error,
    ];
}


function gameplayStoryletBindingTraitCatalog(
    PDO $pdo,
    int $gameId,
    string $entityType
): array {
    $entityType =
        strtolower(
            trim($entityType)
        );

    if (
        $gameId <= 0 ||
        !in_array(
            $entityType,
            ['character', 'item'],
            true
        )
    ) {
        return [];
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                config
            FROM wf_entities
            WHERE game_id = ?
              AND status = 'active'
              AND LOWER(entity_type) = ?
            ORDER BY id
            "
        );

    $stmt->execute([
        $gameId,
        $entityType,
    ]);

    $catalog = [];

    foreach (
        $stmt->fetchAll(PDO::FETCH_ASSOC)
        as $row
    ) {
        $config =
            json_decode(
                (string)(
                    $row['config']
                    ?? ''
                ),
                true
            );

        if (!is_array($config)) {
            $config = [];
        }

        $traits =
            isset($config['traits']) &&
            is_array($config['traits'])
                ? $config['traits']
                : [];

        foreach ($traits as $trait) {
            if (
                !is_array($trait) ||
                (
                    array_key_exists(
                        'active',
                        $trait
                    ) &&
                    !$trait['active']
                ) ||
                !empty($trait['system'])
            ) {
                continue;
            }

            $name =
                trim(
                    (string)(
                        $trait['name']
                        ?? ''
                    )
                );

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

            $type =
                strtolower(
                    trim(
                        (string)(
                            $trait['type']
                            ?? 'text'
                        )
                    )
                );

            if ($type === 'binary') {
                $type = 'boolean';
            }

            if (
                !in_array(
                    $type,
                    ['number', 'boolean'],
                    true
                )
            ) {
                continue;
            }

            $normalizedName =
                gameplayStoryletBindingNormalizeTraitName(
                    $name
                );

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

            if (!isset($catalog[$normalizedName])) {
                $catalog[$normalizedName] = [
                    'name' => $name,
                    'data_type' => $type,
                    'conflict' => false,
                ];
                continue;
            }

            if (
                $catalog[$normalizedName]['data_type'] !==
                $type
            ) {
                /*
                 * A random binding cannot safely target one logical Trait name
                 * when different Entities define it with incompatible types.
                 */
                $catalog[$normalizedName]['conflict'] =
                    true;
            }
        }
    }

    foreach ($catalog as $name => $definition) {
        if (!empty($definition['conflict'])) {
            unset($catalog[$name]);
        }
    }

    uasort(
        $catalog,
        static function (
            array $a,
            array $b
        ): int {
            return strcasecmp(
                (string)$a['name'],
                (string)$b['name']
            );
        }
    );

    return $catalog;
}


function gameplayStoryletBindingEffectTargets(
    PDO $pdo,
    int $gameId,
    array $bindings
): array {
    $targets = [];

    /* WAYFARER_PARTY_BINDINGS_V85 */
    $partyTraits =
        function_exists(
            'gameplayPartyTraitCatalog'
        )
            ? gameplayPartyTraitCatalog(
                $pdo,
                $gameId
            )
            : gameplayStoryletBindingTraitCatalog(
                $pdo,
                $gameId,
                'character'
            );

    $itemTraits =
        gameplayStoryletBindingTraitCatalog(
            $pdo,
            $gameId,
            'item'
        );

    foreach ($bindings as $binding) {
        if (!is_array($binding)) {
            continue;
        }

        $key =
            gameplayStoryletBindingNormalizeKey(
                (string)(
                    $binding['key']
                    ?? ''
                )
            );

        $label =
            trim(
                (string)(
                    $binding['label']
                    ?? $key
                )
            );

        $selector =
            strtolower(
                trim(
                    (string)(
                        $binding['selector']
                        ?? ''
                    )
                )
            );

        if (
            $key === '' ||
            preg_match(
                '/^[a-z][a-z0-9_]{0,31}$/',
                $key
            ) !== 1
        ) {
            continue;
        }

        $scope =
            'binding:' .
            $key;

        $group =
            'Binding — ' .
            (
                $label !== ''
                    ? $label
                    : $key
            );

        if ($selector === 'random_party_character') {
            $targetId =
                'sys_character_party_member';

            $targetKey =
                $scope .
                ':trait:' .
                $targetId;

            $targets[$targetKey] = [
                'scope' => $scope,
                'target_scope' => $scope,
                'target_type' => 'trait',
                'target_id' => $targetId,
                'target_system_key' => 'party_member',
                'trait_type' => 'boolean',
                'data_type' => 'boolean',
                'semantic_type' => 'storylet_binding_trait',
                'condition_operators' => [
                    'equals',
                    'not_equals',
                ],
                'effect_operations' => [
                    'set',
                ],
                'supports_random' => false,
                'group' => $group,
                'label' => 'Party Membership',
                'helper' => 'Random Party Member',
                /* Legacy Entity-only property: keep saved Effects editable. */
                'effect_hidden' => true,
                'hierarchy' => [
                    [
                        'key' => 'storylet_binding',
                        'label' => 'Storylet Binding',
                    ],
                    [
                        'key' => $scope,
                        'label' => $label !== '' ? $label : $key,
                    ],
                    [
                        'key' => 'party_membership',
                        'label' => 'Party Membership',
                    ],
                ],
            ];

            foreach (
                $partyTraits
                as $trait
            ) {
                $namedTargetId =
                    gameplayStoryletBindingNamedTraitId(
                        (string)$trait['name']
                    );

                $targetKey =
                    $scope .
                    ':trait:' .
                    $namedTargetId;

                $dataType =
                    (string)$trait['data_type'];

                $targets[$targetKey] = [
                    'scope' => $scope,
                    'target_scope' => $scope,
                    'target_type' => 'trait',
                    'target_id' => $namedTargetId,
                    'trait_type' => $dataType,
                    'data_type' => $dataType,
                    'semantic_type' => 'storylet_binding_named_trait',
                    'condition_operators' =>
                        $dataType === 'boolean'
                            ? [
                                'equals',
                                'not_equals',
                            ]
                            : wayfarerConditionOperators(),
                    'effect_operations' =>
                        $dataType === 'number'
                            ? [
                                'set',
                                'add',
                                'subtract',
                            ]
                            : [
                                'set',
                            ],
                    'supports_random' =>
                        $dataType === 'number',
                    'group' => $group,
                    'label' =>
                        (string)$trait['name'],
                    'helper' =>
                        'Random Party Member',
                    'hierarchy' => [
                        [
                            'key' => 'storylet_binding',
                            'label' => 'Storylet Binding',
                        ],
                        [
                            'key' => $scope,
                            'label' => $label !== '' ? $label : $key,
                        ],
                        [
                            'key' => $namedTargetId,
                            'label' => (string)$trait['name'],
                        ],
                    ],
                ];
            }

            /* WAYFARER_STATUS_BINDING_TARGETS_V87 */
            if (function_exists('gameplayStatusDefinitions')) {
                foreach (
                    gameplayStatusDefinitions(
                        $pdo,
                        $gameId,
                        true
                    )
                    as $statusDefinition
                ) {
                    $statusId =
                        (int)($statusDefinition['id'] ?? 0);
                    $statusName =
                        trim((string)($statusDefinition['name'] ?? ''));

                    if ($statusId <= 0 || $statusName === '') {
                        continue;
                    }

                    $statusTargetKey =
                        $scope .
                        ':status:' .
                        $statusId;

                    $targets[$statusTargetKey] = [
                        'scope' => $scope,
                        'target_scope' => $scope,
                        'target_type' => 'status',
                        'target_id' => (string)$statusId,
                        'trait_type' => 'boolean',
                        'data_type' => 'boolean',
                        'semantic_type' => 'status',
                        'condition_operators' => [
                            'equals',
                            'not_equals',
                        ],
                        'effect_operations' => [
                            'set',
                        ],
                        'supports_random' => false,
                        'value_options' => [
                            '0' => 'Inactive',
                            '1' => 'Active',
                        ],
                        'group' => $group,
                        'label' => 'Status — ' . $statusName,
                        'helper' => 'Persistent Status on the selected Party Member',
                        'hierarchy' => [
                            [
                                'key' => 'storylet_binding',
                                'label' => 'Storylet Binding',
                            ],
                            [
                                'key' => $scope,
                                'label' => $label !== '' ? $label : $key,
                            ],
                            [
                                'key' => 'status:' . $statusId,
                                'label' => 'Status — ' . $statusName,
                            ],
                        ],
                    ];
                }
            }

            continue;
        }

        if ($selector === 'random_possessed_item') {
            $targetId =
                'sys_item_quantity';

            $targetKey =
                $scope .
                ':trait:' .
                $targetId;

            $targets[$targetKey] = [
                'scope' => $scope,
                'target_scope' => $scope,
                'target_type' => 'trait',
                'target_id' => $targetId,
                'target_system_key' => 'quantity',
                'trait_type' => 'number',
                'data_type' => 'number',
                'semantic_type' => 'storylet_binding_trait',
                'condition_operators' =>
                    wayfarerConditionOperators(),
                'effect_operations' => [
                    'set',
                    'add',
                    'subtract',
                ],
                'supports_random' => true,
                'group' => $group,
                'label' => 'Quantity',
                'helper' => 'Random Possessed Item',
                'hierarchy' => [
                    [
                        'key' => 'storylet_binding',
                        'label' => 'Storylet Binding',
                    ],
                    [
                        'key' => $scope,
                        'label' => $label !== '' ? $label : $key,
                    ],
                    [
                        'key' => 'quantity',
                        'label' => 'Quantity',
                    ],
                ],
            ];

            foreach (
                $itemTraits
                as $trait
            ) {
                $namedTargetId =
                    gameplayStoryletBindingNamedTraitId(
                        (string)$trait['name']
                    );

                $targetKey =
                    $scope .
                    ':trait:' .
                    $namedTargetId;

                $dataType =
                    (string)$trait['data_type'];

                $targets[$targetKey] = [
                    'scope' => $scope,
                    'target_scope' => $scope,
                    'target_type' => 'trait',
                    'target_id' => $namedTargetId,
                    'trait_type' => $dataType,
                    'data_type' => $dataType,
                    'semantic_type' => 'storylet_binding_named_trait',
                    'condition_operators' =>
                        $dataType === 'boolean'
                            ? [
                                'equals',
                                'not_equals',
                            ]
                            : wayfarerConditionOperators(),
                    'effect_operations' =>
                        $dataType === 'number'
                            ? [
                                'set',
                                'add',
                                'subtract',
                            ]
                            : [
                                'set',
                            ],
                    'supports_random' =>
                        $dataType === 'number',
                    'group' => $group,
                    'label' =>
                        (string)$trait['name'],
                    'helper' =>
                        'Random Possessed Item',
                    'hierarchy' => [
                        [
                            'key' => 'storylet_binding',
                            'label' => 'Storylet Binding',
                        ],
                        [
                            'key' => $scope,
                            'label' => $label !== '' ? $label : $key,
                        ],
                        [
                            'key' => $namedTargetId,
                            'label' => (string)$trait['name'],
                        ],
                    ],
                ];
            }
        }
    }

    return $targets;
}



==============================================================================
FILE: includes/gameplay/tick-effects-editor.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Shared Tick Effects Editor
|--------------------------------------------------------------------------
|
| WAYFARER_GAMEPLAY_MODULAR_V25
| WAYFARER_CONDITION_EDITOR_V27
| WAYFARER_TICK_EFFECT_BRANCHES_V28
|
| A Tick Effect owns one target and one or more ordered result branches.
| The first matching result will win when runtime enforcement is wired.
|
*/

$gameplayTickEffects =
    $gameplayTickEffects
    ?? [];

$gameplayGameTraitTargets =
    $gameplayGameTraitTargets
    ?? [];

$gameplayScopeTraitTargets =
    $gameplayScopeTraitTargets
    ?? [];

$gameplayScopeLabel =
    $gameplayScopeLabel
    ?? '';

$gameplayScopeKey =
    $gameplayScopeKey
    ?? '';

$gameplayAllowNavigation =
    !empty(
        $gameplayAllowNavigation
    );

$gameplayNavigationType =
    (string)(
        $gameplayNavigationType
        ?? ''
    );

$gameplayDescription =
    (string)(
        $gameplayDescription
        ?? 'These effects are applied on each gameplay tick.'
    );

$gameplayEmbedded =
    !empty(
        $gameplayEmbedded
    );


/*
 * Conditions may inspect active traits regardless of whether the trait is
 * numeric. Effect targets remain restricted by the existing effect-target
 * rules.
 */
if (
    !isset(
        $gameplayConditionTargets
    ) ||
    !is_array(
        $gameplayConditionTargets
    )
) {

    $gameplayConditionTargets =
        isset($pdo, $gameId) && $pdo instanceof PDO
            ? gameplayRuntimeStateTargets($pdo, (int)$gameId)
            : [];
}

/* WAYFARER_LIVE_LOCATION_ANCHORS_V76 */
if (
    isset($pdo, $gameId) &&
    $pdo instanceof PDO &&
    function_exists(
        'gameplayNavigationConditionTargets'
    )
) {
    $gameplayConditionTargets =
        array_replace(
            $gameplayConditionTargets,
            gameplayNavigationConditionTargets(
                $pdo,
                (int)$gameId
            ),
            function_exists(
                'gameplayTimeConditionTargets'
            )
                ? gameplayTimeConditionTargets(
                    $pdo,
                    (int)$gameId
                )
                : []
        );
}


/* WAYFARER_UNIVERSAL_TICK_TARGET_EDITOR_V56 */
$gameplayTargetCatalog =
    isset($gameplayTargetCatalog) &&
    is_array($gameplayTargetCatalog)
        ? $gameplayTargetCatalog
        : [];

if (
    !$gameplayTargetCatalog &&
    isset($pdo, $gameId) &&
    $pdo instanceof PDO
) {
    $gameplayTargetCatalog =
        gameplayRuntimeStateTargets(
            $pdo,
            (int)$gameId
        );
}
$renderTickEffectTargetOptions =
    function (
        array $tickEffect = []
    ) use (
        $gameplayAllowNavigation,
        $gameplayGameTraitTargets,
        $gameplayScopeKey,
        $gameplayScopeLabel,
        $gameplayScopeTraitTargets,
        $gameplayTargetCatalog
    ): void {

        echo '<option value="">Select target...</option>';

        if ($gameplayTargetCatalog) {
            $selectedScope =
                (string)(
                    $tickEffect['target_scope']
                    ?? ''
                );

            $selectedType =
                (string)(
                    $tickEffect['target_type']
                    ?? ''
                );

            $selectedId =
                (string)(
                    $tickEffect['target_id']
                    ?? ''
                );

            $selectedKey =
                $selectedScope .
                ':' .
                $selectedType .
                ':' .
                $selectedId;


            /*
             * WAYFARER_POSTED_TICK_TARGET_PRESERVE_V67
             *
             * Failed POSTs are intentionally re-rendered from their submitted
             * rows. Submitted rows use the form field "target" rather than the
             * canonical stored target_scope / target_type / target_id fields.
             */
            $postedSelectedKey =
                trim(
                    (string)(
                        $tickEffect['target']
                        ?? ''
                    )
                );

            if (
                $postedSelectedKey !== '' &&
                isset(
                    $gameplayTargetCatalog[
                        $postedSelectedKey
                    ]
                )
            ) {
                $selectedKey =
                    $postedSelectedKey;
            }


            /*
             * WAYFARER_LEGACY_TICK_TARGET_SELECTION_V65
             *
             * Pre-universal-target Tick Effects did not always store
             * target_type. Infer the canonical catalog key for display so the
             * existing Effect remains selected instead of silently posting the
             * blank first option on the next Region save.
             */
            if (
                $selectedScope !== '' &&
                $selectedType === '' &&
                $selectedId !== ''
            ) {

                foreach (
                    $gameplayTargetCatalog
                    as $catalogKey => $catalogTarget
                ) {

                    if (!is_array($catalogTarget)) {
                        continue;
                    }

                    if (
                        (string)(
                            $catalogTarget[
                                'target_scope'
                            ]
                            ?? ''
                        ) ===
                            $selectedScope
                        &&
                        (string)(
                            $catalogTarget[
                                'target_id'
                            ]
                            ?? ''
                        ) ===
                            $selectedId
                    ) {
                        $selectedKey =
                            (string)$catalogKey;

                        break;
                    }
                }
            }

            $grouped = [];

            foreach (
                $gameplayTargetCatalog
                as $value => $target
            ) {
                if (!is_array($target)) {
                    continue;
                }

                if (
                    !empty($target['effect_hidden']) &&
                    $value !== $selectedKey
                ) {
                    continue;
                }

                $group =
                    (string)(
                        $target['group']
                        ?? 'Targets'
                    );

                if (!isset($grouped[$group])) {
                    $grouped[$group] = [];
                }

                $grouped[$group][$value] =
                    $target;
            }

            foreach ($grouped as $group => $options) {
                echo '<optgroup label="' .
                    builderEscape($group) .
                    '">';

                foreach ($options as $value => $target) {
                    echo '<option value="' .
                        builderEscape($value) .
                        '"' .
                        (
                            $value === $selectedKey
                                ? ' selected'
                                : ''
                        ) .
                        '>' .
                        builderEscape(
                            (string)(
                                $target['label']
                                ?? $value
                            ) .
                            (
                                trim((string)($target['helper'] ?? '')) !== ''
                                    ? ' — ' . trim((string)$target['helper'])
                                    : ''
                            )
                        ) .
                        '</option>';
                }

                echo '</optgroup>';
            }

            return;
        }




        if ($gameplayAllowNavigation) {

            echo '<optgroup label="Navigation">';

            echo '<option value="navigation:position" ' .
                'data-linear-navigation-target' .
                (
                    gameplayTickEffectSelected(
                        $tickEffect,
                        'navigation',
                        'position'
                    )
                        ? ' selected'
                        : ''
                ) .
                '>';

            echo 'Navigation → Position';

            echo '</option>';
            echo '</optgroup>';
        }


        if ($gameplayGameTraitTargets) {

            echo '<optgroup label="Game Traits">';

            foreach (
                $gameplayGameTraitTargets
                as $targetTrait
            ) {

                echo '<option value="game:' .
                    builderEscape(
                        $targetTrait['id']
                    ) .
                    '"' .
                    (
                        gameplayTickEffectSelected(
                            $tickEffect,
                            'game',
                            $targetTrait['id']
                        )
                            ? ' selected'
                            : ''
                    ) .
                    '>';

                echo 'Game → ' .
                    builderEscape(
                        $targetTrait['name']
                    );

                echo '</option>';
            }

            echo '</optgroup>';
        }


        if (
            $gameplayScopeKey !== '' &&
            $gameplayScopeTraitTargets
        ) {

            echo '<optgroup label="' .
                builderEscape(
                    $gameplayScopeLabel
                ) .
                ' Traits">';

            foreach (
                $gameplayScopeTraitTargets
                as $targetTrait
            ) {

                echo '<option value="' .
                    builderEscape(
                        $gameplayScopeKey
                    ) .
                    ':' .
                    builderEscape(
                        $targetTrait['id']
                    ) .
                    '"' .
                    (
                        gameplayTickEffectSelected(
                            $tickEffect,
                            $gameplayScopeKey,
                            $targetTrait['id']
                        )
                            ? ' selected'
                            : ''
                    ) .
                    '>';

                echo builderEscape(
                    $gameplayScopeLabel
                ) .
                    ' → ' .
                    builderEscape(
                        $targetTrait['name']
                    );

                echo '</option>';
            }

            echo '</optgroup>';
        }
    };


$renderBranchResultFields =
    function (
        array $branch,
        string $name
    ): void {

        $operation =
            gameplayTickEffectBranchOperation(
                $branch
            );

        $value =
            gameplayTickEffectBranchValue(
                $branch
            );

        $valueMode =
            gameplayTickEffectBranchValueMode(
                $branch
            );

        $minimum =
            gameplayTickEffectBranchMin(
                $branch
            );

        $maximum =
            gameplayTickEffectBranchMax(
                $branch
            );

        ?>

        <div
            class="builder-tick-result-fields"
            data-tick-initial-value-mode="<?= builderEscape($valueMode) ?>"
            data-tick-initial-min="<?= builderEscape($minimum) ?>"
            data-tick-initial-max="<?= builderEscape($maximum) ?>"
        >

            <label>
                Result
                <select
                    name="<?= builderEscape(
                        $name
                    ) ?>[operation]"
                    data-tick-branch-operation
                >
                    <?php foreach (
                        [
                            'add' => 'Add',
                            'subtract' => 'Subtract',
                            'set' => 'Set',
                            'none' => 'No Change',
                        ]
                        as $operationValue => $operationLabel
                    ): ?>

                        <option
                            value="<?= builderEscape(
                                $operationValue
                            ) ?>"
                            <?= $operation === $operationValue
                                ? 'selected'
                                : '' ?>
                        >
                            <?= builderEscape(
                                $operationLabel
                            ) ?>
                        </option>

                    <?php endforeach; ?>
                </select>
            </label>

            <label
                data-tick-branch-value-wrap
                <?= $operation === 'none'
                    ? 'hidden'
                    : '' ?>
            >
                Value
                <input
                    type="number"
                    step="any"
                    name="<?= builderEscape(
                        $name
                    ) ?>[value]"
                    value="<?= builderEscape(
                        $value
                    ) ?>"
                    <?= $operation === 'none'
                        ? 'disabled'
                        : '' ?>
                >
            </label>

        </div>

        <?php
    };

?>

<section
    data-builder-tick-effects
    <?= $gameplayEmbedded
        ? 'data-tick-effects-embedded="1"'
        : '' ?>
    data-gameplay-scope="<?= builderEscape(
        $gameplayScopeKey
    ) ?>"
    data-navigation-type="<?= builderEscape(
        $gameplayNavigationType
    ) ?>"
>

    <h3>Tick Effects</h3>

    <p>
        <?= builderEscape(
            $gameplayDescription
        ) ?>
    </p>

    <p class="builder-field-help">
        Each Tick Effect controls one target. Its results are checked from top
        to bottom. The first matching result wins within that Tick Effect.
        Separate Tick Effects remain independent.
    </p>

    <div data-tick-effects-list>

        <?php foreach (
            $gameplayTickEffects
            as $tickEffectIndex => $tickEffect
        ): ?>

            <?php
            $tickEffectBranches =
                gameplayTickEffectNormalizeBranches(
                    is_array($tickEffect)
                        ? $tickEffect
                        : []
                );
            ?>

            <div
                class="builder-tick-effect-row"
                data-tick-effect-row
                data-tick-index="<?= (int)$tickEffectIndex ?>"
            >

                <div class="builder-tick-effect-header">

                    <label class="builder-tick-effect-target">
                        Target

                        <select
                            name="tick_effects[<?= (int)$tickEffectIndex ?>][target]"
                            data-tick-effect-target
                        >
                            <?php
                            $renderTickEffectTargetOptions(
                                $tickEffect
                            );
                            ?>
                        </select>
                    </label>

                    <button
                        type="button"
                        class="secondary-button"
                        data-remove-tick-effect
                    >
                        Remove Tick Effect
                    </button>

                </div>


                <div
                    class="builder-tick-result-list"
                    data-tick-branch-list
                >

                    <?php foreach (
                        $tickEffectBranches
                        as $branchIndex => $branch
                    ): ?>

                        <?php
                        $branchName =
                            'tick_effects[' .
                            (int)$tickEffectIndex .
                            '][branches][' .
                            (int)$branchIndex .
                            ']';

                        $isOtherwise =
                            gameplayTickEffectBranchIsOtherwise(
                                $branch
                            );
                        ?>

                        <div
                            class="builder-tick-result-branch<?= $isOtherwise
                                ? ' is-otherwise'
                                : '' ?>"
                            data-tick-effect-branch
                            data-branch-kind="<?= $isOtherwise
                                ? 'otherwise'
                                : 'conditional' ?>"
                        >

                            <input
                                type="hidden"
                                name="<?= builderEscape(
                                    $branchName
                                ) ?>[kind]"
                                value="<?= $isOtherwise
                                    ? 'otherwise'
                                    : 'conditional' ?>"
                                data-tick-branch-kind-input
                            >

                            <div class="builder-tick-result-heading">

                                <strong>
                                    <?= $isOtherwise
                                        ? 'OTHERWISE'
                                        : 'WHEN' ?>
                                </strong>

                                <div class="builder-tick-result-order">

                                    <?php if (!$isOtherwise): ?>

                                        <button
                                            type="button"
                                            class="secondary-button"
                                            data-move-tick-branch-up
                                            title="Move result up"
                                        >
                                            ↑
                                        </button>

                                        <button
                                            type="button"
                                            class="secondary-button"
                                            data-move-tick-branch-down
                                            title="Move result down"
                                        >
                                            ↓
                                        </button>

                                    <?php endif; ?>

                                    <button
                                        type="button"
                                        class="secondary-button"
                                        data-remove-tick-branch
                                    >
                                        Remove Result
                                    </button>

                                </div>

                            </div>


                            <?php if (!$isOtherwise): ?>

                                <div class="builder-tick-result-condition">

                                    <?php

                                    $conditionEditorNode =
                                        $branch['conditions']
                                        ?? null;

                                    $conditionEditorName =
                                        $branchName .
                                        '[conditions]';

                                    $conditionEditorTargets =
                                        $gameplayConditionTargets;

                                    require __DIR__ .
                                        '/condition-editor.php';

                                    ?>

                                </div>

                                <div class="builder-tick-result-then">
                                    <strong>THEN</strong>
                                </div>

                            <?php endif; ?>


                            <?php
                            $renderBranchResultFields(
                                $branch,
                                $branchName
                            );
                            ?>

                        </div>

                    <?php endforeach; ?>

                </div>


                <div class="builder-tick-result-actions">

                    <button
                        type="button"
                        class="secondary-button"
                        data-add-tick-conditional-result
                    >
                        + Add Conditional Result
                    </button>

                    <button
                        type="button"
                        class="secondary-button"
                        data-add-tick-otherwise-result
                    >
                        + Add Otherwise
                    </button>

                </div>

            </div>

        <?php endforeach; ?>

    </div>


    <p>
        <button
            type="button"
            class="secondary-button"
            data-add-tick-effect
        >
            + Add Tick Effect
        </button>
    </p>


    <template data-tick-effect-template>

        <div
            class="builder-tick-effect-row"
            data-tick-effect-row
            data-tick-index="__INDEX__"
        >

            <div class="builder-tick-effect-header">

                <label class="builder-tick-effect-target">
                    Target

                    <select
                        name="tick_effects[__INDEX__][target]"
                        data-tick-effect-target
                    >
                        <?php
                        $renderTickEffectTargetOptions(
                            []
                        );
                        ?>
                    </select>
                </label>

                <button
                    type="button"
                    class="secondary-button"
                    data-remove-tick-effect
                >
                    Remove Tick Effect
                </button>

            </div>


            <div
                class="builder-tick-result-list"
                data-tick-branch-list
            >

                <div
                    class="builder-tick-result-branch is-otherwise"
                    data-tick-effect-branch
                    data-branch-kind="otherwise"
                >

                    <input
                        type="hidden"
                        name="tick_effects[__INDEX__][branches][0][kind]"
                        value="otherwise"
                        data-tick-branch-kind-input
                    >

                    <div class="builder-tick-result-heading">

                        <strong>OTHERWISE</strong>

                        <div class="builder-tick-result-order">

                            <button
                                type="button"
                                class="secondary-button"
                                data-remove-tick-branch
                            >
                                Remove Result
                            </button>

                        </div>

                    </div>

                    <div class="builder-tick-result-fields">

                        <label>
                            Result

                            <select
                                name="tick_effects[__INDEX__][branches][0][operation]"
                                data-tick-branch-operation
                            >
                                <option value="add">Add</option>
                                <option value="subtract">Subtract</option>
                                <option value="set">Set</option>
                                <option value="none">No Change</option>
                            </select>
                        </label>

                        <label data-tick-branch-value-wrap>
                            Value

                            <input
                                type="number"
                                step="any"
                                name="tick_effects[__INDEX__][branches][0][value]"
                            >
                        </label>

                    </div>

                </div>

            </div>


            <div class="builder-tick-result-actions">

                <button
                    type="button"
                    class="secondary-button"
                    data-add-tick-conditional-result
                >
                    + Add Conditional Result
                </button>

                <button
                    type="button"
                    class="secondary-button"
                    data-add-tick-otherwise-result
                >
                    + Add Otherwise
                </button>

            </div>

        </div>

    </template>


    <template data-tick-conditional-branch-template>

        <div
            class="builder-tick-result-branch"
            data-tick-effect-branch
            data-branch-kind="conditional"
        >

            <input
                type="hidden"
                name="tick_effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][kind]"
                value="conditional"
                data-tick-branch-kind-input
            >

            <div class="builder-tick-result-heading">

                <strong>WHEN</strong>

                <div class="builder-tick-result-order">

                    <button
                        type="button"
                        class="secondary-button"
                        data-move-tick-branch-up
                        title="Move result up"
                    >
                        ↑
                    </button>

                    <button
                        type="button"
                        class="secondary-button"
                        data-move-tick-branch-down
                        title="Move result down"
                    >
                        ↓
                    </button>

                    <button
                        type="button"
                        class="secondary-button"
                        data-remove-tick-branch
                    >
                        Remove Result
                    </button>

                </div>

            </div>


            <div
                class="builder-tick-result-condition"
                data-new-branch-condition-editor
            ></div>

            <div class="builder-tick-result-then">
                <strong>THEN</strong>
            </div>

            <div class="builder-tick-result-fields">

                <label>
                    Result

                    <select
                        name="tick_effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][operation]"
                        data-tick-branch-operation
                    >
                        <option value="add">Add</option>
                        <option value="subtract">Subtract</option>
                        <option value="set">Set</option>
                        <option value="none">No Change</option>
                    </select>
                </label>

                <label data-tick-branch-value-wrap>
                    Value

                    <input
                        type="number"
                        step="any"
                        name="tick_effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][value]"
                    >
                </label>

            </div>

        </div>

    </template>


    <template data-tick-otherwise-branch-template>

        <div
            class="builder-tick-result-branch is-otherwise"
            data-tick-effect-branch
            data-branch-kind="otherwise"
        >

            <input
                type="hidden"
                name="tick_effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][kind]"
                value="otherwise"
                data-tick-branch-kind-input
            >

            <div class="builder-tick-result-heading">

                <strong>OTHERWISE</strong>

                <div class="builder-tick-result-order">

                    <button
                        type="button"
                        class="secondary-button"
                        data-remove-tick-branch
                    >
                        Remove Result
                    </button>

                </div>

            </div>

            <div class="builder-tick-result-fields">

                <label>
                    Result

                    <select
                        name="tick_effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][operation]"
                        data-tick-branch-operation
                    >
                        <option value="add">Add</option>
                        <option value="subtract">Subtract</option>
                        <option value="set">Set</option>
                        <option value="none">No Change</option>
                    </select>
                </label>

                <label data-tick-branch-value-wrap>
                    Value

                    <input
                        type="number"
                        step="any"
                        name="tick_effects[__EFFECT_INDEX__][branches][__BRANCH_INDEX__][value]"
                    >
                </label>

            </div>

        </div>

    </template>


    <!-- WAYFARER_DATATYPE_TICK_EFFECT_UI_V58 -->
    <script
        type="application/json"
        data-tick-target-catalog-json
    ><?= json_encode(
        $gameplayTargetCatalog,
        JSON_UNESCAPED_SLASHES |
        JSON_UNESCAPED_UNICODE |
        JSON_HEX_TAG |
        JSON_HEX_AMP |
        JSON_HEX_APOS |
        JSON_HEX_QUOT
    ) ?></script>

    <script
        type="application/json"
        data-condition-targets-json
    ><?= json_encode(
        $gameplayConditionTargets,
        JSON_UNESCAPED_SLASHES |
        JSON_UNESCAPED_UNICODE |
        JSON_HEX_TAG |
        JSON_HEX_AMP |
        JSON_HEX_APOS |
        JSON_HEX_QUOT
    ) ?></script>

</section>



==============================================================================
FILE: includes/gameplay/travel-modifiers.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Game-Level Travel Modifiers
 * WAYFARER_GAME_TRAVEL_MODIFIERS_EDITOR_V73
 * WAYFARER_GENERIC_TRAVEL_MODIFIER_COPY_V74
 * --------------------------------------------------------------------------
 *
 * These are not Tick Effects. They are conditional inputs to the dedicated
 * Linear Travel distance calculation. Conditions are reevaluated every time
 * a normal travel tick is about to move the party.
 */

function wayfarerTravelModifierMakeId(): string
{
    return
        'travel_modifier_' .
        bin2hex(
            random_bytes(8)
        );
}

function wayfarerTravelModifierNormalizeNumber(
    float $value
) {
    if (floor($value) === $value) {
        return (int)$value;
    }

    return $value;
}

function wayfarerBuildGameTravelModifiersFromPost(
    array $postedModifiers,
    array $allowedTargets
): array {
    $modifiers = [];
    $editorModifiers = [];
    $firstError = '';

    foreach (
        array_values($postedModifiers)
        as $index => $postedModifier
    ) {
        if (!is_array($postedModifier)) {
            continue;
        }

        $id =
            trim(
                (string)(
                    $postedModifier['id']
                    ?? ''
                )
            );

        if ($id === '') {
            $id =
                wayfarerTravelModifierMakeId();
        }

        $name =
            trim(
                (string)(
                    $postedModifier['name']
                    ?? ''
                )
            );

        $operation =
            strtolower(
                trim(
                    (string)(
                        $postedModifier['operation']
                        ?? 'add'
                    )
                )
            );

        $valueRaw =
            trim(
                (string)(
                    $postedModifier['value']
                    ?? ''
                )
            );

        $postedConditions =
            $postedModifier['conditions']
            ?? null;

        $conditionResult =
            gameplayBuildConditionNodeFromPost(
                $postedConditions,
                $allowedTargets
            );

        $conditions =
            $conditionResult['node'];

        /*
         * A completely blank newly-added row is ignored. An empty Conditions
         * group is valid and means the modifier always applies.
         */
        if (
            $name === '' &&
            $valueRaw === '' &&
            $conditions === null &&
            $conditionResult['error'] === ''
        ) {
            continue;
        }

        $editorValue =
            is_numeric($valueRaw)
                ? wayfarerTravelModifierNormalizeNumber(
                    (float)$valueRaw
                )
                : $valueRaw;

        $editorModifier = [
            'id' => $id,
            'name' => $name,
            'operation' => $operation,
            'value' => $editorValue,
            'conditions' => $conditions,
        ];

        $editorModifiers[] =
            $editorModifier;

        $label =
            $name !== ''
                ? 'Travel Modifier "' . $name . '"'
                : 'Travel Modifier ' . ($index + 1);

        if (
            $conditionResult['error'] !== '' &&
            $firstError === ''
        ) {
            $firstError =
                $label . ': ' .
                $conditionResult['error'];
            continue;
        }

        if (
            $name === '' &&
            $firstError === ''
        ) {
            $firstError =
                'Each Travel Modifier must have a Name.';
            continue;
        }

        if (
            !in_array(
                $operation,
                ['add', 'subtract'],
                true
            ) &&
            $firstError === ''
        ) {
            $firstError =
                $label .
                ' must use Add or Subtract.';
            continue;
        }

        if (
            !is_numeric($valueRaw) ||
            (float)$valueRaw <= 0
        ) {
            if ($firstError === '') {
                $firstError =
                    $label .
                    ' must use an Amount greater than zero.';
            }
            continue;
        }

        $value =
            wayfarerTravelModifierNormalizeNumber(
                (float)$valueRaw
            );

        $modifiers[] = [
            'id' => $id,
            'name' => $name,
            'operation' => $operation,
            'value' => $value,
            'conditions' => $conditions,
        ];
    }

    return [
        'modifiers' =>
            $firstError === ''
                ? $modifiers
                : [],
        'editor_modifiers' =>
            $editorModifiers,
        'error' =>
            $firstError,
    ];
}

function wayfarerRenderGameTravelModifiersEditor(
    array $modifiers,
    array $conditionTargets
): void {
    $modifiers =
        array_values(
            $modifiers
        );
    ?>

    <section
        data-game-travel-modifiers
        data-next-index="<?= count($modifiers) ?>"
    >
        <!-- WAYFARER_GAME_TRAVEL_MODIFIERS_EDITOR_V73 -->
        <h2>Travel</h2>

        <p class="admin-game-panel-intro">
            Global travel rules follow the party between Regions. Matching modifiers
            adjust a Region's dedicated Base Distance Per Tick whenever a normal
            travel tick moves the player.
        </p>

        <p>
            <small>
                Example: if a Region moves 10 units per tick and a Car adds 5
                while its Conditions are met, that travel tick moves 15 units. These
                modifiers are reevaluated every travel tick and do not produce normal
                Effect feedback.
            </small>
        </p>

        <input
            type="hidden"
            name="travel_modifiers_present"
            value="1"
        >

        <script
            type="application/json"
            data-game-travel-targets-json
        ><?= json_encode(
            $conditionTargets,
            JSON_UNESCAPED_SLASHES |
            JSON_UNESCAPED_UNICODE |
            JSON_HEX_TAG |
            JSON_HEX_AMP |
            JSON_HEX_APOS |
            JSON_HEX_QUOT
        ) ?></script>

        <div data-game-travel-modifier-list>

            <?php foreach (
                $modifiers
                as $index => $modifier
            ): ?>
                <?php
                $modifierName =
                    trim(
                        (string)(
                            $modifier['name']
                            ?? ''
                        )
                    );

                $modifierOperation =
                    strtolower(
                        trim(
                            (string)(
                                $modifier['operation']
                                ?? 'add'
                            )
                        )
                    );

                if (
                    !in_array(
                        $modifierOperation,
                        ['add', 'subtract'],
                        true
                    )
                ) {
                    $modifierOperation =
                        'add';
                }

                $modifierValue =
                    $modifier['value']
                    ?? '';

                $modifierConditions =
                    $modifier['conditions']
                    ?? null;
                ?>

                <fieldset
                    data-game-travel-modifier
                    data-travel-modifier-index="<?= (int)$index ?>"
                >
                    <legend data-game-travel-modifier-legend>
                        <?= builderEscape(
                            $modifierName !== ''
                                ? $modifierName
                                : 'Travel Modifier'
                        ) ?>
                    </legend>

                    <input
                        type="hidden"
                        name="travel_modifiers[<?= (int)$index ?>][id]"
                        value="<?= builderEscape(
                            (string)(
                                $modifier['id']
                                ?? ''
                            )
                        ) ?>"
                    >

                    <p>
                        <label>
                            Name<br>
                            <input
                                type="text"
                                name="travel_modifiers[<?= (int)$index ?>][name]"
                                value="<?= builderEscape($modifierName) ?>"
                                placeholder="Car"
                                data-game-travel-modifier-name
                            >
                        </label>
                    </p>

                    <p>
                        <label>
                            Adjustment<br>
                            <select
                                name="travel_modifiers[<?= (int)$index ?>][operation]"
                            >
                                <option
                                    value="add"
                                    <?= $modifierOperation === 'add'
                                        ? 'selected'
                                        : '' ?>
                                >
                                    Add
                                </option>
                                <option
                                    value="subtract"
                                    <?= $modifierOperation === 'subtract'
                                        ? 'selected'
                                        : '' ?>
                                >
                                    Subtract
                                </option>
                            </select>

                            <input
                                type="number"
                                name="travel_modifiers[<?= (int)$index ?>][value]"
                                value="<?= builderEscape($modifierValue) ?>"
                                min="0.000001"
                                step="any"
                                placeholder="5"
                            >
                        </label>
                        <br>
                        <small>
                            Applied to the current Region's Base Distance Per Tick.
                        </small>
                    </p>

                    <h3>Apply when</h3>
                    <p>
                        <small>
                            No Conditions means this modifier always applies during
                            dedicated Linear Travel.
                        </small>
                    </p>

                    <?php
                    $conditionEditorNode =
                        $modifierConditions;

                    $conditionEditorName =
                        'travel_modifiers[' .
                        $index .
                        '][conditions]';

                    $conditionEditorTargets =
                        $conditionTargets;

                    require __DIR__ .
                        '/condition-editor.php';
                    ?>

                    <p>
                        <button
                            type="button"
                            class="secondary-button"
                            data-remove-game-travel-modifier
                        >
                            Remove Travel Modifier
                        </button>
                    </p>
                </fieldset>

            <?php endforeach; ?>

        </div>

        <p>
            <button
                type="button"
                class="secondary-button"
                data-add-game-travel-modifier
            >
                + Add Travel Modifier
            </button>
        </p>
    </section>

    <?php
}


==============================================================================
FILE: includes/header.php
==============================================================================

<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Untitled Document</title>
</head>

<body>
</body>
</html>



==============================================================================
FILE: includes/traits/editor.php
==============================================================================

<?php
/*
 * Backward-compatible generic Trait editor wrapper.
 * WAYFARER_MULTI_TRAIT_EDITOR_V52
 *
 * Expects $traits.
 */

require_once __DIR__ . '/render.php';

wayfarerRenderTraitEditor(
    is_array($traits ?? null)
        ? $traits
        : [],
    [
        'field_name' => 'traits',
        'editor_id' => 'traits',
        'allowed_surfaces' => [
            'inventory',
            'status',
        ],
        'intro' =>
            'Each authored trait can be shown in Inventory, Status, both, or neither. ' .
            'These settings affect presentation only; hidden traits remain available ' .
            'to gameplay logic.',
    ]
);


==============================================================================
FILE: includes/traits/functions.php
==============================================================================

<?php

/**
 * Build and validate trait definitions from submitted form data.
 *
 * Returns:
 * [
 *     'traits' => [...],
 *     'error'  => ''
 * ]
 */
function buildTraitsFromPost(
    array $postedTraits,
    array $allowedDisplaySurfaces = ['inventory', 'status']
): array {
    $traits = [];
    $error = '';

    foreach ($postedTraits as $postedTrait) {

        $name = trim(
            $postedTrait['name'] ?? ''
        );

        $type =
            $postedTrait['type'] ?? 'number';

        /*
         * WAYFARER_TRAIT_PLAYER_DISPLAY_V41
         *
         * Presentation metadata is independent from runtime trait state.
         */
        $postedDisplaySurfaces =
            $postedTrait['display_surfaces'] ?? [];

        if (!is_array($postedDisplaySurfaces)) {
            $postedDisplaySurfaces = [];
        }

        $displaySurfaces = [];

        $allowedDisplaySurfaces =
            array_values(
                array_intersect(
                    ['inventory', 'status'],
                    $allowedDisplaySurfaces
                )
            );

        foreach ($postedDisplaySurfaces as $surface) {

            $surface = (string)$surface;

            if (
                in_array(
                    $surface,
                    $allowedDisplaySurfaces,
                    true
                ) &&
                !in_array(
                    $surface,
                    $displaySurfaces,
                    true
                )
            ) {
                $displaySurfaces[] =
                    $surface;
            }
        }

        /*
         * WAYFARER_STATUS_TRAIT_DISPLAY_V86
         *
         * Presentation metadata is stored with the Trait definition. Existing
         * Traits that do not have this field remain Number/Value by default.
         */
        $statusDisplay =
            strtolower(
                trim(
                    (string)(
                        $postedTrait['status_display']
                        ?? 'number'
                    )
                )
            );

        if (
            !in_array(
                $statusDisplay,
                ['number', 'bar', 'both'],
                true
            )
        ) {
            $error =
                $name !== ''
                    ? $name . ': invalid Status display mode.'
                    : 'Invalid Status display mode.';
            break;
        }


        // Ignore completely blank rows.
        if ($name === '') {
            continue;
        }


        // Validate type.
        if (!in_array(
            $type,
            ['number', 'boolean'],
            true
        )) {
            $error = 'Invalid trait type.';
            break;
        }


        // Preserve an existing ID.
        // Generate one only for a new trait.
        $traitId = trim(
            $postedTrait['id'] ?? ''
        );

        if ($traitId === '') {
            $traitId =
                'tr_' . bin2hex(random_bytes(8));
        }


		$trait = [
			'id' => $traitId,
			'name' => $name,
    	'type' => $type,
    	'active' =>
        ($postedTrait['active'] ?? '1') === '1',
    	'notes' =>
        trim($postedTrait['notes'] ?? ''),
        'display' => [
            'surfaces' =>
                $displaySurfaces,
            'status_mode' =>
                $statusDisplay,
        ]
		];


        // Boolean
        if ($type === 'boolean') {

            /*
             * Bars are only meaningful for bounded numeric Traits.
             * If an old/cached form submits another mode for a Boolean, retain
             * the Trait and normalize its presentation to Number/Value.
             */
            $trait['display']['status_mode'] =
                'number';

            $trait['initial'] =
                ($postedTrait['initial_boolean'] ?? '0') === '1';
        }


        // Number
        else {

            $min = trim(
                $postedTrait['min'] ?? ''
            );

            $max = trim(
                $postedTrait['max'] ?? ''
            );

            $initial = trim(
                $postedTrait['initial_number'] ?? ''
            );


            if ($min !== '' && !is_numeric($min)) {
                $error =
                    $name .
                    ': minimum must be a number.';
                break;
            }

            if ($max !== '' && !is_numeric($max)) {
                $error =
                    $name .
                    ': maximum must be a number.';
                break;
            }

            if (
                $initial !== '' &&
                !is_numeric($initial)
            ) {
                $error =
                    $name .
                    ': initial value must be a number.';
                break;
            }


            $minValue =
                $min === ''
                    ? null
                    : (float)$min;

            $maxValue =
                $max === ''
                    ? null
                    : (float)$max;

            $initialValue =
                $initial === ''
                    ? 0
                    : (float)$initial;


            if (
                $minValue !== null &&
                $maxValue !== null &&
                $minValue > $maxValue
            ) {
                $error =
                    $name .
                    ': minimum cannot be greater than maximum.';
                break;
            }

            if (
                $minValue !== null &&
                $initialValue < $minValue
            ) {
                $error =
                    $name .
                    ': initial value cannot be less than minimum.';
                break;
            }

            if (
                $maxValue !== null &&
                $initialValue > $maxValue
            ) {
                $error =
                    $name .
                    ': initial value cannot be greater than maximum.';
                break;
            }

            if (
                in_array(
                    $statusDisplay,
                    ['bar', 'both'],
                    true
                ) &&
                (
                    $minValue === null ||
                    $maxValue === null ||
                    $maxValue <= $minValue
                )
            ) {
                $error =
                    $name .
                    ': Bar Status display requires both Minimum and Maximum, ' .
                    'with Maximum greater than Minimum.';
                break;
            }


            $trait['min'] = $minValue;
            $trait['max'] = $maxValue;
            $trait['initial'] = $initialValue;
        }


        $traits[] = $trait;
    }


    return [
        'traits' => $traits,
        'error' => $error
    ];
}


==============================================================================
FILE: includes/traits/render.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Reusable Wayfarer Trait Editor Renderer
 * WAYFARER_MULTI_TRAIT_EDITOR_V52
 * WAYFARER_STATUS_TRAIT_DISPLAY_V86
 * --------------------------------------------------------------------------
 *
 * Options:
 *   field_name        POST collection name (default: traits)
 *   editor_id         unique DOM/editor key
 *   allowed_surfaces  inventory/status display controls to show
 *   intro             explanatory text above the editor
 */

if (!function_exists('wayfarerRenderTraitEditor')) {

    function wayfarerRenderTraitEditor(
        array $traitDefinitions,
        array $options = []
    ): void {

        static $assetsRendered = false;

        $fieldName =
            preg_replace(
                '/[^a-zA-Z0-9_]/',
                '',
                (string)($options['field_name'] ?? 'traits')
            );

        if ($fieldName === '') {
            $fieldName = 'traits';
        }

        $editorId =
            preg_replace(
                '/[^a-zA-Z0-9_-]/',
                '',
                (string)($options['editor_id'] ?? $fieldName)
            );

        if ($editorId === '') {
            $editorId = $fieldName;
        }

        $allowedSurfaces =
            isset($options['allowed_surfaces']) &&
            is_array($options['allowed_surfaces'])
                ? array_values(
                    array_intersect(
                        ['inventory', 'status'],
                        $options['allowed_surfaces']
                    )
                )
                : ['inventory', 'status'];

        $intro =
            trim(
                (string)(
                    $options['intro']
                    ?? 'Traits are authored once and keep independent runtime values.'
                )
            );

        if (!$assetsRendered) {
            $assetsRendered = true;
            ?>
            <style>
                /* WAYFARER_MULTI_TRAIT_EDITOR_V52 */
                .wayfarer-trait-editor .traits-table {
                    border-collapse: collapse;
                    width: 100%;
                    max-width: 1000px;
                    margin-bottom: 12px;
                }

                .wayfarer-trait-editor .traits-table th,
                .wayfarer-trait-editor .traits-table td {
                    border: 1px solid #ccc;
                    padding: 6px;
                    text-align: left;
                    vertical-align: middle;
                }

                .wayfarer-trait-editor .traits-table th {
                    background: #f3f3f3;
                }

                .wayfarer-trait-editor .traits-table input,
                .wayfarer-trait-editor .traits-table select {
                    box-sizing: border-box;
                    width: 100%;
                }

                .wayfarer-trait-editor .traits-table .trait-name {
                    min-width: 180px;
                }

                .wayfarer-trait-editor .traits-table .trait-number {
                    width: 90px;
                }

                .wayfarer-trait-editor .traits-table .trait-actions {
                    width: 80px;
                    text-align: center;
                }

                .wayfarer-trait-editor .traits-table .remove-trait {
                    width: auto;
                }

                .wayfarer-trait-editor .trait-not-applicable {
                    text-align: center;
                    color: #888;
                }

                .wayfarer-trait-editor .trait-player-display {
                    display: flex;
                    align-items: center;
                    gap: 16px;
                    flex-wrap: wrap;
                    margin-top: 8px;
                }

                .wayfarer-trait-editor .trait-player-display > strong {
                    margin-right: 2px;
                }

                .wayfarer-trait-editor .trait-player-display label {
                    display: inline-flex;
                    align-items: center;
                    gap: 5px;
                    white-space: nowrap;
                }

                .wayfarer-trait-editor .traits-table .trait-player-display input[type="checkbox"] {
                    width: auto;
                    margin: 0;
                }

                .wayfarer-trait-editor .trait-player-display-help {
                    flex-basis: 100%;
                    color: #666;
                }

                .wayfarer-trait-editor .trait-status-display-control {
                    display: inline-flex;
                    align-items: center;
                    gap: 6px;
                }

                .wayfarer-trait-editor .traits-table .trait-status-display-control select {
                    width: auto;
                    min-width: 110px;
                }

                .wayfarer-trait-editor .trait-status-display-help {
                    flex-basis: 100%;
                    color: #666;
                }

                .wayfarer-trait-editor .trait-player-display-intro {
                    margin: 0 0 12px;
                    padding: 10px 12px;
                    border: 1px solid #d8dbe2;
                    border-radius: 6px;
                    background: #f6f7f9;
                    color: #404650;
                }
            </style>
            <script
                src="/wayfarer/assets/js/traits.js?v=52"
                defer
            ></script>
            <script
                src="/wayfarer/assets/js/trait-display.js?v=86"
                defer
            ></script>
            <?php
        }

        $surfaceJson =
            htmlspecialchars(
                json_encode(
                    $allowedSurfaces,
                    JSON_UNESCAPED_SLASHES |
                    JSON_UNESCAPED_UNICODE
                ) ?: '[]',
                ENT_QUOTES,
                'UTF-8'
            );

        ?>
        <div
            class="wayfarer-trait-editor"
            data-wayfarer-trait-editor
            data-trait-field-name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>"
            data-trait-editor-id="<?= htmlspecialchars($editorId, ENT_QUOTES, 'UTF-8') ?>"
            data-trait-surfaces="<?= $surfaceJson ?>"
        >
            <p class="trait-player-display-intro">
                <?= htmlspecialchars($intro, ENT_QUOTES, 'UTF-8') ?>
            </p>

            <table class="traits-table">
                <thead>
                    <tr>
                        <th>Name</th>
                        <th>Type</th>
                        <th>Minimum</th>
                        <th>Maximum</th>
                        <th>Initial Value</th>
                        <th>Status</th>
                        <th></th>
                    </tr>
                </thead>

                <tbody data-traits-container>
                    <?php foreach (array_values($traitDefinitions) as $index => $trait): ?>
                        <?php
                        $traitStatusMode =
                            strtolower(
                                trim(
                                    (string)(
                                        $trait['display']['status_mode']
                                        ?? 'number'
                                    )
                                )
                            );

                        if (
                            !in_array(
                                $traitStatusMode,
                                ['number', 'bar', 'both'],
                                true
                            )
                        ) {
                            $traitStatusMode =
                                'number';
                        }

                        $traitStatusBarAvailable =
                            ($trait['type'] ?? 'number') === 'number' &&
                            is_numeric($trait['min'] ?? null) &&
                            is_numeric($trait['max'] ?? null) &&
                            (float)$trait['max'] > (float)$trait['min'];

                        if (
                            !$traitStatusBarAvailable &&
                            $traitStatusMode !== 'number'
                        ) {
                            $traitStatusMode =
                                'number';
                        }
                        ?>
                        <tr class="trait-row" data-trait-index="<?= (int)$index ?>">
                            <td class="trait-name">
                                <input
                                    type="hidden"
                                    name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][id]"
                                    value="<?= htmlspecialchars((string)($trait['id'] ?? ''), ENT_QUOTES, 'UTF-8') ?>"
                                >

                                <input
                                    type="text"
                                    name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][name]"
                                    value="<?= htmlspecialchars((string)($trait['name'] ?? ''), ENT_QUOTES, 'UTF-8') ?>"
                                >
                            </td>

                            <td>
                                <select
                                    name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][type]"
                                    class="trait-type"
                                >
                                    <option value="number" <?= ($trait['type'] ?? 'number') === 'number' ? 'selected' : '' ?>>Number</option>
                                    <option value="boolean" <?= ($trait['type'] ?? '') === 'boolean' ? 'selected' : '' ?>>True / False</option>
                                </select>
                            </td>

                            <td class="trait-number">
                                <span class="trait-number-fields">
                                    <input
                                        type="number"
                                        step="any"
                                        name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][min]"
                                        value="<?= htmlspecialchars((string)($trait['min'] ?? ''), ENT_QUOTES, 'UTF-8') ?>"
                                    >
                                </span>
                                <span class="trait-not-applicable">&mdash;</span>
                            </td>

                            <td class="trait-number">
                                <span class="trait-number-fields">
                                    <input
                                        type="number"
                                        step="any"
                                        name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][max]"
                                        value="<?= htmlspecialchars((string)($trait['max'] ?? ''), ENT_QUOTES, 'UTF-8') ?>"
                                    >
                                </span>
                                <span class="trait-not-applicable">&mdash;</span>
                            </td>

                            <td>
                                <span class="trait-number-initial">
                                    <input
                                        type="number"
                                        step="any"
                                        name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][initial_number]"
                                        value="<?= htmlspecialchars(
                                            (string)(
                                                ($trait['type'] ?? 'number') === 'number'
                                                    ? ($trait['initial'] ?? '')
                                                    : ''
                                            ),
                                            ENT_QUOTES,
                                            'UTF-8'
                                        ) ?>"
                                    >
                                </span>

                                <span class="trait-boolean-initial">
                                    <select name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][initial_boolean]">
                                        <option value="0" <?= empty($trait['initial']) ? 'selected' : '' ?>>False</option>
                                        <option value="1" <?= !empty($trait['initial']) ? 'selected' : '' ?>>True</option>
                                    </select>
                                </span>
                            </td>

                            <td>
                                <select name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][active]">
                                    <option value="1" <?= !array_key_exists('active', $trait) || !empty($trait['active']) ? 'selected' : '' ?>>Active</option>
                                    <option value="0" <?= array_key_exists('active', $trait) && empty($trait['active']) ? 'selected' : '' ?>>Inactive</option>
                                </select>
                            </td>

                            <td class="trait-actions">
                                <button type="button" class="remove-trait">Remove</button>
                            </td>
                        </tr>

                        <tr class="trait-notes-row" data-trait-index="<?= (int)$index ?>">
                            <td colspan="7">
                                <label>
                                    <strong>Notes:</strong>
                                    <input
                                        type="text"
                                        name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][notes]"
                                        value="<?= htmlspecialchars((string)($trait['notes'] ?? ''), ENT_QUOTES, 'UTF-8') ?>"
                                        placeholder="Optional notes about how this trait is used"
                                        style="width: calc(100% - 70px);"
                                    >
                                </label>

                                <input
                                    type="hidden"
                                    name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][display_surfaces_present]"
                                    value="1"
                                >

                                <?php if (!empty($allowedSurfaces)): ?>
                                    <div class="trait-player-display">
                                        <strong>Show to Player:</strong>

                                        <?php foreach ($allowedSurfaces as $surface): ?>
                                            <label>
                                                <input
                                                    type="checkbox"
                                                    name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][display_surfaces][]"
                                                    value="<?= htmlspecialchars($surface, ENT_QUOTES, 'UTF-8') ?>"
                                                    <?= (
                                                        isset($trait['display']['surfaces']) &&
                                                        is_array($trait['display']['surfaces']) &&
                                                        in_array($surface, $trait['display']['surfaces'], true)
                                                    ) ? 'checked' : '' ?>
                                                >
                                                <?= $surface === 'inventory' ? 'Inventory' : 'Status' ?>
                                            </label>
                                        <?php endforeach; ?>

                                        <?php if (
                                            in_array(
                                                'status',
                                                $allowedSurfaces,
                                                true
                                            )
                                        ): ?>
                                            <label class="trait-status-display-control">
                                                <span>Status Display:</span>
                                                <select
                                                    name="<?= htmlspecialchars($fieldName, ENT_QUOTES, 'UTF-8') ?>[<?= (int)$index ?>][status_display]"
                                                    data-trait-status-display
                                                >
                                                    <option
                                                        value="number"
                                                        <?= $traitStatusMode === 'number'
                                                            ? 'selected'
                                                            : '' ?>
                                                    >
                                                        Number
                                                    </option>
                                                    <option
                                                        value="bar"
                                                        <?= $traitStatusMode === 'bar'
                                                            ? 'selected'
                                                            : '' ?>
                                                        <?= !$traitStatusBarAvailable
                                                            ? 'disabled'
                                                            : '' ?>
                                                    >
                                                        Bar
                                                    </option>
                                                    <option
                                                        value="both"
                                                        <?= $traitStatusMode === 'both'
                                                            ? 'selected'
                                                            : '' ?>
                                                        <?= !$traitStatusBarAvailable
                                                            ? 'disabled'
                                                            : '' ?>
                                                    >
                                                        Both
                                                    </option>
                                                </select>
                                            </label>

                                            <small
                                                class="trait-status-display-help"
                                                data-trait-status-display-help
                                            >
                                                Bars require a Number Trait with both Minimum and Maximum.
                                                True / False Traits always display their value.
                                            </small>
                                        <?php endif; ?>

                                        <small class="trait-player-display-help">
                                            Controls where this trait is displayed to the player.
                                            Unchecked traits remain available to gameplay logic.
                                        </small>
                                    </div>
                                <?php endif; ?>
                            </td>
                        </tr>
                    <?php endforeach; ?>
                </tbody>
            </table>

            <p>
                <button type="button" data-add-trait>+ Add Trait</button>
            </p>
        </div>
        <?php
    }
}


==============================================================================
FILE: play/api/presentation.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Presentation API
 * WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40
 * --------------------------------------------------------------------------
 */

declare(strict_types=1);

header(
    'Content-Type: application/json; charset=UTF-8'
);


function wayfarerPresentationRespond(
    int $status,
    array $payload
): void {

    http_response_code(
        $status
    );

    echo json_encode(
        $payload,
        JSON_UNESCAPED_SLASHES |
        JSON_UNESCAPED_UNICODE
    );

    exit;
}


if (
    $_SERVER['REQUEST_METHOD'] !==
    'POST'
) {

    wayfarerPresentationRespond(
        405,
        [
            'ok' =>
                false,

            'error' =>
                'POST required.',
        ]
    );
}


if (
    session_status() !==
    PHP_SESSION_ACTIVE
) {
    session_start();
}


require_once __DIR__ .
    '/../../config/database.php';

require_once __DIR__ .
    '/../includes/runtime.php';


try {

    $rawInput =
        file_get_contents(
            'php://input'
        );

    $input =
        json_decode(
            $rawInput ?: '{}',
            true
        );

    if (!is_array($input)) {

        wayfarerPresentationRespond(
            400,
            [
                'ok' =>
                    false,

                'error' =>
                    'Invalid JSON request.',
            ]
        );
    }


    $csrfToken =
        isset($input['csrf_token'])
            ? (string)$input['csrf_token']
            : '';

    $sessionToken =
        isset(
            $_SESSION[
                'wayfarer_tick_csrf'
            ]
        )
            ? (string)$_SESSION[
                'wayfarer_tick_csrf'
            ]
            : '';


    if (
        $csrfToken === '' ||
        $sessionToken === '' ||
        !hash_equals(
            $sessionToken,
            $csrfToken
        )
    ) {

        wayfarerPresentationRespond(
            403,
            [
                'ok' =>
                    false,

                'error' =>
                    'Invalid runtime token.',
            ]
        );
    }


    $requestedId =
        isset(
            $input['game_user_id']
        )
            ? (int)$input[
                'game_user_id'
            ]
            : null;

    $gameUserId =
        wayfarerRuntimeResolveGameUserId(
            $pdo,
            $requestedId
        );


    $expectedType =
        trim(
            (string)(
                $input['type']
                ?? ''
            )
        );

    $expectedId =
        (int)(
            $input['id']
            ?? 0
        );


    $result =
        wayfarerRuntimeDismissPresentation(
            $pdo,
            $gameUserId,
            $expectedType,
            $expectedId
        );


    wayfarerPresentationRespond(
        200,
        [
            'ok' =>
                true,

            'game_user_id' =>
                $result[
                    'game_user_id'
                ],

            'state' =>
                $result['state'],

            /* WAYFARER_PLAYER_CONTEXT_API_V46_1 */
            'context' =>
                $result['context']
                ?? null,

            'dismissed' =>
                $result['dismissed'],

            /* WAYFARER_STORYLET_ACTIONS_AFTER_PRESENTATION_V59 */
            'actions' =>
                $result['actions']
                ?? [],
        ]
    );


} catch (Throwable $exception) {

    wayfarerPresentationRespond(
        500,
        [
            'ok' =>
                false,

            'error' =>
                $exception->getMessage(),
        ]
    );
}


==============================================================================
FILE: play/api/restart.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Ending Restart API
 * WAYFARER_ENDING_RESTART_V63
 * --------------------------------------------------------------------------
 */

declare(strict_types=1);

header(
    'Content-Type: application/json; charset=UTF-8'
);


function wayfarerRestartRespond(
    int $status,
    array $payload
): void {

    http_response_code(
        $status
    );

    echo json_encode(
        $payload,
        JSON_UNESCAPED_SLASHES |
        JSON_UNESCAPED_UNICODE
    );

    exit;
}


if (
    $_SERVER['REQUEST_METHOD'] !==
    'POST'
) {
    wayfarerRestartRespond(
        405,
        [
            'ok' => false,
            'error' => 'POST required.',
        ]
    );
}


if (
    session_status() !==
    PHP_SESSION_ACTIVE
) {
    session_start();
}


require_once __DIR__ .
    '/../../config/database.php';

require_once __DIR__ .
    '/../includes/runtime.php';


try {

    $rawInput =
        file_get_contents(
            'php://input'
        );

    $input =
        json_decode(
            $rawInput ?: '{}',
            true
        );

    if (!is_array($input)) {
        wayfarerRestartRespond(
            400,
            [
                'ok' => false,
                'error' => 'Invalid JSON request.',
            ]
        );
    }


    $csrfToken =
        isset($input['csrf_token'])
            ? (string)$input['csrf_token']
            : '';

    $sessionToken =
        isset(
            $_SESSION['wayfarer_tick_csrf']
        )
            ? (string)$_SESSION['wayfarer_tick_csrf']
            : '';

    if (
        $csrfToken === '' ||
        $sessionToken === '' ||
        !hash_equals(
            $sessionToken,
            $csrfToken
        )
    ) {
        wayfarerRestartRespond(
            403,
            [
                'ok' => false,
                'error' => 'Invalid runtime token.',
            ]
        );
    }


    $requestedId =
        isset($input['game_user_id'])
            ? (int)$input['game_user_id']
            : null;

    $gameUserId =
        wayfarerRuntimeResolveGameUserId(
            $pdo,
            $requestedId
        );


    $pdo->beginTransaction();

    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                state
            FROM wf_game_users
            WHERE id = ?
            LIMIT 1
            FOR UPDATE
            "
        );

    $stmt->execute([
        $gameUserId
    ]);

    $row =
        $stmt->fetch(
            PDO::FETCH_ASSOC
        );

    if (!$row) {
        throw new RuntimeException(
            'Game-user runtime record not found.'
        );
    }


    $state =
        wayfarerRuntimeDecodeState(
            $row['state']
            ?? null
        );

    $ending =
        $state['runtime']['ending']
        ?? null;

    if (
        !is_array($ending) ||
        empty($ending['id'])
    ) {
        throw new RuntimeException(
            'This playthrough has not ended.'
        );
    }


    $update =
        $pdo->prepare(
            "
            UPDATE wf_game_users
            SET state = NULL
            WHERE id = ?
            "
        );

    $update->execute([
        $gameUserId
    ]);

    $pdo->commit();


    wayfarerRestartRespond(
        200,
        [
            'ok' => true,
            'game_user_id' => $gameUserId,
            'restarted' => true,
        ]
    );


} catch (Throwable $exception) {

    if (
        isset($pdo) &&
        $pdo instanceof PDO &&
        $pdo->inTransaction()
    ) {
        $pdo->rollBack();
    }

    wayfarerRestartRespond(
        409,
        [
            'ok' => false,
            'error' =>
                $exception->getMessage(),
        ]
    );
}


==============================================================================
FILE: play/api/storylet.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Storylet Action / Branch API
 * WAYFARER_STORYLET_ACTION_RUNTIME_V59
 * --------------------------------------------------------------------------
 */

declare(strict_types=1);

header(
    'Content-Type: application/json; charset=UTF-8'
);


function wayfarerStoryletRespond(
    int $status,
    array $payload
): void {

    http_response_code($status);

    echo json_encode(
        $payload,
        JSON_UNESCAPED_SLASHES |
        JSON_UNESCAPED_UNICODE
    );

    exit;
}


if (
    $_SERVER['REQUEST_METHOD'] !==
    'POST'
) {
    wayfarerStoryletRespond(
        405,
        [
            'ok' => false,
            'error' => 'POST required.',
        ]
    );
}


if (
    session_status() !==
    PHP_SESSION_ACTIVE
) {
    session_start();
}


require_once __DIR__ .
    '/../../config/database.php';

require_once __DIR__ .
    '/../includes/runtime.php';


try {
    $rawInput =
        file_get_contents(
            'php://input'
        );

    $input =
        json_decode(
            $rawInput ?: '{}',
            true
        );

    if (!is_array($input)) {
        wayfarerStoryletRespond(
            400,
            [
                'ok' => false,
                'error' => 'Invalid JSON request.',
            ]
        );
    }

    $csrfToken =
        isset($input['csrf_token'])
            ? (string)$input['csrf_token']
            : '';

    $sessionToken =
        isset(
            $_SESSION['wayfarer_tick_csrf']
        )
            ? (string)$_SESSION['wayfarer_tick_csrf']
            : '';

    if (
        $csrfToken === '' ||
        $sessionToken === '' ||
        !hash_equals(
            $sessionToken,
            $csrfToken
        )
    ) {
        wayfarerStoryletRespond(
            403,
            [
                'ok' => false,
                'error' => 'Invalid runtime token.',
            ]
        );
    }

    $requestedId =
        isset($input['game_user_id'])
            ? (int)$input['game_user_id']
            : null;

    $gameUserId =
        wayfarerRuntimeResolveGameUserId(
            $pdo,
            $requestedId
        );

    $storyletId =
        (int)(
            $input['storylet_id']
            ?? 0
        );

    if ($storyletId <= 0) {
        wayfarerStoryletRespond(
            400,
            [
                'ok' => false,
                'error' => 'A Storylet ID is required.',
            ]
        );
    }

    $entryMode =
        trim(
            (string)(
                $input['entry_mode']
                ?? 'action'
            )
        );

    $parentStoryletId =
        (int)(
            $input['parent_storylet_id']
            ?? 0
        );

    $result =
        wayfarerRuntimeEnterStorylet(
            $pdo,
            $gameUserId,
            $storyletId,
            $entryMode,
            $parentStoryletId
        );

    wayfarerStoryletRespond(
        200,
        [
            'ok' => true,
            'game_user_id' =>
                $result['game_user_id'],
            'state' =>
                $result['state'],
            'context' =>
                $result['context']
                ?? null,
            'presentation' =>
                $result['presentation']
                ?? null,
            'ending' =>
                $result['ending']
                ?? null,
            'occurrence' =>
                $result['occurrence']
                ?? null,
            'actions' =>
                $result['actions']
                ?? [],
        ]
    );

} catch (Throwable $exception) {
    wayfarerStoryletRespond(
        409,
        [
            'ok' => false,
            'error' =>
                $exception->getMessage(),
        ]
    );
}


==============================================================================
FILE: play/api/tick.php
==============================================================================

<?php

declare(strict_types=1);

header(
    'Content-Type: application/json; charset=UTF-8'
);

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {

    http_response_code(405);

    echo json_encode([
        'ok' => false,
        'error' => 'POST required.',
    ]);

    exit;
}

if (session_status() !== PHP_SESSION_ACTIVE) {
    session_start();
}

require_once __DIR__ . '/../../config/database.php';
require_once __DIR__ . '/../includes/runtime.php';


function wayfarerTickRespond(
    int $status,
    array $payload
): void {

    http_response_code($status);

    echo json_encode(
        $payload,
        JSON_UNESCAPED_SLASHES |
        JSON_UNESCAPED_UNICODE
    );

    exit;
}


try {

    $rawInput =
        file_get_contents(
            'php://input'
        );

    $input =
        json_decode(
            $rawInput ?: '{}',
            true
        );

    if (!is_array($input)) {
        wayfarerTickRespond(
            400,
            [
                'ok' => false,
                'error' => 'Invalid JSON request.',
            ]
        );
    }

    $csrfToken =
        isset($input['csrf_token'])
            ? (string)$input['csrf_token']
            : '';

    $sessionToken =
        isset($_SESSION['wayfarer_tick_csrf'])
            ? (string)$_SESSION['wayfarer_tick_csrf']
            : '';

    if (
        $csrfToken === '' ||
        $sessionToken === '' ||
        !hash_equals(
            $sessionToken,
            $csrfToken
        )
    ) {
        wayfarerTickRespond(
            403,
            [
                'ok' => false,
                'error' => 'Invalid tick token.',
            ]
        );
    }

    $requestedId =
        isset($input['game_user_id'])
            ? (int)$input['game_user_id']
            : null;

    /* WAYFARER_BIDIRECTIONAL_TRAVEL_API_V71 */
    $requestedTravelDirection =
        null;

    if (
        array_key_exists(
            'travel_direction',
            $input
        )
    ) {
        if (!is_numeric($input['travel_direction'])) {
            wayfarerTickRespond(
                400,
                [
                    'ok' => false,
                    'error' =>
                        'Travel direction must be -1 or 1.',
                ]
            );
        }

        $requestedTravelDirection =
            (int)$input['travel_direction'];

        if (
            !in_array(
                $requestedTravelDirection,
                [-1, 1],
                true
            )
        ) {
            wayfarerTickRespond(
                400,
                [
                    'ok' => false,
                    'error' =>
                        'Travel direction must be -1 or 1.',
                ]
            );
        }
    }

    $gameUserId =
        wayfarerRuntimeResolveGameUserId(
            $pdo,
            $requestedId
        );

    $result =
        wayfarerRuntimeAdvanceTick(
            $pdo,
            $gameUserId,
            $requestedTravelDirection
        );

    wayfarerTickRespond(
        200,
        [
            'ok' => true,
            'tick' => $result['tick'],
            'game_user_id' =>
                $result['game_user_id'],
            'state' =>
                $result['state'],

            /* WAYFARER_PLAYER_CONTEXT_API_V46_1 */
            'context' =>
                $result['context']
                ?? null,

            /*
             * WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40
             * The browser stops automatic advancement immediately when the
             * runtime reports an interrupting presentation.
             */
            'pause' =>
                !empty(
                    $result['pause']
                ),

            'pause_reason' =>
                (string)(
                    $result['pause_reason']
                    ?? ''
                ),

            'presentation' =>
                $result['presentation']
                ?? null,

            /* WAYFARER_GAME_ENDINGS_TICK_API_V45 */
            'ending' =>
                $result['ending']
                ?? null,

            /* WAYFARER_STORYLET_ACTIONS_TICK_API_V59 */
            'actions' =>
                $result['actions']
                ?? [],

            /* WAYFARER_TRAVEL_TIME_HUD_V61 */
            'travel' =>
                $result['travel']
                ?? null,
        ]
    );

} catch (Throwable $exception) {

    wayfarerTickRespond(
        500,
        [
            'ok' => false,
            'error' =>
                $exception->getMessage(),
        ]
    );
}



==============================================================================
FILE: play/assets/play.css
==============================================================================

/*
|--------------------------------------------------------------------------
| Wayfarer Play Shell v20
|--------------------------------------------------------------------------
*/

html,
body {
    height: 100%;
}


body.wayfarer-play-page {
    margin: 0;
    overflow: hidden;
    background: #eef1f5;
    color: #20242a;
    font-family:
        -apple-system,
        BlinkMacSystemFont,
        "Segoe UI",
        Roboto,
        Arial,
        sans-serif;
    line-height: 1.45;
}


.wayfarer-play-page * {
    box-sizing: border-box;
}


.wayfarer-play-page hr {
    display: none;
}


.wayfarer-play-shell {
    height: 100vh;
    display: flex;
    flex-direction: column;
    overflow: hidden;
}


.wayfarer-play-shell-header {
    flex: 0 0 auto;
    min-height: 68px;
    padding: 12px 18px;
    display: flex;
    align-items: center;
    justify-content: space-between;
    gap: 18px;
    background: #ffffff;
    border-bottom: 1px solid #d8dbe2;
}


.wayfarer-play-title {
    min-width: 0;
}


.wayfarer-play-title h1 {
    margin: 0;
    font-size: 1.35rem;
    line-height: 1.2;
}


.wayfarer-play-title p {
    margin: 4px 0 0;
    color: #667085;
    font-size: 0.9rem;
}


.wayfarer-shell-actions {
    display: flex;
    align-items: center;
    gap: 8px;
}


.wayfarer-shell-button {
    border: 1px solid #b8bdc7;
    border-radius: 6px;
    padding: 7px 10px;
    background: #ffffff;
    color: #20242a;
    cursor: pointer;
    font: inherit;
    font-weight: 600;
}


.wayfarer-shell-button:hover {
    background: #f6f7f9;
}


.wayfarer-play-main {
    flex: 1 1 auto;
    min-height: 0;
    display: grid;
    grid-template-columns:
        minmax(0, 7fr)
        minmax(330px, 3fr);
    gap: 12px;
    padding: 12px;
    overflow: hidden;
}


.wayfarer-player-pane,
.wayfarer-author-pane {
    min-width: 0;
    min-height: 0;
    background: #ffffff;
    border: 1px solid #d8dbe2;
    border-radius: 10px;
    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.06);
}


.wayfarer-player-pane {
    overflow: auto;
    padding: 22px;
}


.wayfarer-player-pane > h2:first-child {
    margin-top: 0;
}


#wayfarer-player-scene {
    margin-top: 10px;
}


#wayfarer-player-scene h2 {
    margin-top: 0;
}


.wayfarer-author-pane {
    display: flex;
    flex-direction: column;
    overflow: hidden;
}


.wayfarer-author-header {
    flex: 0 0 auto;
    padding: 14px 16px 10px;
    border-bottom: 1px solid #e3e6eb;
}


.wayfarer-author-header h2 {
    margin: 0;
    font-size: 1.05rem;
}


.wayfarer-author-header p {
    margin: 6px 0 0;
    font-size: 0.85rem;
}


.wayfarer-author-header a {
    color: #2f5ea8;
}


.wayfarer-author-toolbar {
    flex: 0 0 auto;
    padding: 10px 14px;
    background: #f6f7f9;
    border-bottom: 1px solid #e3e6eb;
}


.wayfarer-author-toolbar #wayfarer-tick-test {
    margin: 0;
}


.wayfarer-author-toolbar #wayfarer-tick-test > h2 {
    margin: 0 0 6px;
    font-size: 0.9rem;
}


.wayfarer-author-toolbar #wayfarer-tick-test > p {
    margin: 5px 0;
    font-size: 0.82rem;
}


.wayfarer-author-toolbar button {
    margin-right: 4px;
    margin-bottom: 2px;
    padding: 5px 8px;
}


#wayfarer-tick-message {
    min-height: 1.2em;
}


.wayfarer-author-tabs {
    flex: 0 0 auto;
    display: flex;
    gap: 2px;
    padding: 8px 10px 0;
    background: #ffffff;
    border-bottom: 1px solid #d8dbe2;
}


.wayfarer-author-tab {
    appearance: none;
    border: 0;
    border-bottom: 2px solid transparent;
    padding: 8px 10px 7px;
    background: transparent;
    color: #667085;
    cursor: pointer;
    font: inherit;
    font-size: 0.86rem;
    font-weight: 600;
}


.wayfarer-author-tab:hover {
    color: #20242a;
}


.wayfarer-author-tab.is-active {
    color: #2f5ea8;
    border-bottom-color: #2f5ea8;
}


.wayfarer-author-content {
    flex: 1 1 auto;
    min-height: 0;
    overflow: auto;
    padding: 14px 16px 18px;
}


.wayfarer-author-tab-panel {
    display: none;
}


.wayfarer-author-tab-panel.is-active {
    display: block;
}


.wayfarer-author-tab-panel > :first-child {
    margin-top: 0;
}


.wayfarer-author-tab-panel h3 {
    margin-top: 0;
    font-size: 1rem;
}


.wayfarer-author-tab-panel h4 {
    margin-bottom: 8px;
}


.wayfarer-author-tab-panel table {
    width: 100%;
    border-collapse: collapse;
    font-size: 0.84rem;
}


.wayfarer-author-tab-panel th,
.wayfarer-author-tab-panel td {
    padding: 6px 7px;
    text-align: left;
    vertical-align: top;
}


.wayfarer-author-tab-panel pre {
    max-width: 100%;
    overflow: auto;
    font-size: 0.78rem;
}


#wayfarer-author-debug-panel details {
    margin-top: 0 !important;
}


#wayfarer-author-debug-panel summary {
    display: none;
}


#wayfarer-author-debug-panel details:not([open]) > *:not(summary) {
    display: block;
}


#wayfarer-author-debug-panel details > pre {
    display: block;
    max-height: none !important;
    margin-top: 0 !important;
}


.wayfarer-player-meta {
    margin-bottom: 14px;
    padding: 10px 12px;
    border-radius: 7px;
    background: #f6f7f9;
    color: #667085;
    font-size: 0.86rem;
}


.wayfarer-player-meta h2 {
    margin: 0 0 4px;
    color: #20242a;
    font-size: 0.95rem;
}


.wayfarer-player-meta p {
    margin: 0;
}


.wayfarer-play-shell.author-collapsed .wayfarer-play-main {
    grid-template-columns: minmax(0, 1fr);
}


.wayfarer-play-shell.author-collapsed .wayfarer-author-pane {
    display: none;
}


@media (max-width: 900px) {

    body.wayfarer-play-page {
        overflow: auto;
    }

    .wayfarer-play-shell {
        height: auto;
        min-height: 100vh;
        overflow: visible;
    }

    .wayfarer-play-main {
        display: block;
        overflow: visible;
        padding: 8px;
    }

    .wayfarer-player-pane,
    .wayfarer-author-pane {
        overflow: visible;
        margin-bottom: 10px;
    }

    .wayfarer-author-pane {
        min-height: 480px;
    }

    .wayfarer-author-content {
        overflow: visible;
    }

    .wayfarer-play-shell.author-collapsed .wayfarer-author-pane {
        display: none;
    }
}

/* ------------------------------------------------------------------
   GAME START SCREEN
   WAYFARER_PLAYER_START_SCREEN_V36
------------------------------------------------------------------ */

/*
 * WAYFARER_ROLE_BASED_AUTHOR_MODE_V37
 *
 * The start screen no longer implies "no Author Mode." Authors may inspect
 * the Author panel before initialization. The existing author-collapsed class
 * controls the one-column layout for normal players and collapsed authors.
 */

.wayfarer-start-screen {
    width: min(860px, 100%);
    margin: 0 auto;
}

.wayfarer-start-screen-heading { margin-bottom: 24px; }

.wayfarer-start-screen-heading h2 {
    margin: 0 0 12px;
    font-size: 1.65rem;
}

.wayfarer-start-introduction {
    max-width: 72ch;
    color: #4b5563;
    line-height: 1.65;
}

.wayfarer-start-error {
    margin-bottom: 18px;
    padding: 10px 12px;
    border: 1px solid #e4a7ad;
    border-radius: 7px;
    background: #fff4f5;
    color: #8b1e2d;
}

.wayfarer-start-form {
    display: grid;
    gap: 22px;
}

.wayfarer-start-section,
.wayfarer-start-choice {
    margin: 0;
    padding: 18px;
    border: 1px solid #d8dbe2;
    border-radius: 9px;
    background: #ffffff;
}

.wayfarer-start-section h3,
.wayfarer-start-choice legend {
    margin: 0 0 14px;
    color: #20242a;
    font-size: 1.05rem;
    font-weight: 700;
}

.wayfarer-start-choice legend { padding: 0 6px; }

.wayfarer-start-names {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
    gap: 12px;
}

.wayfarer-start-names label {
    display: grid;
    gap: 5px;
    font-weight: 600;
}

.wayfarer-start-names input {
    width: 100%;
    padding: 9px 10px;
    border: 1px solid #b8bdc7;
    border-radius: 6px;
    font: inherit;
}

.wayfarer-start-choice {
    display: grid;
    gap: 10px;
}

.wayfarer-start-option {
    display: grid;
    grid-template-columns: auto minmax(0, 1fr);
    gap: 10px;
    align-items: start;
    padding: 12px 13px;
    border: 1px solid #d8dbe2;
    border-radius: 7px;
    cursor: pointer;
}

.wayfarer-start-option:hover { background: #f6f7f9; }

.wayfarer-start-option input { margin-top: 4px; }

.wayfarer-start-option-copy {
    display: grid;
    gap: 4px;
}

.wayfarer-start-option-copy > span {
    color: #667085;
    font-size: 0.92rem;
}

.wayfarer-start-actions {
    display: flex;
    justify-content: flex-end;
}

.wayfarer-start-button {
    padding: 10px 18px;
    border: 1px solid #244b88;
    border-radius: 7px;
    background: #2f5ea8;
    color: #ffffff;
    cursor: pointer;
    font: inherit;
    font-weight: 700;
}

.wayfarer-start-button:hover { background: #244b88; }

@media (max-width: 700px) {
    .wayfarer-start-screen { width: 100%; }

    .wayfarer-start-section,
    .wayfarer-start-choice {
        padding: 14px;
    }
}


/* ------------------------------------------------------------------
   PLAYER ACTION SCREEN
   WAYFARER_ACTION_SCREEN_V39
------------------------------------------------------------------ */

.wayfarer-action-screen {
    margin-top: 14px;
    padding: 18px;
    border: 1px solid #d8dbe2;
    border-radius: 10px;
    background: #ffffff;
    box-shadow: 0 1px 2px rgba(16, 24, 40, 0.05);
}


.wayfarer-action-screen[hidden],
.wayfarer-travel-controls[hidden] {
    display: none !important;
}


.wayfarer-action-heading {
    margin-bottom: 14px;
}


.wayfarer-action-heading h2 {
    margin: 0 0 4px;
    font-size: 1.25rem;
}


.wayfarer-action-heading p {
    margin: 0;
    color: #667085;
}


.wayfarer-action-list {
    display: grid;
    gap: 10px;
}


.wayfarer-action-button {
    width: 100%;
    padding: 12px 14px;
    border: 1px solid #214b86;
    border-radius: 8px;
    background: #245a9b;
    color: #ffffff;
    cursor: pointer;
    font: inherit;
    font-weight: 700;
    text-align: left;
}


.wayfarer-action-button:hover {
    background: #1e4c84;
}


.wayfarer-action-button:disabled {
    cursor: default;
    opacity: 0.55;
}


/* ------------------------------------------------------------------
   IN-CARD ACTION UTILITY VIEWS
   WAYFARER_ACTION_UTILITY_VIEWS_V48
------------------------------------------------------------------ */

.wayfarer-action-utility-row {
    display: grid;
    grid-template-columns: repeat(2, minmax(0, 1fr));
    gap: 10px;
    margin-top: 2px;
}


.wayfarer-action-utility-button,
.wayfarer-action-back-button {
    padding: 10px 12px;
    border: 1px solid #b8bdc7;
    border-radius: 7px;
    background: #ffffff;
    color: #20242a;
    cursor: pointer;
    font: inherit;
    font-weight: 650;
}


.wayfarer-action-utility-button {
    width: 100%;
    text-align: center;
}


.wayfarer-action-utility-button:hover,
.wayfarer-action-back-button:hover {
    border-color: #98a2b3;
    background: #f6f7f9;
}


.wayfarer-action-subview[hidden],
.wayfarer-action-heading[hidden],
.wayfarer-action-list[hidden] {
    display: none !important;
}


.wayfarer-action-subview-heading {
    display: flex;
    align-items: center;
    justify-content: space-between;
    gap: 14px;
    margin-bottom: 18px;
}


.wayfarer-action-subview-heading h2 {
    margin: 0;
    font-size: 1.25rem;
}


.wayfarer-action-back-button {
    flex: 0 0 auto;
}


.wayfarer-action-subview-body {
    min-height: 90px;
}


/* ------------------------------------------------------------------
   ENTITY INVENTORY / STATUS PRESENTATION
   WAYFARER_ENTITY_PRESENTATION_V49
------------------------------------------------------------------ */

.wayfarer-inventory-list,
.wayfarer-party-list {
    display: grid;
    gap: 10px;
}


.wayfarer-inventory-item,
.wayfarer-party-member,
.wayfarer-status-section {
    padding: 13px 14px;
    border: 1px solid #d8dbe2;
    border-radius: 8px;
    background: #f8fafc;
}


.wayfarer-inventory-item-heading {
    display: flex;
    align-items: baseline;
    justify-content: space-between;
    gap: 14px;
}


.wayfarer-inventory-quantity {
    flex: 0 0 auto;
    color: #667085;
    font-size: 0.9rem;
    font-weight: 650;
}


.wayfarer-status-section + .wayfarer-status-section {
    margin-top: 12px;
}


.wayfarer-status-section > h3 {
    margin: 0 0 10px;
    font-size: 1rem;
}


.wayfarer-status-player-name {
    margin: 0;
    font-weight: 700;
}


.wayfarer-party-member {
    background: #ffffff;
}


.wayfarer-party-member h4 {
    margin: 0;
    font-size: 0.98rem;
}


/* WAYFARER_PLAYER_TRAITS_STATUS_V52 */
.wayfarer-player-member h4::after {
    content: "Player";
    margin-left: 8px;
    color: #667085;
    font-size: 0.72rem;
    font-weight: 600;
    text-transform: uppercase;
    letter-spacing: 0.04em;
}


.wayfarer-status-values {
    margin: 10px 0 0;
}


.wayfarer-status-values > div {
    display: grid;
    grid-template-columns: minmax(0, 1fr) auto;
    gap: 18px;
    padding: 6px 0;
    border-top: 1px solid #e3e6eb;
}


.wayfarer-status-values dt {
    color: #4b5563;
}


.wayfarer-status-values dd {
    margin: 0;
    font-weight: 700;
    text-align: right;
}


.wayfarer-status-muted {
    margin: 8px 0 0;
    color: #667085;
    font-size: 0.88rem;
}


/* ------------------------------------------------------------------
   ENTITY DETAIL VIEW
   WAYFARER_ENTITY_DETAIL_VIEW_V50
------------------------------------------------------------------ */

.wayfarer-entity-open-button {
    appearance: none;
    border: 0;
    padding: 0;
    background: transparent;
    color: #2f5ea8;
    cursor: pointer;
    font: inherit;
    font-weight: 750;
    text-align: left;
}


.wayfarer-entity-open-button:hover {
    text-decoration: underline;
}


.wayfarer-entity-open-button:focus-visible {
    outline: 2px solid #2f5ea8;
    outline-offset: 3px;
    border-radius: 2px;
}


.wayfarer-status-player-names {
    display: grid;
    gap: 4px;
}


.wayfarer-status-player-names .wayfarer-status-player-name {
    margin: 0;
}


.wayfarer-entity-detail-eyebrow {
    margin: 0 0 3px;
    color: #667085;
    font-size: 0.78rem;
    font-weight: 750;
    letter-spacing: 0.08em;
    text-transform: uppercase;
}


.wayfarer-entity-detail-layout {
    display: grid;
    grid-template-columns: minmax(180px, 280px) minmax(0, 1fr);
    gap: 22px;
    align-items: start;
}


.wayfarer-entity-detail-layout:not(:has(.wayfarer-entity-detail-media)) {
    grid-template-columns: minmax(0, 1fr);
}


.wayfarer-entity-detail-media {
    margin: 0;
}


.wayfarer-entity-detail-media img {
    display: block;
    width: 100%;
    max-height: 340px;
    object-fit: contain;
    border-radius: 8px;
    background: #f6f7f9;
}


.wayfarer-entity-detail-description {
    margin: 0 0 16px;
    line-height: 1.6;
}


.wayfarer-entity-detail-copy > :first-child {
    margin-top: 0;
}


@media (max-width: 700px) {

    .wayfarer-entity-detail-layout {
        grid-template-columns: 1fr;
    }

    .wayfarer-entity-detail-media img {
        max-height: 280px;
    }
}


.wayfarer-action-empty {
    margin: 0;
    color: #667085;
    font-size: 0.92rem;
}


.wayfarer-travel-controls {
    margin-top: 14px;
    padding: 12px 14px;
    display: flex;
    align-items: center;
    justify-content: space-between;
    gap: 12px;
    border: 1px solid #d8dbe2;
    border-radius: 10px;
    background: #ffffff;
}


.wayfarer-travel-status {
    display: flex;
    align-items: center;
    gap: 9px;
    font-weight: 700;
}


/* WAYFARER_TRAVEL_TIME_HUD_V61 */
.wayfarer-travel-copy {
    min-width: 0;
}

.wayfarer-travel-primary {
    display: flex;
    align-items: baseline;
    flex-wrap: wrap;
    gap: 6px;
}

.wayfarer-travel-time {
    font-weight: 800;
}

.wayfarer-travel-time-separator {
    color: #98a2b3;
}

.wayfarer-travel-next {
    margin-top: 3px;
    color: #667085;
    font-size: 0.88rem;
    font-weight: 600;
}


.wayfarer-travel-indicator {
    width: 9px;
    height: 9px;
    border-radius: 999px;
    background: currentColor;
}


.wayfarer-travel-pause {
    padding: 8px 12px;
    border: 1px solid #aab4c3;
    border-radius: 7px;
    background: #ffffff;
    color: #20242a;
    cursor: pointer;
    font: inherit;
    font-weight: 600;
}


.wayfarer-travel-pause:hover {
    background: #f6f7f9;
}


@media (max-width: 620px) {

    .wayfarer-action-screen {
        padding: 14px;
    }

    .wayfarer-travel-controls {
        align-items: stretch;
        flex-direction: column;
    }

    .wayfarer-travel-pause {
        width: 100%;
    }

    .wayfarer-action-utility-row {
        grid-template-columns: 1fr;
    }
}


/* ------------------------------------------------------------------
   LOCATION / STORY PRESENTATION
   WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40
------------------------------------------------------------------ */

/*
 * Scene prose now belongs to Presentation Mode rather than the normal Action
 * page. The server-rendered scene remains in the DOM temporarily for runtime
 * compatibility but is not player-facing.
 */
#wayfarer-player-scene {
    display: none;
}


.wayfarer-action-parent-context {
    margin-bottom: 4px !important;
    font-size: 0.85rem;
    font-weight: 600;
}



/* ------------------------------------------------------------------
   STORYLET ACTIONS / BRANCHES
   WAYFARER_STORYLET_ACTION_RUNTIME_V59
------------------------------------------------------------------ */

.wayfarer-storylet-action-list {
    display: grid;
    gap: 10px;
}

.wayfarer-storylet-action-list:empty {
    display: none;
}

.wayfarer-storylet-branch-list {
    width: 100%;
    display: grid;
    gap: 10px;
}

.wayfarer-presentation-actions.wayfarer-has-storylet-branches > div:not(.wayfarer-storylet-branch-list) {
    display: none;
}

.wayfarer-storylet-branch-prompt {
    margin: 0 0 4px;
    color: #b8c0cc;
    font-weight: 700;
}

.wayfarer-storylet-branch-button {
    width: 100%;
    padding: 12px 14px;
    border: 1px solid #f8fafc;
    border-radius: 8px;
    background: transparent;
    color: #f8fafc;
    cursor: pointer;
    font: inherit;
    font-weight: 700;
    text-align: left;
}

.wayfarer-storylet-branch-button:hover,
.wayfarer-storylet-branch-button:focus-visible {
    background: #f8fafc;
    color: #15181d;
}

.wayfarer-storylet-branch-button:disabled {
    cursor: default;
    opacity: 0.55;
}

.wayfarer-presentation-screen {
    position: fixed;
    z-index: 10000;
    inset: 0;
    overflow-y: auto;
    padding: clamp(24px, 6vh, 72px) 24px;
    background: #15181d;
    color: #f8fafc;
}


.wayfarer-presentation-screen[hidden] {
    display: none !important;
}


.wayfarer-presentation-inner {
    width: min(1040px, 100%);
    min-height: calc(100vh - clamp(48px, 12vh, 144px));
    margin: 0 auto;
    display: flex;
    flex-direction: column;
    justify-content: center;
}


.wayfarer-presentation-media {
    width: 100%;
    margin: 0 0 26px;
    overflow: hidden;
    border-radius: 12px;
    background: #0d0f12;
}


.wayfarer-presentation-media img {
    display: block;
    width: 100%;
    max-height: 52vh;
    object-fit: cover;
}


.wayfarer-presentation-copy {
    width: min(760px, 100%);
    margin: 0 auto;
}


.wayfarer-presentation-eyebrow {
    margin: 0 0 8px;
    color: #b8c0cc;
    font-size: 0.78rem;
    font-weight: 700;
    letter-spacing: 0.1em;
    text-transform: uppercase;
}


.wayfarer-presentation-copy h1 {
    margin: 0 0 18px;
    color: inherit;
    font-size: clamp(2rem, 5vw, 3.8rem);
    line-height: 1.05;
}


.wayfarer-presentation-description {
    font-size: clamp(1rem, 2vw, 1.22rem);
    line-height: 1.7;
}


.wayfarer-presentation-actions {
    width: min(760px, 100%);
    margin: 32px auto 0;
    display: flex;
    justify-content: flex-end;
}


.wayfarer-presentation-continue {
    min-width: 150px;
    padding: 11px 18px;
    border: 1px solid #f8fafc;
    border-radius: 8px;
    background: #f8fafc;
    color: #15181d;
    cursor: pointer;
    font: inherit;
    font-weight: 700;
}


.wayfarer-presentation-continue:hover {
    background: #e8edf3;
}


.wayfarer-presentation-continue:focus-visible {
    outline: 3px solid #ffffff;
    outline-offset: 4px;
}


.wayfarer-presentation-key-hint {
    margin: 10px 0 0;
    color: #9ea8b6;
    font-size: 0.78rem;
    text-align: right;
}


body.wayfarer-runtime-presentation {
    overflow: hidden;
}


@media (max-width: 620px) {

    .wayfarer-presentation-screen {
        padding: 20px 14px;
    }

    .wayfarer-presentation-inner {
        min-height: calc(100vh - 40px);
    }

    .wayfarer-presentation-actions {
        justify-content: stretch;
    }

    .wayfarer-presentation-continue {
        width: 100%;
    }
}


/* ------------------------------------------------------------------
   COMBINED AUTHOR STATE + REGION
   WAYFARER_COMBINED_AUTHOR_STATE_REGION_V41
------------------------------------------------------------------ */

.wayfarer-author-state-region {
    margin-top: 20px;
    padding-top: 14px;
    border-top: 1px solid #e4e7ec;
}

.wayfarer-author-state-region > :first-child {
    margin-top: 0;
}


/* ------------------------------------------------------------------
   TERMINAL GAME ENDING
   WAYFARER_GAME_ENDING_SCREEN_V45
------------------------------------------------------------------ */

.wayfarer-ending-screen {
    position: fixed;
    z-index: 11000;
    inset: 0;
    overflow-y: auto;
    padding: clamp(24px, 6vh, 72px) 24px;
    background: #11151a;
    color: #f8fafc;
}

.wayfarer-ending-inner {
    width: min(1040px, 100%);
    min-height: calc(100vh - clamp(48px, 12vh, 144px));
    margin: 0 auto;
    display: flex;
    flex-direction: column;
    justify-content: center;
}

.wayfarer-ending-media {
    width: 100%;
    margin: 0 0 28px;
    overflow: hidden;
    border-radius: 12px;
    background: #080a0d;
}

.wayfarer-ending-media img {
    display: block;
    width: 100%;
    max-height: 52vh;
    object-fit: cover;
}

.wayfarer-ending-copy {
    width: min(760px, 100%);
    margin: 0 auto;
}

.wayfarer-ending-eyebrow {
    margin: 0 0 8px;
    color: #aeb8c5;
    font-size: 0.78rem;
    font-weight: 700;
    letter-spacing: 0.1em;
    text-transform: uppercase;
}

.wayfarer-ending-copy h1 {
    margin: 0 0 18px;
    color: inherit;
    font-size: clamp(2rem, 5vw, 3.8rem);
    line-height: 1.05;
}

.wayfarer-ending-text {
    font-size: clamp(1rem, 2vw, 1.22rem);
    line-height: 1.7;
}

body.wayfarer-game-ended {
    overflow: hidden;
}

/* ------------------------------------------------------------------
   PRESENTATION TRANSITION + ENDING RESTART
   WAYFARER_PRESENTATION_TRANSITION_V63
   WAYFARER_ENDING_RESTART_V63
------------------------------------------------------------------ */

body.wayfarer-presentation-transitioning::after {
    content: "";
    position: fixed;
    z-index: 10500;
    inset: 0;
    background: #15181d;
    pointer-events: all;
}

.wayfarer-ending-actions {
    margin-top: 30px;
    display: flex;
    justify-content: flex-end;
}

.wayfarer-ending-restart {
    min-width: 150px;
    padding: 11px 18px;
    border: 1px solid #f8fafc;
    border-radius: 8px;
    background: #f8fafc;
    color: #15181d;
    cursor: pointer;
    font: inherit;
    font-weight: 700;
}

.wayfarer-ending-restart:hover {
    background: #e8edf3;
}

.wayfarer-ending-restart:focus-visible {
    outline: 3px solid #ffffff;
    outline-offset: 4px;
}

.wayfarer-ending-restart:disabled {
    cursor: default;
    opacity: 0.6;
}

@media (max-width: 620px) {
    .wayfarer-ending-actions {
        justify-content: stretch;
    }

    .wayfarer-ending-restart {
        width: 100%;
    }
}

/* ------------------------------------------------------------------
   PERSISTENT PLAYER HUD
   WAYFARER_PLAYER_HUD_V64
------------------------------------------------------------------ */

.wayfarer-player-pane {
    display: flex;
    flex-direction: column;
}

.wayfarer-player-hud {
    flex: 0 0 auto;
    margin-top: auto;
    padding-top: 18px;
}

.wayfarer-player-hud[hidden] {
    display: none !important;
}

.wayfarer-hud-components {
    display: grid;
    grid-template-columns:
        repeat(
            auto-fit,
            minmax(
                min(260px, 100%),
                1fr
            )
        );
    gap: 12px 18px;
    padding: 14px 16px;
    border: 1px solid #d8dbe2;
    border-radius: 10px;
    background: #f8fafc;
}

.wayfarer-hud-progress-component {
    min-width: 0;
}

.wayfarer-hud-progress-heading {
    display: flex;
    align-items: baseline;
    justify-content: space-between;
    gap: 12px;
    margin-bottom: 7px;
}

.wayfarer-hud-label {
    min-width: 0;
    overflow: hidden;
    font-size: 0.88rem;
    font-weight: 700;
    text-overflow: ellipsis;
    white-space: nowrap;
}

.wayfarer-hud-value {
    flex: 0 0 auto;
    color: #667085;
    font-size: 0.82rem;
    font-variant-numeric: tabular-nums;
}

.wayfarer-hud-progress-track {
    height: 10px;
    overflow: hidden;
    border-radius: 999px;
    background: #dfe4ea;
}

.wayfarer-hud-progress-fill {
    height: 100%;
    min-width: 0;
    border-radius: inherit;
    background: #2f5ea8;
    transition: width 180ms ease;
}

@media (max-width: 620px) {

    .wayfarer-player-hud {
        padding-top: 14px;
    }

    .wayfarer-hud-components {
        grid-template-columns: 1fr;
        gap: 12px;
        padding: 12px 13px;
    }
}


/* ------------------------------------------------------------------
   REGION HUD AUTHORING
   WAYFARER_REGION_HUD_EDITOR_V64
------------------------------------------------------------------ */

.builder-region-hud {
    margin: 0;
}

.builder-region-hud > h3 {
    margin-top: 0;
}

.builder-region-hud-component {
    margin: 14px 0;
    padding: 14px 16px;
    border: 1px solid #d8dbe2;
    border-radius: 8px;
}

.builder-region-hud-component legend {
    padding: 0 6px;
    font-weight: 700;
}

.builder-region-hud-component select,
.builder-region-hud-component input[type="text"] {
    width: min(560px, 100%);
    max-width: 100%;
}

/* ------------------------------------------------------------------
   ONE-TIME EFFECT PLAYER FEEDBACK
   WAYFARER_EFFECT_FEEDBACK_V70
------------------------------------------------------------------ */

.wayfarer-presentation-changes {
    margin-top: 18px;
    padding: 12px 14px;
    border: 1px solid rgba(31, 41, 55, 0.16);
    border-radius: 8px;
    background: rgba(255, 255, 255, 0.68);
}

.wayfarer-presentation-changes-heading {
    margin: 0 0 7px;
    font-size: 0.78rem;
    font-weight: 800;
    letter-spacing: 0.08em;
    text-transform: uppercase;
    opacity: 0.68;
}

.wayfarer-presentation-changes-list {
    display: grid;
    gap: 5px;
    margin: 0;
    padding: 0;
    list-style: none;
}

.wayfarer-presentation-change {
    margin: 0;
    font-weight: 700;
    line-height: 1.35;
}

.wayfarer-presentation-change.is-gain::before,
.wayfarer-presentation-change.is-loss::before {
    display: inline-block;
    width: 0;
    overflow: hidden;
    content: '';
}


==============================================================================
FILE: play/assets/play.js
==============================================================================

/*
|--------------------------------------------------------------------------
| PLAYER RUNTIME CONTROLLER
| WAYFARER_ACTION_SCREEN_V39
| WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40
|--------------------------------------------------------------------------
|
| Runtime modes currently exposed to the player:
|
|     presentation -> Action -> running navigation -> presentation/Action
|
| Presentation is persisted by PHP. Automatic tick advancement cannot continue
| while a presentation is active.
|
*/

(() => {
    'use strict';

    const config =
        window.wayfarerTickRuntime;

    if (!config) {
        return;
    }


    const body =
        document.body;

    const tickValue =
        document.getElementById(
            'wayfarer-tick-value'
        );

    const statusValue =
        document.getElementById(
            'wayfarer-tick-status'
        );

    const message =
        document.getElementById(
            'wayfarer-tick-message'
        );

    const onceButton =
        document.getElementById(
            'wayfarer-tick-once'
        );

    const autoButton =
        document.getElementById(
            'wayfarer-tick-auto'
        );

    const authorPauseButton =
        document.getElementById(
            'wayfarer-tick-pause'
        );


    const actionScreen =
        document.querySelector(
            '[data-wayfarer-action-screen]'
        );

    const travelControls =
        document.querySelector(
            '[data-wayfarer-travel-controls]'
        );

    /* WAYFARER_PLAYER_HUD_V64 */
    const playerHud =
        document.querySelector(
            '[data-wayfarer-hud]'
        );

    /* WAYFARER_TRAVEL_TIME_HUD_V61 */
    const travelTime =
        document.querySelector(
            '[data-wayfarer-travel-time]'
        );

    const travelTimeSeparator =
        document.querySelector(
            '[data-wayfarer-travel-time-separator]'
        );

    const travelNext =
        document.querySelector(
            '[data-wayfarer-travel-next]'
        );

    const continueTravelButton =
        document.querySelector(
            '[data-wayfarer-continue-travel]'
        );

    const playerPauseButton =
        document.querySelector(
            '[data-wayfarer-pause-travel]'
        );

    /* WAYFARER_PLAYER_TURN_AROUND_UI_V72 */
    const turnAroundButton =
        document.querySelector(
            '[data-wayfarer-turn-around]'
        );


    /*
     * WAYFARER_ACTION_UTILITY_VIEWS_V48
     *
     * Action Mode owns one physical card. Inventory, Status, and future
     * utility/context views temporarily replace the normal action heading/list
     * inside that card without becoming persisted runtime modes.
     */
    const actionHeading =
        actionScreen
            ? actionScreen.querySelector(
                '.wayfarer-action-heading'
            )
            : null;

    const actionList =
        actionScreen
            ? actionScreen.querySelector(
                '[data-wayfarer-action-list]'
            )
            : null;

    const actionSubviewPanels =
        actionScreen
            ? Array.from(
                actionScreen.querySelectorAll(
                    '[data-wayfarer-action-view]'
                )
            )
            : [];

    const actionViewOpeners =
        actionScreen
            ? Array.from(
                actionScreen.querySelectorAll(
                    '[data-wayfarer-open-action-view]'
                )
            )
            : [];

    const actionViewClosers =
        actionScreen
            ? Array.from(
                actionScreen.querySelectorAll(
                    '[data-wayfarer-close-action-view]'
                )
            )
            : [];


    /*
     * Persisted narrative presentation.
     */
    const presentationScreen =
        document.querySelector(
            '[data-wayfarer-presentation-screen]'
        );

    const presentationContinueButton =
        presentationScreen
            ? presentationScreen.querySelector(
                '[data-wayfarer-presentation-continue]'
            )
            : null;


    let running = false;
    let requestInFlight = false;
    let presentationRequestInFlight = false;
    let storyletRequestInFlight = false;
    let timeoutId = null;
    let reloadWhenIdle = false;

    /* WAYFARER_BIDIRECTIONAL_TRAVEL_UI_V71 */
    let requestedTravelDirection =
        Number(
            config.initialDirection
        ) < 0
            ? -1
            : 1;

    let presentationActive =
        Boolean(
            presentationScreen &&
            !presentationScreen.hidden
        );


    function setMessage(
        text,
        isError = false
    ) {

        if (!message) {
            return;
        }

        message.textContent =
            text;

        message.style.color =
            isError
                ? 'red'
                : '';
    }


    function emitModeEvent() {

        let mode =
            'paused';

        if (presentationActive) {
            mode =
                'presentation';
        } else if (running) {
            mode =
                'running';
        }


        window.dispatchEvent(
            new CustomEvent(
                'wayfarer:runtime-mode',
                {
                    detail: {
                        mode:
                            mode
                    }
                }
            )
        );


        /*
         * Keep the v39 event names available for existing development hooks.
         */
        window.dispatchEvent(
            new CustomEvent(
                running
                    ? 'wayfarer:runtime-running'
                    : 'wayfarer:runtime-paused',
                {
                    detail: {
                        mode:
                            mode
                    }
                }
            )
        );
    }


    /*
     * WAYFARER_ACTION_UTILITY_VIEWS_V48
     *
     * Generic in-card view switcher. Future Map / Shop / other views can use
     * the same data-wayfarer-open-action-view + data-wayfarer-action-view
     * contract without adding another page-level layout system.
     */
    /*
     * WAYFARER_DYNAMIC_ACTION_SUBVIEWS_V51
     *
     * Resolve available views at the moment navigation occurs instead of
     * relying on the V48 page-load snapshot. This supports nested Entity
     * detail screens and future context views added to the same Action card.
     */
    function setActionView(viewName = 'actions') {

        if (!actionScreen) {
            return;
        }

        const requested =
            String(
                viewName ||
                'actions'
            );

        const showActions =
            requested ===
            'actions';

        const panels =
            Array.from(
                actionScreen.querySelectorAll(
                    '[data-wayfarer-action-view]'
                )
            );

        let matched =
            showActions;

        panels.forEach(
            function (panel) {

                const active =
                    panel.dataset
                        .wayfarerActionView ===
                    requested;

                panel.hidden =
                    !active;

                if (active) {
                    matched =
                        true;
                }
            }
        );

        /*
         * Fail safely if a malformed/removed view name is requested.
         */
        if (!matched) {

            panels.forEach(
                function (panel) {
                    panel.hidden =
                        true;
                }
            );

            if (actionHeading) {
                actionHeading.hidden =
                    false;
            }

            if (actionList) {
                actionList.hidden =
                    false;
            }

            return;
        }

        if (actionHeading) {
            actionHeading.hidden =
                !showActions;
        }

        if (actionList) {
            actionList.hidden =
                !showActions;
        }
    }

    function renderControls() {

        if (statusValue) {

            statusValue.textContent =
                presentationActive
                    ? 'Presentation'
                    : (
                        running
                            ? 'Running'
                            : 'Paused'
                    );
        }


        if (onceButton) {

            onceButton.disabled =
                running ||
                requestInFlight ||
                presentationActive;
        }


        if (autoButton) {

            autoButton.disabled =
                running ||
                requestInFlight ||
                presentationActive;
        }


        if (authorPauseButton) {

            authorPauseButton.disabled =
                !running;
        }


        if (continueTravelButton) {

            continueTravelButton.disabled =
                running ||
                requestInFlight ||
                presentationActive;
        }


        document
            .querySelectorAll(
                '[data-wayfarer-storylet-action-id], ' +
                '[data-wayfarer-storylet-branch-id]'
            )
            .forEach(
                function (button) {
                    button.disabled =
                        requestInFlight ||
                        presentationRequestInFlight ||
                        storyletRequestInFlight ||
                        (
                            button.hasAttribute(
                                'data-wayfarer-storylet-action-id'
                            ) &&
                            (running || presentationActive)
                        );
                }
            );


        if (playerPauseButton) {

            playerPauseButton.disabled =
                !running;
        }


        /* WAYFARER_PLAYER_TURN_AROUND_UI_V72 */
        if (turnAroundButton) {
            turnAroundButton.disabled =
                running ||
                requestInFlight ||
                presentationActive;
        }


        if (actionScreen) {

            actionScreen.hidden =
                running ||
                presentationActive;
        }


        if (travelControls) {

            travelControls.hidden =
                !running ||
                presentationActive;
        }


        /* WAYFARER_PLAYER_HUD_V64 */
        if (playerHud) {
            playerHud.hidden =
                presentationActive;
        }


        if (presentationScreen) {

            presentationScreen.hidden =
                !presentationActive;

            presentationScreen.setAttribute(
                'aria-hidden',
                presentationActive
                    ? 'false'
                    : 'true'
            );
        }


        body.classList.toggle(
            'wayfarer-runtime-running',
            running
        );

        body.classList.toggle(
            'wayfarer-runtime-paused',
            !running &&
            !presentationActive
        );

        body.classList.toggle(
            'wayfarer-runtime-presentation',
            presentationActive
        );
    }


    /*
     * WAYFARER_LIVE_ACTION_CONTEXT_V46_1
     *
     * Action Mode must reflect the current runtime position, not the page's
     * original server-rendered context.
     */
    function renderPlayerContext(context) {

        if (
            !context ||
            typeof context !== 'object'
        ) {
            return;
        }


        const heading =
            document.querySelector(
                '[data-wayfarer-action-context-name]'
            );

        const parent =
            document.querySelector(
                '[data-wayfarer-action-parent-context]'
            );


        if (heading) {

            const name =
                String(
                    context.context_name ||
                    'Actions'
                ).trim();

            heading.textContent =
                name ||
                'Actions';
        }


        if (parent) {

            const parentText =
                String(
                    context.parent_context ||
                    ''
                ).trim();

            parent.textContent =
                parentText;

            parent.hidden =
                parentText === '';
        }
    }


    /* WAYFARER_TRAVEL_TIME_HUD_RENDER_V61 */
    function renderTravelStatus(travel) {
        if (!travel || typeof travel !== 'object') {
            return;
        }

        const timeLabel = String(travel.time_label || '').trim();
        if (travelTime) {
            travelTime.textContent = timeLabel;
            travelTime.hidden = timeLabel === '';
        }
        if (travelTimeSeparator) {
            travelTimeSeparator.hidden = timeLabel === '';
        }

        const nextLabel = String(travel.next_label || '').trim();
        if (travelNext) {
            travelNext.textContent = nextLabel === ''
                ? ''
                : 'Next: ' + nextLabel;
            travelNext.hidden = nextLabel === '';
        }
    }


    function displayRuntimeValue(value) {

        if (typeof value === 'boolean') {
            return value
                ? 'True'
                : 'False';
        }

        if (
            value === null ||
            value === undefined
        ) {
            return 'null';
        }

        if (typeof value === 'object') {
            return JSON.stringify(
                value
            );
        }

        return String(
            value
        );
    }


    /*
     * WAYFARER_STORYLET_ACTIONS_LIVE_V59
     *
     * Tick/presentation APIs return the currently eligible root Manual
     * Storylets so Action Mode does not depend on the page-load snapshot.
     */
    function renderStoryletActions(actions) {

        if (!actionScreen) {
            return;
        }

        const host =
            actionScreen.querySelector(
                '[data-wayfarer-storylet-actions]'
            );

        if (!host) {
            return;
        }

        const normalized =
            Array.isArray(actions)
                ? actions
                : [];

        host.innerHTML = '';

        normalized.forEach(
            function (action) {

                const id =
                    Number(
                        action && action.id
                            ? action.id
                            : 0
                    );

                if (id <= 0) {
                    return;
                }

                const button =
                    document.createElement(
                        'button'
                    );

                button.type =
                    'button';

                button.className =
                    'wayfarer-action-button';

                button.dataset.wayfarerStoryletActionId =
                    String(id);

                button.textContent =
                    String(
                        action.label ||
                        action.name ||
                        'Storylet'
                    );

                host.appendChild(
                    button
                );
            }
        );

        const empty =
            actionScreen.querySelector(
                '[data-wayfarer-action-empty]'
            );

        if (empty) {
            const canTravel =
                actionScreen.dataset.wayfarerCanTravel ===
                '1';

            empty.hidden =
                canTravel ||
                host.children.length > 0;
        }

        renderControls();
    }


    /*
     * WAYFARER_PLAYER_HUD_V64
     *
     * HUD definitions remain Region-authored/server-rendered. Tick responses
     * already carry canonical state, so progress bars can update without adding
     * another API payload.
     */
    function renderHudState(state) {

        if (
            !playerHud ||
            !state ||
            typeof state !== 'object'
        ) {
            return;
        }

        playerHud
            .querySelectorAll(
                '[data-wayfarer-hud-component]'
            )
            .forEach(
                function (component) {

                    if (
                        component.dataset
                            .wayfarerHudType !==
                        'progress_bar'
                    ) {
                        return;
                    }

                    const scope =
                        String(
                            component.dataset
                                .wayfarerHudScope ||
                            ''
                        );

                    const sourceId =
                        String(
                            component.dataset
                                .wayfarerHudSourceId ||
                            ''
                        );

                    const regionId =
                        String(
                            component.dataset
                                .wayfarerHudRegionId ||
                            ''
                        );

                    let traits =
                        null;

                    if (
                        scope ===
                        'game'
                    ) {
                        traits =
                            state.game &&
                            state.game.traits &&
                            typeof state.game.traits ===
                                'object'
                                ? state.game.traits
                                : null;

                    } else if (
                        scope ===
                        'region'
                    ) {
                        traits =
                            state.regions &&
                            state.regions[regionId] &&
                            state.regions[regionId].traits &&
                            typeof state.regions[regionId].traits ===
                                'object'
                                ? state.regions[regionId].traits
                                : null;
                    }

                    if (
                        !traits ||
                        !Object.prototype
                            .hasOwnProperty
                            .call(
                                traits,
                                sourceId
                            )
                    ) {
                        return;
                    }

                    const value =
                        Number(
                            traits[sourceId]
                        );

                    const min =
                        Number(
                            component.dataset
                                .wayfarerHudMin
                        );

                    const max =
                        Number(
                            component.dataset
                                .wayfarerHudMax
                        );

                    if (
                        !Number.isFinite(value) ||
                        !Number.isFinite(min) ||
                        !Number.isFinite(max) ||
                        max <= min
                    ) {
                        return;
                    }

                    const percent =
                        Math.max(
                            0,
                            Math.min(
                                100,
                                (
                                    (value - min) /
                                    (max - min)
                                ) *
                                100
                            )
                        );

                    const fill =
                        component.querySelector(
                            '[data-wayfarer-hud-fill]'
                        );

                    if (fill) {
                        fill.style.width =
                            percent +
                            '%';
                    }

                    const meter =
                        component.querySelector(
                            '[data-wayfarer-hud-meter]'
                        );

                    if (meter) {
                        meter.setAttribute(
                            'aria-valuenow',
                            String(value)
                        );
                    }

                    const valueNode =
                        component.querySelector(
                            '[data-wayfarer-hud-value]'
                        );

                    if (valueNode) {
                        valueNode.textContent =
                            String(value);
                    }
                }
            );
    }


    function renderRuntimeState(state) {

        if (
            !state ||
            typeof state !== 'object'
        ) {
            return;
        }


        renderHudState(
            state
        );


        if (
            state.navigation &&
            state.navigation.position !== undefined
        ) {

            const position =
                String(
                    state.navigation.position
                );

            const authorPosition =
                document.getElementById(
                    'wayfarer-author-position'
                );

            if (authorPosition) {
                authorPosition.textContent =
                    position;
            }
        }


        const gameTraits =
            state.game &&
            state.game.traits &&
            typeof state.game.traits === 'object'
                ? state.game.traits
                : {};

        document
            .querySelectorAll(
                '[data-wayfarer-game-trait-value]'
            )
            .forEach(
                function (cell) {

                    const traitId =
                        cell.dataset
                            .wayfarerGameTraitValue;

                    if (
                        Object.prototype
                            .hasOwnProperty
                            .call(
                                gameTraits,
                                traitId
                            )
                    ) {
                        cell.textContent =
                            displayRuntimeValue(
                                gameTraits[traitId]
                            );
                    }
                }
            );


        document
            .querySelectorAll(
                '[data-wayfarer-region-trait-value]'
            )
            .forEach(
                function (cell) {

                    const regionId =
                        cell.dataset
                            .wayfarerRegionId;

                    const traitId =
                        cell.dataset
                            .wayfarerRegionTraitValue;

                    const traits =
                        state.regions &&
                        state.regions[regionId] &&
                        state.regions[regionId].traits &&
                        typeof state.regions[regionId].traits === 'object'
                            ? state.regions[regionId].traits
                            : null;

                    if (
                        traits &&
                        Object.prototype
                            .hasOwnProperty
                            .call(
                                traits,
                                traitId
                            )
                    ) {
                        cell.textContent =
                            displayRuntimeValue(
                                traits[traitId]
                            );
                    }
                }
            );


        const debug =
            document.getElementById(
                'wayfarer-runtime-debug'
            );

        if (debug) {

            debug.textContent =
                JSON.stringify(
                    state,
                    null,
                    2
                );
        }
    }


    async function requestTick() {

        if (
            requestInFlight ||
            presentationActive
        ) {
            return null;
        }

        requestInFlight =
            true;

        renderControls();


        try {

            const response =
                await fetch(
                    config.endpoint,
                    {
                        method:
                            'POST',

                        headers: {
                            'Content-Type':
                                'application/json',

                            'Accept':
                                'application/json'
                        },

                        credentials:
                            'same-origin',

                        body:
                            JSON.stringify({
                                game_user_id:
                                    config.gameUserId,

                                csrf_token:
                                    config.csrfToken,

                                /* WAYFARER_BIDIRECTIONAL_TRAVEL_UI_V71 */
                                travel_direction:
                                    requestedTravelDirection
                            })
                    }
                );


            let data;

            try {

                data =
                    await response.json();

            } catch (error) {

                throw new Error(
                    'Tick endpoint did not return valid JSON.'
                );
            }


            if (
                !response.ok ||
                !data.ok
            ) {
                throw new Error(
                    data.error ||
                    'Tick request failed.'
                );
            }


            if (tickValue) {

                tickValue.textContent =
                    String(
                        data.tick
                    );
            }


            renderRuntimeState(
                data.state
            );

            /* WAYFARER_BIDIRECTIONAL_TRAVEL_UI_V71 */
            if (
                data.state &&
                data.state.navigation &&
                Object.prototype
                    .hasOwnProperty
                    .call(
                        data.state.navigation,
                        'direction'
                    )
            ) {
                requestedTravelDirection =
                    Number(
                        data.state.navigation.direction
                    ) < 0
                        ? -1
                        : 1;
            }

            renderPlayerContext(
                data.context
            );

            renderTravelStatus(
                data.travel
            );

            renderStoryletActions(
                data.actions
            );


            setMessage(
                'Tick ' +
                data.tick +
                ' saved.'
            );


            if (data.pause === true) {

                /*
                 * Suppress Action Mode during the brief interval before reload.
                 * The server-rendered presentation will exist after reload.
                 */
                presentationActive =
                    true;

                pauseRuntime(
                    data.pause_reason ||
                    'Travel interrupted.',
                    true
                );
            }


            return data;


        } catch (error) {

            pauseRuntime(
                error instanceof Error
                    ? error.message
                    : 'Tick request failed.'
            );

            setMessage(
                error instanceof Error
                    ? error.message
                    : 'Tick request failed.',
                true
            );

            return null;


        } finally {

            requestInFlight =
                false;

            renderControls();


            if (reloadWhenIdle) {

                reloadWhenIdle =
                    false;

                window.location.reload();
            }
        }
    }


    async function runAutomaticTick() {

        if (
            !running ||
            presentationActive
        ) {
            return;
        }


        const result =
            await requestTick();


        if (
            !running ||
            presentationActive ||
            result === null
        ) {
            return;
        }


        timeoutId =
            window.setTimeout(
                runAutomaticTick,
                Number(
                    config.intervalMs
                ) || 1500
            );
    }


    function startRuntime() {

        if (
            running ||
            requestInFlight ||
            presentationActive
        ) {
            return;
        }


        /*
         * Travel always leaves inspection/context views and returns the card to
         * its normal Action view for the next pause.
         */
        setActionView(
            'actions'
        );

        running =
            true;


        setMessage(
            'Automatic advancement started.'
        );


        renderControls();
        emitModeEvent();
        runAutomaticTick();
    }


    /*
     * WAYFARER_PRESENTATION_TRANSITION_V63
     *
     * Cover the current DOM before a server-rendered Presentation replaces it.
     * This prevents the previous Location/Storylet copy from being painted for
     * a frame during the navigation boundary.
     */
    function beginPresentationTransition() {
        body.classList.add(
            'wayfarer-presentation-transitioning'
        );
    }


    function pauseRuntime(
        reason = 'Automatic advancement paused.',
        reloadForPresentation = false
    ) {

        const wasRunning =
            running;


        running =
            false;


        if (timeoutId !== null) {

            window.clearTimeout(
                timeoutId
            );

            timeoutId =
                null;
        }


        setMessage(
            reason
        );

        if (wasRunning) {
            setActionView(
                'actions'
            );
        }


        renderControls();


        if (wasRunning) {
            emitModeEvent();
        }


        if (reloadForPresentation) {

            /* WAYFARER_PRESENTATION_TRANSITION_V63 */
            beginPresentationTransition();

            if (requestInFlight) {

                reloadWhenIdle =
                    true;

            } else {

                window.location.reload();
            }
        }
    }


    /*
     * WAYFARER_STORYLET_ACTION_RUNTIME_V59
     */
    async function requestStorylet(
        storyletId,
        entryMode = 'action',
        parentStoryletId = 0
    ) {

        if (
            storyletRequestInFlight ||
            requestInFlight ||
            presentationRequestInFlight
        ) {
            return;
        }

        storyletId =
            Number(storyletId || 0);

        parentStoryletId =
            Number(parentStoryletId || 0);

        if (storyletId <= 0) {
            return;
        }

        storyletRequestInFlight =
            true;

        renderControls();

        try {
            const response =
                await fetch(
                    config.storyletEndpoint ||
                    'api/storylet.php',
                    {
                        method: 'POST',
                        headers: {
                            'Content-Type':
                                'application/json',
                            'Accept':
                                'application/json'
                        },
                        credentials:
                            'same-origin',
                        body:
                            JSON.stringify({
                                game_user_id:
                                    config.gameUserId,
                                csrf_token:
                                    config.csrfToken,
                                storylet_id:
                                    storyletId,
                                entry_mode:
                                    entryMode,
                                parent_storylet_id:
                                    parentStoryletId
                            })
                    }
                );

            let data;

            try {
                data =
                    await response.json();
            } catch (error) {
                throw new Error(
                    'Storylet endpoint did not return valid JSON.'
                );
            }

            if (
                !response.ok ||
                !data.ok
            ) {
                throw new Error(
                    data.error ||
                    'Could not enter Storylet.'
                );
            }

            /*
             * Storylet presentation/Branch markup is server-rendered. Reload
             * only after the runtime transaction succeeds, so Effects cannot be
             * repeated by a failed or duplicate browser transition.
             */
            /* WAYFARER_PRESENTATION_TRANSITION_V63 */
            beginPresentationTransition();
            window.location.reload();

        } catch (error) {
            window.alert(
                error instanceof Error
                    ? error.message
                    : 'Could not enter Storylet.'
            );

        } finally {
            storyletRequestInFlight =
                false;

            renderControls();
        }
    }


    async function dismissPresentation() {

        if (
            !presentationActive ||
            !presentationScreen ||
            presentationRequestInFlight
        ) {
            return;
        }


        presentationRequestInFlight =
            true;

        if (presentationContinueButton) {
            presentationContinueButton.disabled =
                true;
        }


        const presentationType =
            presentationScreen.dataset
                .wayfarerPresentationType ||
            '';

        const presentationId =
            Number(
                presentationScreen.dataset
                    .wayfarerPresentationId ||
                0
            );


        try {

            const response =
                await fetch(
                    config.presentationEndpoint ||
                    'api/presentation.php',
                    {
                        method:
                            'POST',

                        headers: {
                            'Content-Type':
                                'application/json',

                            'Accept':
                                'application/json'
                        },

                        credentials:
                            'same-origin',

                        body:
                            JSON.stringify({
                                game_user_id:
                                    config.gameUserId,

                                csrf_token:
                                    config.csrfToken,

                                type:
                                    presentationType,

                                id:
                                    presentationId
                            })
                    }
                );


            let data;

            try {

                data =
                    await response.json();

            } catch (error) {

                throw new Error(
                    'Presentation endpoint did not return valid JSON.'
                );
            }


            if (
                !response.ok ||
                !data.ok
            ) {
                throw new Error(
                    data.error ||
                    'Could not continue.'
                );
            }


            presentationActive =
                false;

            setActionView(
                'actions'
            );

            renderRuntimeState(
                data.state
            );

            renderPlayerContext(
                data.context
            );

            renderStoryletActions(
                data.actions
            );

            renderControls();
            emitModeEvent();


            /*
             * Place keyboard focus on the first available Action so the
             * transition works cleanly for keyboard players too.
             */
            const firstAction =
                actionScreen
                    ? actionScreen.querySelector(
                        'button:not([disabled]), a[href]'
                    )
                    : null;

            if (
                firstAction &&
                typeof firstAction.focus ===
                    'function'
            ) {
                firstAction.focus();
            }


        } catch (error) {

            if (presentationContinueButton) {

                presentationContinueButton.disabled =
                    false;
            }

            window.alert(
                error instanceof Error
                    ? error.message
                    : 'Could not continue.'
            );


        } finally {

            presentationRequestInFlight =
                false;

            /* WAYFARER_PRESENTATION_CONTROL_RESET_V62
             *
             * dismissPresentation() previously refreshed Action controls while
             * presentationRequestInFlight was still true. Newly-rendered Manual
             * Storylet buttons were therefore left disabled after a Location or
             * Storylet presentation was dismissed. Re-render once the request
             * flag has actually been cleared.
             */
            renderControls();

            if (
                presentationContinueButton &&
                presentationActive
            ) {
                presentationContinueButton.disabled =
                    false;
            }
        }
    }


    if (onceButton) {

        onceButton.addEventListener(
            'click',
            async function () {

                if (
                    running ||
                    presentationActive
                ) {
                    return;
                }

                setMessage('');

                await requestTick();
            }
        );
    }


    if (autoButton) {

        autoButton.addEventListener(
            'click',
            startRuntime
        );
    }


    if (authorPauseButton) {

        authorPauseButton.addEventListener(
            'click',
            function () {

                pauseRuntime(
                    'Automatic advancement paused.'
                );
            }
        );
    }


    /* WAYFARER_PLAYER_TURN_AROUND_UI_V72 */
    if (turnAroundButton) {
        turnAroundButton.addEventListener(
            'click',
            function () {
                requestedTravelDirection =
                    requestedTravelDirection < 0
                        ? 1
                        : -1;

                startRuntime();
            }
        );
    }


    if (continueTravelButton) {

        continueTravelButton.addEventListener(
            'click',
            startRuntime
        );
    }


    if (playerPauseButton) {

        playerPauseButton.addEventListener(
            'click',
            function () {

                /*
                 * WAYFARER_SMOOTH_MANUAL_PAUSE_V46_2
                 *
                 * v46.1 keeps Action context current in-place, so manual Pause
                 * no longer needs a full page reload.
                 */
                pauseRuntime(
                    'Travel paused.'
                );
            }
        );
    }


    /*
     * WAYFARER_ACTION_UTILITY_VIEWS_V48
     */
    /*
     * WAYFARER_DYNAMIC_ACTION_SUBVIEWS_V51
     *
     * Ensure V50 detail panels physically belong to the Action card. This is
     * harmless when the PHP view already placed them correctly, and repairs
     * any earlier V50 markup that landed just outside the host.
     */
    if (actionScreen) {

        document
            .querySelectorAll(
                '.wayfarer-entity-detail-view'
            )
            .forEach(
                function (panel) {

                    if (
                        !actionScreen.contains(
                            panel
                        )
                    ) {
                        actionScreen.appendChild(
                            panel
                        );
                    }
                }
            );


        /*
         * Delegate navigation from the Action card itself. Any current or
         * future control using the generic data attributes automatically
         * participates in the same router.
         */
        actionScreen.addEventListener(
            'click',
            function (event) {

                const storyletAction =
                    event.target.closest(
                        '[data-wayfarer-storylet-action-id]'
                    );

                if (
                    storyletAction &&
                    actionScreen.contains(
                        storyletAction
                    )
                ) {
                    if (
                        running ||
                        presentationActive ||
                        storyletRequestInFlight
                    ) {
                        return;
                    }

                    event.preventDefault();

                    requestStorylet(
                        storyletAction.dataset
                            .wayfarerStoryletActionId,
                        'action',
                        0
                    );

                    return;
                }


                const opener =
                    event.target.closest(
                        '[data-wayfarer-open-action-view]'
                    );

                if (
                    opener &&
                    actionScreen.contains(
                        opener
                    )
                ) {

                    if (
                        running ||
                        presentationActive
                    ) {
                        return;
                    }

                    event.preventDefault();

                    setActionView(
                        opener.dataset
                            .wayfarerOpenActionView ||
                        'actions'
                    );

                    return;
                }


                const closer =
                    event.target.closest(
                        '[data-wayfarer-close-action-view]'
                    );

                if (
                    !closer ||
                    !actionScreen.contains(
                        closer
                    )
                ) {
                    return;
                }

                event.preventDefault();

                const returnView =
                    closer.dataset
                        .wayfarerReturnActionView ||
                    'actions';

                setActionView(
                    returnView
                );

                let focusTarget =
                    null;

                if (returnView === 'actions') {

                    focusTarget =
                        actionList
                            ? actionList.querySelector(
                                'button:not([disabled]), a[href]'
                            )
                            : null;

                } else {

                    const parentPanel =
                        actionScreen.querySelector(
                            '[data-wayfarer-action-view="' +
                            returnView +
                            '"]'
                        );

                    focusTarget =
                        parentPanel
                            ? parentPanel.querySelector(
                                '[data-wayfarer-open-action-view], button:not([disabled]), a[href]'
                            )
                            : null;
                }

                if (
                    focusTarget &&
                    typeof focusTarget.focus ===
                        'function'
                ) {
                    focusTarget.focus();
                }
            }
        );
    }

    /* WAYFARER_STORYLET_BRANCH_SELECTION_V59 */
    document.addEventListener(
        'click',
        function (event) {

            const branch =
                event.target.closest(
                    '[data-wayfarer-storylet-branch-id]'
                );

            if (!branch) {
                return;
            }

            if (
                !presentationActive ||
                storyletRequestInFlight
            ) {
                return;
            }

            event.preventDefault();

            requestStorylet(
                branch.dataset
                    .wayfarerStoryletBranchId,
                'branch',
                branch.dataset
                    .wayfarerStoryletParentId
            );
        }
    );


    if (presentationContinueButton) {

        presentationContinueButton.addEventListener(
            'click',
            dismissPresentation
        );
    }


    document.addEventListener(
        'keydown',
        function (event) {

            if (
                !presentationActive ||
                presentationRequestInFlight ||
                storyletRequestInFlight ||
                !presentationContinueButton
            ) {
                return;
            }


            const target =
                event.target;

            if (
                target &&
                target.matches &&
                target.matches(
                    'input, textarea, select, button, a[href], [contenteditable="true"]'
                )
            ) {
                return;
            }


            if (
                event.key !== 'Enter' &&
                event.key !== ' '
            ) {
                return;
            }


            event.preventDefault();

            dismissPresentation();
        }
    );


    window.addEventListener(
        'pagehide',
        function () {

            running =
                false;

            if (timeoutId !== null) {

                window.clearTimeout(
                    timeoutId
                );

                timeoutId =
                    null;
            }
        }
    );


    window.wayfarerRuntimeController = {

        start:
            startRuntime,

        pause:
            pauseRuntime,

        dismissPresentation:
            dismissPresentation,

        enterStorylet:
            requestStorylet,

        isRunning:
            function () {
                return running;
            },

        mode:
            function () {

                if (presentationActive) {
                    return 'presentation';
                }

                return running
                    ? 'running'
                    : 'paused';
            }
    };


    setActionView(
        'actions'
    );
    renderControls();
    emitModeEvent();

})();

/*
|--------------------------------------------------------------------------
| WAYFARER PLAY SHELL v20
|--------------------------------------------------------------------------
|
| Reorganizes existing server-rendered nodes into the viewport shell.
| Existing nodes are MOVED, not cloned/replaced, so the tick-control
| event listeners installed above remain intact.
|
*/

(() => {

    'use strict';

    if (
        document.getElementById(
            'wayfarer-play-shell'
        )
    ) {
        return;
    }


    function exactHeading(
        level,
        text
    ) {

        const headings =
            document.querySelectorAll(
                level
            );

        for (const heading of headings) {

            if (
                heading.textContent
                    .replace(/\s+/g, ' ')
                    .trim() === text
            ) {
                return heading;
            }
        }

        return null;
    }


    function moveRange(
        start,
        stopExclusive,
        destination
    ) {

        if (
            !start ||
            !destination
        ) {
            return;
        }

        let node =
            start;

        while (
            node &&
            node !== stopExclusive
        ) {

            const next =
                node.nextSibling;

            destination.appendChild(
                node
            );

            node =
                next;
        }
    }


    const body =
        document.body;

    /*
     * WAYFARER_ROLE_BASED_AUTHOR_MODE_V37
     *
     * PHP decides whether Author Mode is permitted. JavaScript only shapes the
     * interface around that server-side decision.
     */
    const canUseAuthorMode =
        body.dataset.wayfarerAuthorMode ===
        '1';

    body.classList.add(
        'wayfarer-play-page'
    );


    const shell =
        document.createElement(
            'div'
        );

    shell.id =
        'wayfarer-play-shell';

    shell.className =
        'wayfarer-play-shell';


    const header =
        document.createElement(
            'header'
        );

    header.className =
        'wayfarer-play-shell-header';


    const title =
        document.createElement(
            'div'
        );

    title.className =
        'wayfarer-play-title';


    const actions =
        document.createElement(
            'div'
        );

    actions.className =
        'wayfarer-shell-actions';


    const toggleAuthor =
        document.createElement(
            'button'
        );

    toggleAuthor.type =
        'button';

    toggleAuthor.className =
        'wayfarer-shell-button';


    if (canUseAuthorMode) {
        actions.appendChild(
            toggleAuthor
        );
    }

    header.appendChild(
        title
    );

    if (canUseAuthorMode) {
        header.appendChild(
            actions
        );
    }


    const main =
        document.createElement(
            'main'
        );

    main.className =
        'wayfarer-play-main';


    const playerPane =
        document.createElement(
            'section'
        );

    playerPane.className =
        'wayfarer-player-pane';


    const authorPane =
        document.createElement(
            'aside'
        );

    authorPane.className =
        'wayfarer-author-pane';


    const authorHeader =
        document.createElement(
            'div'
        );

    authorHeader.className =
        'wayfarer-author-header';


    const authorToolbar =
        document.createElement(
            'div'
        );

    authorToolbar.className =
        'wayfarer-author-toolbar';


    const tabBar =
        document.createElement(
            'div'
        );

    tabBar.className =
        'wayfarer-author-tabs';

    tabBar.setAttribute(
        'role',
        'tablist'
    );


    const authorContent =
        document.createElement(
            'div'
        );

    authorContent.className =
        'wayfarer-author-content';


    authorPane.appendChild(
        authorHeader
    );

    authorPane.appendChild(
        authorToolbar
    );

    authorPane.appendChild(
        tabBar
    );

    authorPane.appendChild(
        authorContent
    );


    main.appendChild(
        playerPane
    );

    if (canUseAuthorMode) {

        main.appendChild(
            authorPane
        );

    } else {

        /*
         * Keep the player workspace full-width when Author Mode is unavailable.
         * No Author pane was rendered by PHP and none is attached here.
         */
        shell.classList.add(
            'author-collapsed'
        );
    }


    shell.appendChild(
        header
    );

    shell.appendChild(
        main
    );


    body.insertBefore(
        shell,
        body.firstChild
    );


    // ------------------------------------------------------------
    // Top title/player identity
    // ------------------------------------------------------------

    const pageTitle =
        Array.from(
            body.querySelectorAll(
                ':scope > h1'
            )
        )[0];

    if (pageTitle) {

        const playerIdentity =
            pageTitle.nextElementSibling;

        title.appendChild(
            pageTitle
        );

        if (
            playerIdentity &&
            playerIdentity.tagName === 'P'
        ) {
            title.appendChild(
                playerIdentity
            );
        }
    }


    // ------------------------------------------------------------
    // Player content
    // ------------------------------------------------------------

    /*
     * WAYFARER_PLAYER_START_SCREEN_V36
     *
     * Before runtime state exists, the start screen owns the full player
     * workspace and Author Mode is intentionally hidden.
     */
    const startScreen =
        document.querySelector(
            '[data-wayfarer-start-screen]'
        );

    if (startScreen) {

        shell.classList.add(
            'is-starting'
        );

        playerPane.appendChild(
            startScreen
        );
    }
    const scene =
        document.getElementById(
            'wayfarer-player-scene'
        );

    const gameStateHeading =
        exactHeading(
            'h2',
            'Game State'
        )
        ||
        exactHeading(
            'h2',
            'Game Not Initialized'
        );

    if (gameStateHeading) {

        const meta =
            document.createElement(
                'div'
            );

        meta.className =
            'wayfarer-player-meta';

        /*
         * Move from Game State through the node immediately before the
         * player scene. This includes initialization messaging/forms but
         * stops before the actual scene.
         */
        moveRange(
            gameStateHeading,
            scene,
            meta
        );

        playerPane.appendChild(
            meta
        );
    }

    if (scene) {
        playerPane.appendChild(
            scene
        );
    }


    /*
     * WAYFARER_ACTION_SCREEN_V39
     *
     * Action Mode is player-facing and exists independently of Author Mode.
     */
    const actionScreen =
        document.querySelector(
            '[data-wayfarer-action-screen]'
        );

    if (actionScreen) {
        playerPane.appendChild(
            actionScreen
        );
    }


    /*
     * WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40
     */
    const presentationScreen =
        document.querySelector(
            '[data-wayfarer-presentation-screen]'
        );

    if (presentationScreen) {
        playerPane.appendChild(
            presentationScreen
        );
    }


    const travelControls =
        document.querySelector(
            '[data-wayfarer-travel-controls]'
        );

    if (travelControls) {
        playerPane.appendChild(
            travelControls
        );
    }


    /* WAYFARER_PLAYER_HUD_V64 */
    const persistentHud =
        document.querySelector(
            '[data-wayfarer-hud]'
        );

    if (persistentHud) {
        playerPane.appendChild(
            persistentHud
        );
    }


    // ------------------------------------------------------------
    // Author header
    // ------------------------------------------------------------

    const authorHeading =
        exactHeading(
            'h2',
            'Author Mode'
        );

    if (authorHeading) {

        const builderLinkBlock =
            authorHeading.nextElementSibling;

        authorHeader.appendChild(
            authorHeading
        );

        if (
            builderLinkBlock &&
            builderLinkBlock.tagName === 'P'
        ) {
            authorHeader.appendChild(
                builderLinkBlock
            );
        }
    }


    // ------------------------------------------------------------
    // Runtime controls
    // ------------------------------------------------------------

    const tickPanel =
        document.getElementById(
            'wayfarer-tick-test'
        );

    if (tickPanel) {
        authorToolbar.appendChild(
            tickPanel
        );
    }


    // ------------------------------------------------------------
    // Author tabs
    // ------------------------------------------------------------

    /* WAYFARER_COMBINED_AUTHOR_STATE_REGION_V41 */
    const panelDefinitions = [
        {
            key: 'state',
            label: 'State'
        },
        {
            key: 'debug',
            label: 'Debug'
        }
    ];


    function activateTab(key) {

        document
            .querySelectorAll(
                '.wayfarer-author-tab'
            )
            .forEach(
                function (button) {

                    const active =
                        button.dataset
                            .wayfarerAuthorTab === key;

                    button.classList.toggle(
                        'is-active',
                        active
                    );

                    button.setAttribute(
                        'aria-selected',
                        active
                            ? 'true'
                            : 'false'
                    );
                }
            );

        authorContent
            .querySelectorAll(
                '.wayfarer-author-tab-panel'
            )
            .forEach(
                function (panel) {

                    panel.classList.toggle(
                        'is-active',
                        panel.dataset
                            .wayfarerAuthorPanel === key
                    );
                }
            );

        try {
            window.localStorage.setItem(
                'wayfarerAuthorTab',
                key
            );
        } catch (error) {
            // Storage is optional.
        }
    }


    for (const definition of panelDefinitions) {

        const panel =
            document.querySelector(
                '[data-wayfarer-author-panel="' +
                definition.key +
                '"]'
            );

        if (!panel) {
            continue;
        }

        authorContent.appendChild(
            panel
        );

        const button =
            document.createElement(
                'button'
            );

        button.type =
            'button';

        button.className =
            'wayfarer-author-tab';

        button.dataset.wayfarerAuthorTab =
            definition.key;

        button.setAttribute(
            'role',
            'tab'
        );

        button.textContent =
            definition.label;

        button.addEventListener(
            'click',
            function () {
                activateTab(
                    definition.key
                );
            }
        );

        tabBar.appendChild(
            button
        );
    }


    let initialTab =
        'state';

    try {

        let savedTab =
            window.localStorage.getItem(
                'wayfarerAuthorTab'
            );

        if (
            savedTab ===
            'region'
        ) {
            savedTab =
                'state';

            window.localStorage.setItem(
                'wayfarerAuthorTab',
                'state'
            );
        }

        if (
            savedTab &&
            authorContent.querySelector(
                '[data-wayfarer-author-panel="' +
                savedTab +
                '"]'
            )
        ) {
            initialTab =
                savedTab;
        }

    } catch (error) {
        // Storage is optional.
    }

    activateTab(
        initialTab
    );


    // ------------------------------------------------------------
    // Hide / Show Author Mode
    // WAYFARER_ROLE_BASED_AUTHOR_MODE_V37
    // ------------------------------------------------------------

    if (canUseAuthorMode) {

        function renderAuthorToggle() {

            const collapsed =
                shell.classList.contains(
                    'author-collapsed'
                );

            toggleAuthor.textContent =
                collapsed
                    ? 'Show Author'
                    : 'Hide Author';

            toggleAuthor.setAttribute(
                'aria-expanded',
                collapsed
                    ? 'false'
                    : 'true'
            );
        }


        toggleAuthor.addEventListener(
            'click',
            function () {

                shell.classList.toggle(
                    'author-collapsed'
                );

                try {

                    window.localStorage.setItem(
                        'wayfarerAuthorCollapsed',
                        shell.classList.contains(
                            'author-collapsed'
                        )
                            ? '1'
                            : '0'
                    );

                } catch (error) {
                    // Storage is optional.
                }

                renderAuthorToggle();
            }
        );


        try {

            if (
                window.localStorage.getItem(
                    'wayfarerAuthorCollapsed'
                ) === '1'
            ) {
                shell.classList.add(
                    'author-collapsed'
                );
            }

        } catch (error) {
            // Storage is optional.
        }


        renderAuthorToggle();

    } else {

        /*
         * Player role is not merely a hidden Author interface. Keep the shell
         * permanently in player-only layout.
         */
        shell.classList.add(
            'author-collapsed'
        );
    }

    // ------------------------------------------------------------
    // Remove otherwise-empty top-level HRs left by the old document flow.
    // ------------------------------------------------------------

    body
        .querySelectorAll(
            ':scope > hr'
        )
        .forEach(
            function (rule) {
                rule.remove();
            }
        );

})();

/*
|--------------------------------------------------------------------------
| ENDING RESTART
| WAYFARER_ENDING_RESTART_V63
|--------------------------------------------------------------------------
*/
(() => {
    'use strict';

    const config =
        window.wayfarerTickRuntime;

    const restartButton =
        document.querySelector(
            '[data-wayfarer-restart-game]'
        );

    if (
        !config ||
        !restartButton
    ) {
        return;
    }

    let requestInFlight =
        false;

    restartButton.addEventListener(
        'click',
        async function () {

            if (requestInFlight) {
                return;
            }

            if (
                !window.confirm(
                    'Start this game over? Your current playthrough progress will be erased.'
                )
            ) {
                return;
            }

            requestInFlight =
                true;

            restartButton.disabled =
                true;

            const originalText =
                restartButton.textContent;

            restartButton.textContent =
                'Starting over…';

            try {

                const response =
                    await fetch(
                        config.restartEndpoint ||
                        'api/restart.php',
                        {
                            method: 'POST',
                            headers: {
                                'Content-Type':
                                    'application/json',
                                'Accept':
                                    'application/json'
                            },
                            credentials:
                                'same-origin',
                            body:
                                JSON.stringify({
                                    game_user_id:
                                        config.gameUserId,
                                    csrf_token:
                                        config.csrfToken
                                })
                        }
                    );

                let data;

                try {
                    data =
                        await response.json();
                } catch (error) {
                    throw new Error(
                        'Restart endpoint did not return valid JSON.'
                    );
                }

                if (
                    !response.ok ||
                    !data.ok
                ) {
                    throw new Error(
                        data.error ||
                        'Could not restart the game.'
                    );
                }

                document.body.classList.add(
                    'wayfarer-presentation-transitioning'
                );

                window.location.href =
                    'index.php';

            } catch (error) {

                requestInFlight =
                    false;

                restartButton.disabled =
                    false;

                restartButton.textContent =
                    originalText;

                window.alert(
                    error instanceof Error
                        ? error.message
                        : 'Could not restart the game.'
                );
            }
        }
    );
})();


==============================================================================
FILE: play/includes/action-screen.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Player Action Screen
 * WAYFARER_ACTION_SCREEN_V39
 * WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40
 * WAYFARER_ACTION_UTILITY_VIEWS_V48
 * WAYFARER_ENTITY_PRESENTATION_V49
 * WAYFARER_ENTITY_DETAIL_VIEW_V50
 * WAYFARER_PLAYER_TRAITS_STATUS_V52
 * --------------------------------------------------------------------------
 *
 * Action Mode shows the most specific current spatial context:
 *
 *     current Location name
 *     otherwise current Region name
 *
 * Context-specific authored actions will later be supplied by eligible
 * Storylets. Continue Travel remains a navigation-system action.
 */

$actionRegionId =
    (int)(
        $state['navigation']['region_id']
        ?? 0
    );

$actionRegion =
    null;

$actionRegionNavigationType =
    '';

$actionContextName =
    'Actions';


if ($actionRegionId > 0) {

    $actionRegionStmt =
        $pdo->prepare(
            "
            SELECT
                id,
                name,
                navigation_type
            FROM wf_regions
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

    $actionRegionStmt->execute([
        $actionRegionId,
        (int)$gameId,
    ]);

    $actionRegion =
        $actionRegionStmt->fetch(
            PDO::FETCH_ASSOC
        );

    if ($actionRegion) {

        $actionRegionNavigationType =
            (string)(
                $actionRegion['navigation_type']
                ?? ''
            );

        $actionContextName =
            trim(
                (string)(
                    $actionRegion['name']
                    ?? ''
                )
            ) ?: 'Actions';
    }
}


$actionLocation =
    wayfarerRuntimeFindCurrentLocation(
        $pdo,
        (int)$gameId,
        $state
    );

if ($actionLocation) {

    $locationName =
        trim(
            (string)(
                $actionLocation['name']
                ?? ''
            )
        );

    if ($locationName !== '') {
        $actionContextName =
            $locationName;
    }
}


$actionCanTravel =
    strtolower(
        trim(
            $actionRegionNavigationType
        )
    ) === 'linear';


/* WAYFARER_STORYLET_ACTION_SCREEN_V59 */
$actionStorylets =
    wayfarerRuntimeEligibleRootManualStorylets(
        $pdo,
        (int)$gameId,
        $state
    );


/*
 * WAYFARER_ENTITY_PRESENTATION_V49
 *
 * The V48 card switcher remains generic. V49 supplies the Inventory / Status
 * view models from canonical runtime Entity state.
 */
$actionEntityPresentation =
    wayfarerRuntimeBuildEntityPresentation(
        $pdo,
        (int)$gameId,
        $state,
        is_array($gameConfig ?? null)
            ? $gameConfig
            : []
    );

$actionInventory =
    $actionEntityPresentation['inventory']
    ?? [];

$actionParty =
    $actionEntityPresentation['party']
    ?? [];

/* WAYFARER_PLAYER_TRAITS_STATUS_V52 */
$actionPlayerPresentation =
    wayfarerRuntimeBuildPlayerPresentation(
        is_array($gameConfig ?? null)
            ? $gameConfig
            : [],
        $state
    );

$actionPlayers =
    $actionPlayerPresentation['players']
    ?? [];

$actionGameStatusTraits =
    $actionPlayerPresentation['game_status_traits']
    ?? [];

/* WAYFARER_STATUSES_PRESENTATION_V87 */
foreach ($actionPlayers as &$actionStatusPlayer) {
    $slot =
        (int)(
            $actionStatusPlayer['slot']
            ?? 0
        );

    $actionStatusPlayer['statuses'] =
        wayfarerRuntimeVisibleStatusesForScope(
            $pdo,
            (int)$gameId,
            $state,
            'player:' . $slot
        );
}
unset($actionStatusPlayer);

foreach ($actionParty as &$actionStatusCharacter) {
    $entityId =
        (int)(
            $actionStatusCharacter['id']
            ?? 0
        );

    $actionStatusCharacter['statuses'] =
        $entityId > 0
            ? wayfarerRuntimeVisibleStatusesForScope(
                $pdo,
                (int)$gameId,
                $state,
                'entity:' . $entityId
            )
            : [];
}
unset($actionStatusCharacter);

/*
 * WAYFARER_STATUS_TRAIT_DISPLAY_V86
 *
 * Status Traits may render as a Number, a Bar, or Both. Runtime presentation
 * metadata already falls back to Number when a bar cannot be calculated.
 */
$renderStatusTrait =
    static function (
        array $trait
    ): void {
        $name =
            trim(
                (string)(
                    $trait['name']
                    ?? ''
                )
            );

        $value =
            (string)(
                $trait['value']
                ?? ''
            );

        $mode =
            strtolower(
                trim(
                    (string)(
                        $trait['display_mode']
                        ?? 'number'
                    )
                )
            );

        if (
            !in_array(
                $mode,
                ['number', 'bar', 'both'],
                true
            )
        ) {
            $mode =
                'number';
        }

        $showBar =
            !empty(
                $trait['bar_available']
            ) &&
            is_numeric(
                $trait['bar_percent']
                ?? null
            ) &&
            (
                $mode === 'bar' ||
                $mode === 'both'
            );

        if (!$showBar && $mode !== 'number') {
            $mode =
                'number';
        }

        $showValue =
            $mode === 'number' ||
            $mode === 'both';

        $percent =
            $showBar
                ? max(
                    0,
                    min(
                        100,
                        (float)$trait['bar_percent']
                    )
                )
                : 0;

        $minimum =
            $trait['bar_min']
            ?? 0;

        $maximum =
            $trait['bar_max']
            ?? 100;

        $current =
            $trait['bar_value']
            ?? 0;
        ?>
        <div
            class="wayfarer-status-trait wayfarer-status-trait--<?= htmlspecialchars(
                $mode,
                ENT_QUOTES,
                'UTF-8'
            ) ?>"
        >
            <dt>
                <?= htmlspecialchars(
                    $name
                ) ?>
            </dt>

            <dd>
                <?php if ($showBar): ?>
                    <div
                        class="wayfarer-status-trait-bar"
                        role="progressbar"
                        aria-label="<?= htmlspecialchars(
                            $name .
                            ': ' .
                            $value,
                            ENT_QUOTES,
                            'UTF-8'
                        ) ?>"
                        aria-valuemin="<?= htmlspecialchars(
                            (string)$minimum,
                            ENT_QUOTES,
                            'UTF-8'
                        ) ?>"
                        aria-valuemax="<?= htmlspecialchars(
                            (string)$maximum,
                            ENT_QUOTES,
                            'UTF-8'
                        ) ?>"
                        aria-valuenow="<?= htmlspecialchars(
                            (string)$current,
                            ENT_QUOTES,
                            'UTF-8'
                        ) ?>"
                    >
                        <span
                            style="width:<?= htmlspecialchars(
                                number_format(
                                    $percent,
                                    4,
                                    '.',
                                    ''
                                ),
                                ENT_QUOTES,
                                'UTF-8'
                            ) ?>%"
                            aria-hidden="true"
                        ></span>
                    </div>
                <?php endif; ?>

                <?php if ($showValue): ?>
                    <span class="wayfarer-status-trait-value">
                        <?= htmlspecialchars(
                            $value
                        ) ?>
                    </span>
                <?php endif; ?>
            </dd>
        </div>
        <?php
    };

/* WAYFARER_TRAVEL_TIME_HUD_V61 */
$actionTravelStatus =
    wayfarerRuntimeBuildTravelStatus(
        $pdo,
        (int)$gameId,
        $state
    );

?>
<style>
/* WAYFARER_STATUS_TRAIT_DISPLAY_V86 */
.wayfarer-status-values > .wayfarer-status-trait {
    display: grid;
    grid-template-columns: minmax(0, 1fr) minmax(180px, 2fr);
    gap: 10px 16px;
    align-items: center;
}

.wayfarer-status-values > .wayfarer-status-trait dd {
    display: flex;
    align-items: center;
    gap: 10px;
    min-width: 0;
    margin: 0;
}

.wayfarer-status-trait-value {
    margin-left: auto;
    white-space: nowrap;
}

.wayfarer-status-trait-bar {
    flex: 1 1 180px;
    min-width: 120px;
    height: 10px;
    overflow: hidden;
    border-radius: 999px;
    background: rgba(95, 105, 120, 0.18);
}

.wayfarer-status-trait-bar > span {
    display: block;
    height: 100%;
    border-radius: inherit;
    background: currentColor;
    opacity: 0.7;
}

/* WAYFARER_STATUSES_PRESENTATION_V87 */
.wayfarer-person-statuses {
    display: grid;
    gap: 8px;
    margin-top: 12px;
}

.wayfarer-person-status {
    padding: 9px 11px;
    border: 1px solid rgba(95, 105, 120, 0.22);
    border-radius: 7px;
    background: rgba(95, 105, 120, 0.06);
}

.wayfarer-person-status strong,
.wayfarer-person-status small {
    display: block;
}

.wayfarer-person-status small {
    margin-top: 3px;
    opacity: 0.78;
}

/* WAYFARER_STATUS_LIFECYCLE_PRESENTATION_V88 */
.wayfarer-person-status-stage,
.wayfarer-person-status-time {
    font-weight: 600;
}

@media (max-width: 640px) {
    .wayfarer-status-values > .wayfarer-status-trait {
        grid-template-columns: 1fr;
        gap: 4px;
    }

    .wayfarer-status-values > .wayfarer-status-trait dd {
        width: 100%;
    }
}
</style>
<section
    class="wayfarer-action-screen"
    data-wayfarer-action-screen
    data-wayfarer-can-travel="<?= $actionCanTravel ? '1' : '0' ?>"
>
    <header class="wayfarer-action-heading">
        <!-- WAYFARER_LIVE_ACTION_CONTEXT_V46_1 -->
        <h2 data-wayfarer-action-context-name>
            <?= htmlspecialchars(
                $actionContextName
            ) ?>
        </h2>

        <?php
        $actionParentContext =
            (
                $actionLocation &&
                $actionRegion
            )
                ? trim(
                    (string)(
                        $actionRegion['name']
                        ?? ''
                    )
                )
                : '';
        ?>

        <p
            class="wayfarer-action-parent-context"
            data-wayfarer-action-parent-context
            <?= $actionParentContext === ''
                ? 'hidden'
                : '' ?>
        >
            <?= htmlspecialchars(
                $actionParentContext
            ) ?>
        </p>

        <p>
            What would you like to do?
        </p>
    </header>

    <div
        class="wayfarer-action-list"
        data-wayfarer-action-list
    >
        <!-- WAYFARER_STORYLET_ACTION_SCREEN_V59 -->
        <div
            class="wayfarer-storylet-action-list"
            data-wayfarer-storylet-actions
        >
            <?php foreach ($actionStorylets as $storyletAction): ?>
                <button
                    type="button"
                    class="wayfarer-action-button"
                    data-wayfarer-storylet-action-id="<?= (int)$storyletAction['id'] ?>"
                >
                    <?= htmlspecialchars(
                        (string)(
                            $storyletAction['label']
                            ?? $storyletAction['name']
                            ?? 'Storylet'
                        )
                    ) ?>
                </button>
            <?php endforeach; ?>
        </div>

        <?php if ($actionCanTravel): ?>

            <button
                type="button"
                class="wayfarer-action-button"
                data-wayfarer-continue-travel
            >
                Continue Travel
            </button>

            <!-- WAYFARER_PLAYER_TURN_AROUND_V72 -->
            <?php if (
                !empty(
                    $actionTravelStatus[
                        'can_turn_around'
                    ]
                )
            ): ?>

                <button
                    type="button"
                    class="wayfarer-action-button"
                    data-wayfarer-turn-around
                >
                    Turn Around
                </button>

            <?php endif; ?>

        <?php elseif (!$actionStorylets): ?>

            <p
                class="wayfarer-action-empty"
                data-wayfarer-action-empty
            >
                No actions are currently available.
            </p>

        <?php else: ?>

            <p
                class="wayfarer-action-empty"
                data-wayfarer-action-empty
                hidden
            >
                No actions are currently available.
            </p>

        <?php endif; ?>

        <!-- WAYFARER_ACTION_UTILITY_VIEWS_V48 -->
        <div class="wayfarer-action-utility-row">
            <button
                type="button"
                class="wayfarer-action-utility-button"
                data-wayfarer-open-action-view="inventory"
            >
                Inventory
            </button>

            <button
                type="button"
                class="wayfarer-action-utility-button"
                data-wayfarer-open-action-view="status"
            >
                Status
            </button>
        </div>
    </div>

    <div
        class="wayfarer-action-subview"
        data-wayfarer-action-view="inventory"
        hidden
    >
        <header class="wayfarer-action-subview-heading">
            <h2>Inventory</h2>

            <button
                type="button"
                class="wayfarer-action-back-button"
                data-wayfarer-close-action-view
            >
                Back
            </button>
        </header>

        <div
            class="wayfarer-action-subview-body"
            data-wayfarer-inventory-view
        >
            <?php if (empty($actionInventory)): ?>

                <p class="wayfarer-action-empty">
                    Inventory is empty.
                </p>

            <?php else: ?>

                <div class="wayfarer-inventory-list">

                    <?php foreach ($actionInventory as $item): ?>

                        <article class="wayfarer-inventory-item">

                            <div class="wayfarer-inventory-item-heading">

                                <button
                                    type="button"
                                    class="wayfarer-entity-open-button"
                                    data-wayfarer-open-action-view="entity-item-<?= (int)($item['id'] ?? 0) ?>"
                                >
                                    <?= htmlspecialchars(
                                        (string)(
                                            $item['name']
                                            ?? 'Item'
                                        )
                                    ) ?>
                                </button>

                                <span class="wayfarer-inventory-quantity">
                                    Quantity:
                                    <?= htmlspecialchars(
                                        (string)(
                                            $item['quantity']
                                            ?? '0'
                                        )
                                    ) ?>
                                </span>
                            </div>

                            <?php if (!empty($item['traits'])): ?>

                                <dl class="wayfarer-status-values">

                                    <?php foreach (
                                        $item['traits']
                                        as $trait
                                    ): ?>

                                        <div>
                                            <dt>
                                                <?= htmlspecialchars(
                                                    (string)(
                                                        $trait['name']
                                                        ?? ''
                                                    )
                                                ) ?>
                                            </dt>

                                            <dd>
                                                <?= htmlspecialchars(
                                                    (string)(
                                                        $trait['value']
                                                        ?? ''
                                                    )
                                                ) ?>
                                            </dd>
                                        </div>

                                    <?php endforeach; ?>

                                </dl>

                            <?php endif; ?>

                        </article>

                    <?php endforeach; ?>

                </div>

            <?php endif; ?>
        </div>
    </div>

    <div
        class="wayfarer-action-subview"
        data-wayfarer-action-view="status"
        hidden
    >
        <header class="wayfarer-action-subview-heading">
            <h2>Status</h2>

            <button
                type="button"
                class="wayfarer-action-back-button"
                data-wayfarer-close-action-view
            >
                Back
            </button>
        </header>

        <div
            class="wayfarer-action-subview-body"
            data-wayfarer-status-view
        >
            <!-- WAYFARER_PLAYER_TRAITS_STATUS_V52 -->
            <?php if (
                !empty($actionPlayers) ||
                !empty($actionParty)
            ): ?>

                <section class="wayfarer-status-section">
                    <h3>Party</h3>

                    <div class="wayfarer-party-list">

                        <?php foreach ($actionPlayers as $player): ?>

                            <article class="wayfarer-party-member wayfarer-player-member">
                                <h4>
                                    <?= htmlspecialchars(
                                        (string)(
                                            $player['name']
                                            ?? 'Player'
                                        )
                                    ) ?>
                                </h4>

                                <?php if (!empty($player['traits'])): ?>

                                    <dl class="wayfarer-status-values">

                                        <?php foreach (
                                            $player['traits']
                                            as $trait
                                        ): ?>

                                            <?php
                                            $renderStatusTrait(
                                                $trait
                                            );
                                            ?>

                                        <?php endforeach; ?>

                                    </dl>

                                <?php endif; ?>

                                <?php if (!empty($player['statuses'])): ?>
                                    <div class="wayfarer-person-statuses">
                                        <?php foreach ($player['statuses'] as $status): ?>
                                            <div class="wayfarer-person-status">
                                                <strong><?= htmlspecialchars((string)($status['name'] ?? 'Status')) ?></strong>
                                                <?php if (trim((string)($status['stage_name'] ?? '')) !== ''): ?>
                                                    <small class="wayfarer-person-status-stage">
                                                        Stage: <?= htmlspecialchars((string)$status['stage_name']) ?>
                                                    </small>
                                                <?php endif; ?>
                                                <?php if (($status['remaining_ticks'] ?? null) !== null): ?>
                                                    <small class="wayfarer-person-status-time">
                                                        <?= (int)$status['remaining_ticks'] ?> tick<?= (int)$status['remaining_ticks'] === 1 ? '' : 's' ?> remaining
                                                    </small>
                                                <?php endif; ?>
                                                <?php if (trim((string)($status['description'] ?? '')) !== ''): ?>
                                                    <small><?= htmlspecialchars((string)$status['description']) ?></small>
                                                <?php endif; ?>
                                            </div>
                                        <?php endforeach; ?>
                                    </div>
                                <?php endif; ?>

                                <?php if (
                                    empty($player['traits']) &&
                                    empty($player['statuses'])
                                ): ?>
                                    <p class="wayfarer-status-muted">
                                        No player-visible traits or Statuses.
                                    </p>
                                <?php endif; ?>
                            </article>

                        <?php endforeach; ?>


                        <?php foreach ($actionParty as $character): ?>

                            <article class="wayfarer-party-member">
                                <h4>
                                    <button
                                        type="button"
                                        class="wayfarer-entity-open-button"
                                        data-wayfarer-open-action-view="entity-character-<?= (int)($character['id'] ?? 0) ?>"
                                    >
                                        <?= htmlspecialchars(
                                            (string)(
                                                $character['name']
                                                ?? 'Character'
                                            )
                                        ) ?>
                                    </button>
                                </h4>

                                <?php if (!empty($character['traits'])): ?>

                                    <dl class="wayfarer-status-values">

                                        <?php foreach (
                                            $character['traits']
                                            as $trait
                                        ): ?>

                                            <?php
                                            $renderStatusTrait(
                                                $trait
                                            );
                                            ?>

                                        <?php endforeach; ?>

                                    </dl>

                                <?php endif; ?>

                                <?php if (!empty($character['statuses'])): ?>
                                    <div class="wayfarer-person-statuses">
                                        <?php foreach ($character['statuses'] as $status): ?>
                                            <div class="wayfarer-person-status">
                                                <strong><?= htmlspecialchars((string)($status['name'] ?? 'Status')) ?></strong>
                                                <?php if (trim((string)($status['stage_name'] ?? '')) !== ''): ?>
                                                    <small class="wayfarer-person-status-stage">
                                                        Stage: <?= htmlspecialchars((string)$status['stage_name']) ?>
                                                    </small>
                                                <?php endif; ?>
                                                <?php if (($status['remaining_ticks'] ?? null) !== null): ?>
                                                    <small class="wayfarer-person-status-time">
                                                        <?= (int)$status['remaining_ticks'] ?> tick<?= (int)$status['remaining_ticks'] === 1 ? '' : 's' ?> remaining
                                                    </small>
                                                <?php endif; ?>
                                                <?php if (trim((string)($status['description'] ?? '')) !== ''): ?>
                                                    <small><?= htmlspecialchars((string)$status['description']) ?></small>
                                                <?php endif; ?>
                                            </div>
                                        <?php endforeach; ?>
                                    </div>
                                <?php endif; ?>

                                <?php if (
                                    empty($character['traits']) &&
                                    empty($character['statuses'])
                                ): ?>
                                    <p class="wayfarer-status-muted">
                                        No player-visible traits or Statuses.
                                    </p>
                                <?php endif; ?>
                            </article>

                        <?php endforeach; ?>
                    </div>
                </section>

            <?php endif; ?>


            <?php if (!empty($actionGameStatusTraits)): ?>

                <section class="wayfarer-status-section">
                    <h3>Game</h3>

                    <dl class="wayfarer-status-values">

                        <?php foreach (
                            $actionGameStatusTraits
                            as $trait
                        ): ?>

                            <?php
                            $renderStatusTrait(
                                $trait
                            );
                            ?>

                        <?php endforeach; ?>

                    </dl>
                </section>

            <?php endif; ?>


            <?php if (
                empty($actionPlayers) &&
                empty($actionParty) &&
                empty($actionGameStatusTraits)
            ): ?>

                <p class="wayfarer-action-empty">
                    Nothing to display.
                </p>

            <?php endif; ?>
        </div>
    </div>
</section>


<section
    class="wayfarer-travel-controls"
    data-wayfarer-travel-controls
    hidden
>
    <!-- WAYFARER_TRAVEL_TIME_HUD_V61 -->
    <div class="wayfarer-travel-status">
        <span
            class="wayfarer-travel-indicator"
            aria-hidden="true"
        ></span>

        <div class="wayfarer-travel-copy">
            <div class="wayfarer-travel-primary">
                <span
                    class="wayfarer-travel-time"
                    data-wayfarer-travel-time
                    <?= empty($actionTravelStatus['time_label']) ? 'hidden' : '' ?>
                ><?= htmlspecialchars((string)($actionTravelStatus['time_label'] ?? '')) ?></span>
                <span
                    class="wayfarer-travel-time-separator"
                    data-wayfarer-travel-time-separator
                    <?= empty($actionTravelStatus['time_label']) ? 'hidden' : '' ?>
                >·</span>
                <span>Traveling…</span>
            </div>

            <div
                class="wayfarer-travel-next"
                data-wayfarer-travel-next
                <?= empty($actionTravelStatus['next_label']) ? 'hidden' : '' ?>
            >
                Next: <?= htmlspecialchars((string)($actionTravelStatus['next_label'] ?? '')) ?>
            </div>
        </div>
    </div>

    <button
        type="button"
        class="wayfarer-travel-pause"
        data-wayfarer-pause-travel
    >
        Pause
    </button>
    <!-- ============================================================
         ENTITY DETAIL VIEWS
         WAYFARER_ENTITY_DETAIL_VIEW_V50
         ============================================================ -->

    <?php foreach ($actionInventory as $item): ?>

        <div
            class="wayfarer-action-subview wayfarer-entity-detail-view"
            data-wayfarer-action-view="entity-item-<?= (int)($item['id'] ?? 0) ?>"
            hidden
        >
            <header class="wayfarer-action-subview-heading">
                <div>
                    <p class="wayfarer-entity-detail-eyebrow">Item</p>
                    <h2>
                        <?= htmlspecialchars(
                            (string)(
                                $item['name']
                                ?? 'Item'
                            )
                        ) ?>
                    </h2>
                </div>

                <button
                    type="button"
                    class="wayfarer-action-back-button"
                    data-wayfarer-close-action-view
                    data-wayfarer-return-action-view="inventory"
                >
                    Back
                </button>
            </header>

            <div class="wayfarer-entity-detail-layout">

                <?php if (
                    trim(
                        (string)(
                            $item['image_url']
                            ?? ''
                        )
                    ) !== ''
                ): ?>

                    <figure class="wayfarer-entity-detail-media">
                        <img
                            src="<?= htmlspecialchars(
                                (string)$item['image_url'],
                                ENT_QUOTES,
                                'UTF-8'
                            ) ?>"
                            alt=""
                        >
                    </figure>

                <?php endif; ?>

                <div class="wayfarer-entity-detail-copy">

                    <?php if (
                        trim(
                            (string)(
                                $item['description']
                                ?? ''
                            )
                        ) !== ''
                    ): ?>

                        <p class="wayfarer-entity-detail-description">
                            <?= nl2br(
                                htmlspecialchars(
                                    (string)$item['description']
                                )
                            ) ?>
                        </p>

                    <?php endif; ?>

                    <dl class="wayfarer-status-values">

                        <div>
                            <dt>Quantity</dt>
                            <dd>
                                <?= htmlspecialchars(
                                    (string)(
                                        $item['quantity']
                                        ?? '0'
                                    )
                                ) ?>
                            </dd>
                        </div>

                        <?php foreach (
                            $item['traits']
                            ?? []
                            as $trait
                        ): ?>

                            <div>
                                <dt>
                                    <?= htmlspecialchars(
                                        (string)(
                                            $trait['name']
                                            ?? ''
                                        )
                                    ) ?>
                                </dt>
                                <dd>
                                    <?= htmlspecialchars(
                                        (string)(
                                            $trait['value']
                                            ?? ''
                                        )
                                    ) ?>
                                </dd>
                            </div>

                        <?php endforeach; ?>

                    </dl>

                </div>
            </div>
        </div>

    <?php endforeach; ?>


    <?php foreach ($actionParty as $character): ?>

        <div
            class="wayfarer-action-subview wayfarer-entity-detail-view"
            data-wayfarer-action-view="entity-character-<?= (int)($character['id'] ?? 0) ?>"
            hidden
        >
            <header class="wayfarer-action-subview-heading">
                <div>
                    <p class="wayfarer-entity-detail-eyebrow">Character</p>
                    <h2>
                        <?= htmlspecialchars(
                            (string)(
                                $character['name']
                                ?? 'Character'
                            )
                        ) ?>
                    </h2>
                </div>

                <button
                    type="button"
                    class="wayfarer-action-back-button"
                    data-wayfarer-close-action-view
                    data-wayfarer-return-action-view="status"
                >
                    Back
                </button>
            </header>

            <div class="wayfarer-entity-detail-layout">

                <?php if (
                    trim(
                        (string)(
                            $character['image_url']
                            ?? ''
                        )
                    ) !== ''
                ): ?>

                    <figure class="wayfarer-entity-detail-media">
                        <img
                            src="<?= htmlspecialchars(
                                (string)$character['image_url'],
                                ENT_QUOTES,
                                'UTF-8'
                            ) ?>"
                            alt=""
                        >
                    </figure>

                <?php endif; ?>

                <div class="wayfarer-entity-detail-copy">

                    <?php if (
                        trim(
                            (string)(
                                $character['description']
                                ?? ''
                            )
                        ) !== ''
                    ): ?>

                        <p class="wayfarer-entity-detail-description">
                            <?= nl2br(
                                htmlspecialchars(
                                    (string)$character['description']
                                )
                            ) ?>
                        </p>

                    <?php endif; ?>

                    <?php if (!empty($character['traits'])): ?>

                        <dl class="wayfarer-status-values">

                            <?php foreach (
                                $character['traits']
                                as $trait
                            ): ?>

                                <?php
                                $renderStatusTrait(
                                    $trait
                                );
                                ?>

                            <?php endforeach; ?>

                        </dl>

                    <?php endif; ?>

                </div>
            </div>
        </div>

    <?php endforeach; ?>

</section>


==============================================================================
FILE: play/includes/applicable-traits.v15-disabled.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Applicable Traits - v15
|--------------------------------------------------------------------------
|
| Current definition of "applicable":
|
|   - Game Traits
|   - Traits on the player's current Region
|
| More scopes can be added later without changing the basic table contract.
|
*/

require_once __DIR__ . '/runtime.php';

if (
    !isset($pdo) ||
    !($pdo instanceof PDO)
) {
    require_once __DIR__ . '/../../config/database.php';
}

$applicableTraitsError =
    '';

$applicableTraitRows =
    [];

$applicableRegion =
    null;

try {

    $requestedGameUserId =
        isset($_GET['game_user_id'])
            ? (int)$_GET['game_user_id']
            : null;

    $applicableGameUserId =
        wayfarerRuntimeResolveGameUserId(
            $pdo,
            $requestedGameUserId
        );

    $applicableContext =
        wayfarerRuntimeEnsureInitialContext(
            $pdo,
            $applicableGameUserId
        );

    $applicableTraitRows =
        wayfarerRuntimeApplicableTraitRows(
            $applicableContext
        );

    $applicableRegion =
        $applicableContext['region']
        ?? null;

} catch (Throwable $exception) {

    $applicableTraitsError =
        $exception->getMessage();
}

?>

<h3>Applicable Traits</h3>

<?php if ($applicableTraitsError !== ''): ?>

    <p style="color:red;">
        <?= htmlspecialchars(
            $applicableTraitsError
        ) ?>
    </p>

<?php else: ?>

    <?php if ($applicableRegion): ?>

        <p>
            Current Region:
            <strong>
                <?= htmlspecialchars(
                    (string)$applicableRegion['name']
                ) ?>
            </strong>
            (ID <?= (int)$applicableRegion['id'] ?>)
        </p>

    <?php else: ?>

        <p>
            <strong>No current Region.</strong>
            The game does not currently resolve to a valid authored
            starting Region.
        </p>

    <?php endif; ?>

    <?php if ($applicableTraitRows): ?>

        <table border="1" cellpadding="6" cellspacing="0">
            <thead>
                <tr>
                    <th>Scope</th>
                    <th>Trait</th>
                    <th>Current Value</th>
                    <th>Type</th>
                </tr>
            </thead>

            <tbody>

            <?php foreach ($applicableTraitRows as $row): ?>

                <?php
                $displayValue =
                    $row['value'];

                if (is_bool($displayValue)) {
                    $displayValue =
                        $displayValue
                            ? 'true'
                            : 'false';
                } elseif ($displayValue === null) {
                    $displayValue =
                        'null';
                } elseif (is_array($displayValue)) {
                    $displayValue =
                        json_encode(
                            $displayValue,
                            JSON_UNESCAPED_SLASHES |
                            JSON_UNESCAPED_UNICODE
                        );
                }
                ?>

                <tr>
                    <td>
                        <?= htmlspecialchars(
                            (string)$row['scope']
                        ) ?>
                    </td>

                    <td>
                        <?= htmlspecialchars(
                            (string)$row['name']
                        ) ?>
                    </td>

                    <td>
                        <?= htmlspecialchars(
                            (string)$displayValue
                        ) ?>
                    </td>

                    <td>
                        <?= htmlspecialchars(
                            (string)$row['type']
                        ) ?>
                    </td>
                </tr>

            <?php endforeach; ?>

            </tbody>
        </table>

    <?php else: ?>

        <p>
            No active Traits are currently applicable.
        </p>

    <?php endif; ?>

<?php endif; ?>



==============================================================================
FILE: play/includes/author-mode.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Role-Based Author Mode
 * WAYFARER_ROLE_BASED_AUTHOR_MODE_V37
 * --------------------------------------------------------------------------
 *
 * This file is included only when play/index.php has already verified that
 * the current wf_game_users.role is "author".
 */

$authorSetupChoices =
    isset($gameConfig['setup']['choices']) &&
    is_array($gameConfig['setup']['choices'])
        ? array_values(
            $gameConfig['setup']['choices']
        )
        : [];

?>
<h2>Author Mode</h2>

<p>
    <a
        href="../admin/builder.php?game=<?= (int)$gameId ?>"
        target="_blank"
    >
        Open Wayfarer Builder
    </a>
</p>


<?php if ($state === null): ?>

    <section
        id="wayfarer-author-state-panel"
        class="wayfarer-author-tab-panel"
        data-wayfarer-author-panel="state"
    >
        <h3>Runtime</h3>

        <p>
            Runtime state has not been initialized.
        </p>

        <h4>Game Setup</h4>

        <table>
            <tbody>
                <tr>
                    <th>Player Name Slots</th>
                    <td>
                        <?= (int)(
                            $gameUser['player_slots']
                            ?? 0
                        ) ?>
                    </td>
                </tr>

                <tr>
                    <th>Starting Choices</th>
                    <td>
                        <?= count(
                            $authorSetupChoices
                        ) ?>
                    </td>
                </tr>

                <tr>
                    <th>Starting Region ID</th>
                    <td>
                        <?php if (
                            !empty(
                                $gameConfig['starting_region_id']
                            )
                        ): ?>
                            <?= (int)$gameConfig['starting_region_id'] ?>
                        <?php else: ?>
                            <em>Not configured</em>
                        <?php endif; ?>
                    </td>
                </tr>
            </tbody>
        </table>
    </section>

    <section
        id="wayfarer-author-debug-panel"
        class="wayfarer-author-tab-panel"
        data-wayfarer-author-panel="debug"
    >
        <h3>Runtime Debug</h3>

        <pre id="wayfarer-runtime-debug">NULL</pre>
    </section>


<?php else: ?>

    <section
        id="wayfarer-author-state-panel"
        class="wayfarer-author-tab-panel"
        data-wayfarer-author-panel="state"
    >
        <h3>Game Traits</h3>

        <?php if (
            empty(
                $state['game']['traits']
            )
        ): ?>

            <p>
                No game traits are currently stored.
            </p>

        <?php else: ?>

            <table>
                <thead>
                    <tr>
                        <th>Trait</th>
                        <th>Current Value</th>
                        <th>Type</th>
                    </tr>
                </thead>

                <tbody>

                <?php foreach (
                    $state['game']['traits']
                    as $traitId => $value
                ): ?>

                    <?php
                    $definition =
                        $gameTraitDefinitions[$traitId]
                        ?? null;
                    ?>

                    <tr>
                        <td>
                            <?php if ($definition): ?>
                                <?= htmlspecialchars(
                                    (string)$definition['name']
                                ) ?>
                            <?php else: ?>
                                <em>Unknown Trait</em>
                                <small>
                                    <?= htmlspecialchars(
                                        (string)$traitId
                                    ) ?>
                                </small>
                            <?php endif; ?>
                        </td>

                        <td
                            data-wayfarer-game-trait-value="<?= htmlspecialchars(
                                (string)$traitId,
                                ENT_QUOTES,
                                'UTF-8'
                            ) ?>"
                        >
                            <?php
                            if (is_bool($value)) {
                                echo $value
                                    ? 'True'
                                    : 'False';
                            } else {
                                echo htmlspecialchars(
                                    (string)$value
                                );
                            }
                            ?>
                        </td>

                        <td>
                            <?= htmlspecialchars(
                                (string)(
                                    $definition['type']
                                    ?? 'unknown'
                                )
                            ) ?>
                        </td>
                    </tr>

                <?php endforeach; ?>

                </tbody>
            </table>

        <?php endif; ?>


        <!-- WAYFARER_COMBINED_AUTHOR_STATE_REGION_V41 -->
        <div class="wayfarer-author-state-region">
            <!-- WAYFARER_CURRENT_REGION_V16 -->
            <?php require __DIR__ . '/current-region.php'; ?>
        </div>
    </section>


    <section
        id="wayfarer-author-debug-panel"
        class="wayfarer-author-tab-panel"
        data-wayfarer-author-panel="debug"
    >
        <h3>Runtime Debug</h3>

        <pre
            id="wayfarer-runtime-debug"
        ><?= htmlspecialchars(
            $gameUser['state']
            ?? 'NULL'
        ) ?></pre>
    </section>


    <!-- WAYFARER_TICK_PANEL_V14 -->
    <?php require __DIR__ . '/tick-panel.php'; ?>

<?php endif; ?>


==============================================================================
FILE: play/includes/current-region.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Current Region - v16
|--------------------------------------------------------------------------
|
| Current gameplay context shown in Author Mode.
|
| This deliberately remains independent of the existing Game Traits table.
|
*/

require_once __DIR__ . '/runtime.php';

if (
    !isset($pdo) ||
    !($pdo instanceof PDO)
) {
    require_once __DIR__ . '/../../config/database.php';
}


function wayfarerV16DecodeConfig($raw): array
{
    if (is_array($raw)) {
        return $raw;
    }

    if ($raw === null || $raw === '') {
        return [];
    }

    $decoded =
        json_decode(
            (string)$raw,
            true
        );

    return is_array($decoded)
        ? $decoded
        : [];
}


function wayfarerV16ActiveTraits(array $config): array
{
    $traits =
        $config['traits']
        ?? [];

    if (!is_array($traits)) {
        return [];
    }

    $result = [];

    foreach ($traits as $trait) {

        if (!is_array($trait)) {
            continue;
        }

        if (
            array_key_exists(
                'active',
                $trait
            ) &&
            !$trait['active']
        ) {
            continue;
        }

        $traitId =
            trim(
                (string)(
                    $trait['id']
                    ?? ''
                )
            );

        if ($traitId === '') {

            $traitId =
                trim(
                    (string)(
                        $trait['system_key']
                        ?? ''
                    )
                );
        }

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

        $trait['_runtime_id'] =
            $traitId;

        $result[] =
            $trait;
    }

    return $result;
}


function wayfarerV16InitialTraitValue(array $trait)
{
    if (
        array_key_exists(
            'initial',
            $trait
        )
    ) {
        return $trait['initial'];
    }

    $type =
        (string)(
            $trait['type']
            ?? ''
        );

    if (
        $type === 'number' ||
        $type === 'binary' ||
        $type === 'boolean'
    ) {
        return 0;
    }

    return null;
}


function wayfarerV16LoadRegion(
    PDO $pdo,
    int $gameId,
    int $regionId
): ?array {

    if ($regionId <= 0) {
        return null;
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT *
            FROM wf_regions
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

    $stmt->execute([
        $regionId,
        $gameId,
    ]);

    $row =
        $stmt->fetch(
            PDO::FETCH_ASSOC
        );

    return $row ?: null;
}



function wayfarerV16EnsureCurrentRegion(
    PDO $pdo,
    int $gameUserId
): array {

    try {

        $pdo->beginTransaction();

        $stmt =
            $pdo->prepare(
                "
                SELECT
                    id,
                    game_id,
                    state
                FROM wf_game_users
                WHERE id = ?
                LIMIT 1
                FOR UPDATE
                "
            );

        $stmt->execute([
            $gameUserId
        ]);

        $gameUser =
            $stmt->fetch(
                PDO::FETCH_ASSOC
            );

        if (!$gameUser) {
            throw new RuntimeException(
                'Game-user runtime record not found.'
            );
        }

        $gameId =
            (int)$gameUser['game_id'];

        $state =
            wayfarerRuntimeDecodeState(
                $gameUser['state']
            );

        if (
            !isset($state['navigation']) ||
            !is_array($state['navigation'])
        ) {
            $state['navigation'] = [];
        }

        $regionId =
            (int)(
                $state['navigation']['region_id']
                ?? 0
            );

        $region =
            wayfarerV16LoadRegion(
                $pdo,
                $gameId,
                $regionId
            );

        $changed = false;

        /*
         * WAYFARER_RUNTIME_INITIALIZATION_V31
         *
         * Recovery only: properly initialized v31 state already contains its
         * Region. If older/incomplete state lacks a valid Region, recover to
         * the Game's authored Starting Region — never an arbitrary first row.
         */
        if (!$region) {

            $region =
                wayfarerRuntimeLoadStartingRegion(
                    $pdo,
                    $gameId
                );

            if ($region) {

                $regionId =
                    (int)$region['id'];

                $state['navigation']['region_id'] =
                    $regionId;

                if (
                    strtolower(
                        trim(
                            (string)(
                                $region['navigation_type']
                                ?? ''
                            )
                        )
                    ) === 'linear' &&
                    !array_key_exists(
                        'position',
                        $state['navigation']
                    )
                ) {
                    $state['navigation']['position'] =
                        0;
                }

                $changed = true;
            }
        }

        $traits = [];

        if ($region) {

            $regionConfig =
                wayfarerV16DecodeConfig(
                    $region['config']
                    ?? null
                );

            $traits =
                wayfarerV16ActiveTraits(
                    $regionConfig
                );

            if (
                !isset($state['regions']) ||
                !is_array($state['regions'])
            ) {
                $state['regions'] = [];
                $changed = true;
            }

            $regionKey =
                (string)$regionId;

            if (
                !isset($state['regions'][$regionKey]) ||
                !is_array(
                    $state['regions'][$regionKey]
                )
            ) {
                $state['regions'][$regionKey] = [];
                $changed = true;
            }

            if (
                !isset(
                    $state['regions'][$regionKey]['traits']
                ) ||
                !is_array(
                    $state['regions'][$regionKey]['traits']
                )
            ) {
                $state['regions'][$regionKey]['traits'] =
                    [];

                $changed = true;
            }

            foreach ($traits as $trait) {

                $traitId =
                    (string)$trait['_runtime_id'];

                if (
                    array_key_exists(
                        $traitId,
                        $state['regions'][$regionKey]['traits']
                    )
                ) {
                    continue;
                }

                $state['regions'][$regionKey]['traits'][$traitId] =
                    wayfarerV16InitialTraitValue(
                        $trait
                    );

                $changed = true;
            }
        }

        if ($changed) {

            $update =
                $pdo->prepare(
                    "
                    UPDATE wf_game_users
                    SET state = ?
                    WHERE id = ?
                    "
                );

            $update->execute([
                wayfarerRuntimeEncodeState(
                    $state
                ),
                $gameUserId,
            ]);
        }

        $pdo->commit();

        return [
            'region' =>
                $region,

            'traits' =>
                $traits,

            'state' =>
                $state,

            'region_id' =>
                $regionId,
        ];

    } catch (Throwable $exception) {

        if ($pdo->inTransaction()) {
            $pdo->rollBack();
        }

        throw $exception;
    }
}


$currentRegionError =
    '';

$currentRegionContext =
    null;

try {

    $requestedGameUserId =
        isset($_GET['game_user_id'])
            ? (int)$_GET['game_user_id']
            : null;

    $currentRegionGameUserId =
        wayfarerRuntimeResolveGameUserId(
            $pdo,
            $requestedGameUserId
        );

    $currentRegionContext =
        wayfarerV16EnsureCurrentRegion(
            $pdo,
            $currentRegionGameUserId
        );

} catch (Throwable $exception) {

    $currentRegionError =
        $exception->getMessage();
}

?>

<h3>Current Region</h3>

<?php if ($currentRegionError !== ''): ?>

    <p style="color:red;">
        <?= htmlspecialchars(
            $currentRegionError
        ) ?>
    </p>

<?php elseif (
    empty(
        $currentRegionContext['region']
    )
): ?>

    <p>
        No active Region is available for this game.
    </p>

<?php else: ?>

    <?php
    $region =
        $currentRegionContext['region'];

    $regionId =
        (int)$currentRegionContext['region_id'];

    $state =
        $currentRegionContext['state'];

    $position =
        $state['navigation']['position']
        ?? 0;
    ?>

    <p>
        <strong>
            <?= htmlspecialchars(
                (string)$region['name']
            ) ?>
        </strong>

        <?php if (!empty($region['navigation_type'])): ?>
            —
            <?= htmlspecialchars(
                (string)$region['navigation_type']
            ) ?>
        <?php endif; ?>
    </p>

    <p>
        Region ID:
        <?= $regionId ?>
        &nbsp; | &nbsp;
        Position:
        <strong id="wayfarer-author-position">
            <?= htmlspecialchars(
                (string)$position
            ) ?>
        </strong>
    </p>


    <h4>Region Traits</h4>

    <?php if (
        empty(
            $currentRegionContext['traits']
        )
    ): ?>

        <p>
            This Region has no active Traits.
        </p>

    <?php else: ?>

        <table
            border="1"
            cellpadding="6"
            cellspacing="0"
        >
            <thead>
                <tr>
                    <th>Trait</th>
                    <th>Current Value</th>
                    <th>Type</th>
                </tr>
            </thead>

            <tbody>

            <?php foreach (
                $currentRegionContext['traits']
                as $trait
            ): ?>

                <?php
                $traitId =
                    (string)$trait['_runtime_id'];

                $value =
                    $state['regions'][(string)$regionId]['traits'][$traitId]
                    ?? null;

                if (is_bool($value)) {

                    $displayValue =
                        $value
                            ? 'true'
                            : 'false';

                } elseif ($value === null) {

                    $displayValue =
                        'null';

                } else {

                    $displayValue =
                        (string)$value;
                }

                $traitName =
                    (string)(
                        $trait['name']
                        ?? $trait['label']
                        ?? $traitId
                    );
                ?>

                <tr>
                    <td>
                        <?= htmlspecialchars(
                            $traitName
                        ) ?>
                    </td>

                    <td
                        data-wayfarer-region-trait-value="<?= htmlspecialchars(
                            (string)$traitId,
                            ENT_QUOTES,
                            'UTF-8'
                        ) ?>"
                        data-wayfarer-region-id="<?= (int)$regionId ?>"
                    >
                        <?= htmlspecialchars(
                            $displayValue
                        ) ?>
                    </td>

                    <td>
                        <?= htmlspecialchars(
                            (string)(
                                $trait['type']
                                ?? ''
                            )
                        ) ?>
                    </td>
                </tr>

            <?php endforeach; ?>

            </tbody>
        </table>

    <?php endif; ?>

<?php endif; ?>



==============================================================================
FILE: play/includes/effects.php
==============================================================================

<?php

/* WAYFARER_TICK_EFFECT_RUNTIME_BRANCHES_V29 */
/* WAYFARER_RUNTIME_TRAIT_BOUNDS_V30 */
require_once __DIR__ . '/../../includes/gameplay/conditions.php';

/*
|--------------------------------------------------------------------------
| Wayfarer Runtime Effects
|--------------------------------------------------------------------------
|
| Executes authored runtime state effects.
|
*/


function wayfarerNormalizeRuntimeNumber(float $value)
{
    if (floor($value) === $value) {
        return (int)$value;
    }

    return $value;
}


function wayfarerApplyRuntimeOperation(
    $currentValue,
    string $operation,
    $effectValue
): array {

    $operation =
        strtolower(
            trim(
                $operation
            )
        );

    if ($operation === 'set') {

        if (is_numeric($effectValue)) {
            return [
                'applied' => true,
                'value'   =>
                    wayfarerNormalizeRuntimeNumber(
                        (float)$effectValue
                    ),
                'error'   => '',
            ];
        }

        return [
            'applied' => true,
            'value'   => $effectValue,
            'error'   => '',
        ];
    }

    if (
        $operation !== 'add' &&
        $operation !== 'subtract'
    ) {
        return [
            'applied' => false,
            'value'   => $currentValue,
            'error'   =>
                'Unsupported operation: ' .
                $operation,
        ];
    }

    if (
        !is_numeric($currentValue) ||
        !is_numeric($effectValue)
    ) {
        return [
            'applied' => false,
            'value'   => $currentValue,
            'error'   =>
                'Add/subtract requires numeric values.',
        ];
    }

    $current =
        (float)$currentValue;

    $amount =
        (float)$effectValue;

    $result =
        $operation === 'add'
            ? $current + $amount
            : $current - $amount;

    return [
        'applied' => true,
        'value'   =>
            wayfarerNormalizeRuntimeNumber(
                $result
            ),
        'error'   => '',
    ];
}



/*
|--------------------------------------------------------------------------
| Tick Effect branch runtime
|--------------------------------------------------------------------------
|
| A Tick Effect owns one target and an ordered list of result branches.
| Conditions are evaluated against the CURRENT runtime state. Because Tick
| Effects execute sequentially, a later Tick Effect can see state changes made
| by an earlier Tick Effect during the same tick.
|
*/


function wayfarerRuntimeResolveConditionTarget(
    array $runtimeState,
    int $currentRegionId,
    string $scope,
    string $targetType,
    string $targetId
): array {

    $scope =
        strtolower(
            trim(
                $scope
            )
        );

    $targetType =
        strtolower(
            trim(
                $targetType
            )
        );

    $targetId =
        trim(
            $targetId
        );


    // ------------------------------------------------------------
    // PARTY-MEMBER STATUS
    // WAYFARER_STATUS_CONDITION_RUNTIME_V87
    // ------------------------------------------------------------
    if (
        $targetType === 'status' &&
        preg_match('/^[1-9][0-9]*$/', $targetId) === 1 &&
        preg_match(
            '/^(?:player:[0-9]+|entity:[1-9][0-9]*)$/',
            $scope
        ) === 1
    ) {
        $statusState =
            wayfarerRuntimeStatusState(
                $runtimeState,
                $scope,
                (int)$targetId
            );

        if (empty($statusState['found_owner'])) {
            return [
                'found' => false,
                'value' => null,
            ];
        }

        return [
            'found' => true,
            'value' => !empty($statusState['active']) ? 1 : 0,
        ];
    }


    // ------------------------------------------------------------
    // GAME TRAIT
    // ------------------------------------------------------------

    if (
        $scope === 'game' &&
        $targetType === 'trait' &&
        $targetId !== ''
    ) {

        $traits =
            $runtimeState['game']['traits']
            ?? null;

        if (
            is_array($traits) &&
            array_key_exists(
                $targetId,
                $traits
            )
        ) {
            return [
                'found' => true,
                'value' =>
                    $traits[$targetId],
            ];
        }

        return [
            'found' => false,
            'value' => null,
        ];
    }


    // ------------------------------------------------------------
    // SPECIFIC REGION TRAIT
    // WAYFARER_SPECIFIC_REGION_CONDITION_SCOPE_V46
    // ------------------------------------------------------------
    //
    // Game-level condition editors store a Region-owned Trait as
    // "region:<id>". This lets a global rule inspect that Region whether
    // or not the player is currently there.
    //
    if (
        $targetType === 'trait' &&
        $targetId !== '' &&
        preg_match(
            '/^region:([1-9][0-9]*)$/',
            $scope,
            $regionScopeMatch
        ) === 1
    ) {

        $regionKey =
            (string)(
                (int)$regionScopeMatch[1]
            );

        $traits =
            $runtimeState['regions'][$regionKey]['traits']
            ?? null;

        if (
            is_array($traits) &&
            array_key_exists(
                $targetId,
                $traits
            )
        ) {
            return [
                'found' => true,
                'value' =>
                    $traits[$targetId],
            ];
        }

        return [
            'found' => false,
            'value' => null,
        ];
    }


    // ------------------------------------------------------------
    // CURRENT REGION TRAIT
    // ------------------------------------------------------------

    if (
        $scope === 'region' &&
        $targetType === 'trait' &&
        $targetId !== '' &&
        $currentRegionId > 0
    ) {

        $regionKey =
            (string)$currentRegionId;

        $traits =
            $runtimeState['regions'][$regionKey]['traits']
            ?? null;

        if (
            is_array($traits) &&
            array_key_exists(
                $targetId,
                $traits
            )
        ) {
            return [
                'found' => true,
                'value' =>
                    $traits[$targetId],
            ];
        }

        return [
            'found' => false,
            'value' => null,
        ];
    }


    // ------------------------------------------------------------
    // PLAYER / LOCATION / ENTITY TRAITS
    // WAYFARER_RUNTIME_UNIVERSAL_TARGET_RESOLVER_V56
    // ------------------------------------------------------------

    if (
        $targetType === 'trait' &&
        $targetId !== '' &&
        preg_match(
            '/^player:([0-9]+)$/',
            $scope,
            $playerScopeMatch
        ) === 1
    ) {
        $playerKey =
            (string)((int)$playerScopeMatch[1]);

        $traits =
            $runtimeState['players'][$playerKey]['traits']
            ?? null;

        if (
            is_array($traits) &&
            array_key_exists($targetId, $traits)
        ) {
            return [
                'found' => true,
                'value' => $traits[$targetId],
            ];
        }

        return [
            'found' => false,
            'value' => null,
        ];
    }


    if (
        $targetType === 'trait' &&
        $targetId !== '' &&
        preg_match(
            '/^location:([1-9][0-9]*)$/',
            $scope,
            $locationScopeMatch
        ) === 1
    ) {
        $locationKey =
            (string)((int)$locationScopeMatch[1]);

        $traits =
            $runtimeState['locations'][$locationKey]['traits']
            ?? null;

        if (
            is_array($traits) &&
            array_key_exists($targetId, $traits)
        ) {
            return [
                'found' => true,
                'value' => $traits[$targetId],
            ];
        }

        return [
            'found' => false,
            'value' => null,
        ];
    }


    if (
        $targetType === 'trait' &&
        $targetId !== '' &&
        preg_match(
            '/^entity:([1-9][0-9]*)$/',
            $scope,
            $entityScopeMatch
        ) === 1
    ) {
        $entityKey =
            (string)((int)$entityScopeMatch[1]);

        $traits =
            $runtimeState['entities'][$entityKey]['traits']
            ?? null;

        if (
            is_array($traits) &&
            array_key_exists($targetId, $traits)
        ) {
            return [
                'found' => true,
                'value' => $traits[$targetId],
            ];
        }

        return [
            'found' => false,
            'value' => null,
        ];
    }


    // ------------------------------------------------------------
    // GAME TIME
    // WAYFARER_HIERARCHICAL_TARGETS_V80
    // ------------------------------------------------------------

    if (
        $scope === 'time' &&
        $targetType === 'clock'
    ) {
        $clock =
            $runtimeState['runtime']['clock']
            ?? null;

        if (!is_array($clock)) {
            return [
                'found' => false,
                'value' => null,
            ];
        }

        if (
            $targetId === 'day' &&
            array_key_exists(
                'day',
                $clock
            )
        ) {
            return [
                'found' => true,
                'value' => (int)$clock['day'],
            ];
        }

        if (
            $targetId === 'hour' &&
            array_key_exists(
                'hour',
                $clock
            )
        ) {
            return [
                'found' => true,
                'value' => (int)$clock['hour'],
            ];
        }

        return [
            'found' => false,
            'value' => null,
        ];
    }
    // ------------------------------------------------------------
    // REGION-QUALIFIED NAVIGATION POSITION
    // WAYFARER_LOCATION_CONDITION_TARGETS_V75
    // ------------------------------------------------------------

    if (
        $targetType === 'position' &&
        $targetId === 'position' &&
        preg_match(
            '/^navigation:([1-9][0-9]*)$/',
            $scope,
            $navigationRegionMatch
        ) === 1
    ) {
        $requiredRegionId =
            (int)$navigationRegionMatch[1];

        if (
            $requiredRegionId !==
            $currentRegionId
        ) {
            return [
                'found' => false,
                'value' => null,
            ];
        }

        if (
            isset(
                $runtimeState['navigation']
            ) &&
            is_array(
                $runtimeState['navigation']
            ) &&
            array_key_exists(
                'position',
                $runtimeState['navigation']
            )
        ) {
            return [
                'found' => true,
                'value' =>
                    $runtimeState['navigation']['position'],
            ];
        }

        return [
            'found' => false,
            'value' => null,
        ];
    }


    // ------------------------------------------------------------
    // LIVE LOCATION ANCHOR
    // WAYFARER_LIVE_LOCATION_ANCHORS_V76
    // ------------------------------------------------------------

    if (
        $scope === 'navigation' &&
        $targetType === 'location' &&
        preg_match(
            '/^[1-9][0-9]*$/',
            $targetId
        ) === 1
    ) {
        $locationKey =
            (string)((int)$targetId);

        $anchor =
            $runtimeState['locations'][$locationKey]
            ?? null;

        if (!is_array($anchor)) {
            return [
                'found' => false,
                'value' => null,
            ];
        }

        $anchorRegionId =
            (int)(
                $anchor['region_id']
                ?? 0
            );

        $anchorPosition =
            $anchor['position']
            ?? null;

        if (
            $anchorRegionId <= 0 ||
            !is_numeric($anchorPosition)
        ) {
            return [
                'found' => false,
                'value' => null,
            ];
        }

        /*
         * Before/After has no meaning across Regions. "Not at" is handled by
         * the Condition engine via comparison_scope_match=false.
         */
        if ($anchorRegionId !== $currentRegionId) {
            return [
                'found' => true,
                'value' => null,
                'comparison_scope_match' => false,
            ];
        }

        $currentPosition =
            $runtimeState['navigation']['position']
            ?? null;

        if (!is_numeric($currentPosition)) {
            return [
                'found' => false,
                'value' => null,
            ];
        }

        return [
            'found' => true,
            'value' =>
                wayfarerNormalizeRuntimeNumber(
                    (float)$currentPosition -
                    (float)$anchorPosition
                ),
            'comparison_scope_match' => true,
        ];
    }

    // ------------------------------------------------------------
    // NAMED LOCATION = CURRENT REGION + CURRENT NUMERIC POSITION
    // WAYFARER_LOCATION_CONDITION_TARGETS_V75
    // ------------------------------------------------------------

    if (
        $scope === 'navigation' &&
        $targetType === 'location' &&
        $targetId === 'location'
    ) {
        if (
            $currentRegionId <= 0 ||
            !isset(
                $runtimeState['navigation']
            ) ||
            !is_array(
                $runtimeState['navigation']
            ) ||
            !array_key_exists(
                'position',
                $runtimeState['navigation']
            ) ||
            !is_numeric(
                $runtimeState['navigation']['position']
            )
        ) {
            return [
                'found' => false,
                'value' => null,
            ];
        }

        $position =
            wayfarerNormalizeRuntimeNumber(
                (float)$runtimeState[
                    'navigation'
                ]['position']
            );

        return [
            'found' => true,
            'value' =>
                $currentRegionId .
                ':' .
                (string)$position,
        ];
    }

    // ------------------------------------------------------------
    // NAVIGATION POSITION
    // ------------------------------------------------------------

    if (
        $scope === 'navigation' &&
        $targetType === 'position' &&
        $targetId === 'position'
    ) {

        if (
            isset(
                $runtimeState['navigation']
            ) &&
            is_array(
                $runtimeState['navigation']
            ) &&
            array_key_exists(
                'position',
                $runtimeState['navigation']
            )
        ) {
            return [
                'found' => true,
                'value' =>
                    $runtimeState['navigation']['position'],
            ];
        }

        return [
            'found' => false,
            'value' => null,
        ];
    }


    return [
        'found' => false,
        'value' => null,
    ];
}


function wayfarerRuntimeTickEffectBranches(
    array $effect
): array {

    /*
     * v28+ canonical structure.
     *
     * If the branches key exists, it is authoritative. An empty branches
     * array therefore means "this effect has no executable results" rather
     * than silently falling back to legacy compatibility fields.
     */
    if (
        array_key_exists(
            'branches',
            $effect
        )
    ) {

        if (
            !is_array(
                $effect['branches']
            )
        ) {
            return [];
        }

        $branches = [];

        foreach (
            $effect['branches']
            as $branch
        ) {

            if (is_array($branch)) {
                $branches[] =
                    $branch;
            }
        }

        return $branches;
    }


    /*
     * Legacy pre-v28 structure.
     */
    if (
        array_key_exists(
            'operation',
            $effect
        ) ||
        array_key_exists(
            'value',
            $effect
        ) ||
        array_key_exists(
            'conditions',
            $effect
        )
    ) {

        $branch = [
            'conditions' =>
                $effect['conditions']
                ?? null,

            'operation' =>
                $effect['operation']
                ?? '',

            'value_mode' =>
                $effect['value_mode']
                ?? 'fixed',
        ];

        if (
            strtolower(
                trim(
                    (string)$branch['value_mode']
                )
            ) === 'random'
        ) {
            $branch['value_min'] =
                $effect['value_min']
                ?? 0;

            $branch['value_max'] =
                $effect['value_max']
                ?? 0;
        } else {
            $branch['value'] =
                $effect['value']
                ?? 0;
        }

        return [
            $branch
        ];
    }


    return [];
}


function wayfarerRuntimeSelectTickEffectBranch(
    array &$runtimeState,
    array $effect,
    int $currentRegionId
): array {

    $branches =
        wayfarerRuntimeTickEffectBranches(
            $effect
        );


    if ($branches === []) {
        return [
            'matched' => false,
            'branch' => null,
            'branch_index' => null,
            'error' =>
                'Tick Effect has no result branches.',
        ];
    }


    $resolver =
        function (
            string $scope,
            string $targetType,
            string $targetId
        ) use (
            &$runtimeState,
            $currentRegionId
        ): array {

            return
                wayfarerRuntimeResolveConditionTarget(
                    $runtimeState,
                    $currentRegionId,
                    $scope,
                    $targetType,
                    $targetId
                );
        };


    foreach (
        $branches
        as $branchIndex => $branch
    ) {

        $conditions =
            $branch['conditions']
            ?? null;


        /*
         * Validate before evaluating. Invalid authored data fails closed and
         * does NOT fall through to OTHERWISE, because doing so could silently
         * produce the wrong gameplay result.
         */
        $validation =
            wayfarerConditionValidateNode(
                $conditions
            );

        if (!$validation['valid']) {
            return [
                'matched' => false,
                'branch' => null,
                'branch_index' =>
                    (int)$branchIndex,
                'error' =>
                    'Invalid Tick Effect condition: ' .
                    (
                        $validation['error']
                        ?? 'unknown condition error'
                    ),
            ];
        }


        $passes =
            wayfarerConditionEvaluate(
                $validation['node'],
                $resolver
            );


        if (!$passes) {
            continue;
        }


        return [
            'matched' => true,
            'branch' => $branch,
            'branch_index' =>
                (int)$branchIndex,
            'error' => '',
        ];
    }


    return [
        'matched' => false,
        'branch' => null,
        'branch_index' => null,
        'error' => '',
    ];
}



/*
|--------------------------------------------------------------------------
| Runtime Trait bounds
|--------------------------------------------------------------------------
|
| WAYFARER_RUNTIME_TRAIT_BOUNDS_V30
|
| Authored numeric Trait min/max values are runtime invariants.
| State is normalized before condition evaluation and every subsequent
| mutation is clamped again before it is written.
|
*/


function wayfarerRuntimeDecodeTraitConfig(
    $rawConfig
): array {

    if (is_array($rawConfig)) {
        return $rawConfig;
    }

    if (
        $rawConfig === null ||
        $rawConfig === ''
    ) {
        return [];
    }

    $decoded =
        json_decode(
            (string)$rawConfig,
            true
        );

    return is_array($decoded)
        ? $decoded
        : [];
}


function wayfarerRuntimeIndexTraitDefinitions(
    array $traits
): array {

    $definitions = [];

    foreach ($traits as $trait) {

        if (!is_array($trait)) {
            continue;
        }

        $traitId =
            trim(
                (string)(
                    $trait['id']
                    ?? $trait['system_key']
                    ?? ''
                )
            );

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

        $definitions[$traitId] =
            $trait;
    }

    return $definitions;
}


function wayfarerRuntimeLoadTickTraitDefinitions(
    PDO $pdo,
    int $gameId,
    array $regionConfig
): array {

    $gameConfig = [];

    if ($gameId > 0) {

        $stmt =
            $pdo->prepare(
                "
                SELECT config
                FROM wf_games
                WHERE id = ?
                LIMIT 1
                "
            );

        $stmt->execute([
            $gameId
        ]);

        $rawGameConfig =
            $stmt->fetchColumn();

        if ($rawGameConfig !== false) {
            $gameConfig =
                wayfarerRuntimeDecodeTraitConfig(
                    $rawGameConfig
                );
        }
    }


    /* WAYFARER_RUNTIME_UNIVERSAL_DEFINITIONS_V56 */
    $definitions = [
        'game' =>
            wayfarerRuntimeIndexTraitDefinitions(
                is_array(
                    $gameConfig['traits']
                    ?? null
                )
                    ? $gameConfig['traits']
                    : []
            ),

        'player' =>
            wayfarerRuntimeIndexTraitDefinitions(
                is_array(
                    $gameConfig['player_traits']
                    ?? null
                )
                    ? $gameConfig['player_traits']
                    : []
            ),

        'region' =>
            wayfarerRuntimeIndexTraitDefinitions(
                is_array(
                    $regionConfig['traits']
                    ?? null
                )
                    ? $regionConfig['traits']
                    : []
            ),

        'regions' => [],
        'locations' => [],
        'entities' => [],
    ];


    if ($gameId > 0) {
        $stmt =
            $pdo->prepare(
                "
                SELECT id, config
                FROM wf_regions
                WHERE game_id = ?
                "
            );

        $stmt->execute([$gameId]);

        foreach (
            $stmt->fetchAll(PDO::FETCH_ASSOC)
            as $row
        ) {
            $id =
                (string)((int)($row['id'] ?? 0));

            if ($id === '0') {
                continue;
            }

            $config =
                wayfarerRuntimeDecodeTraitConfig(
                    $row['config']
                        ?? null
                );

            $definitions['regions'][$id] =
                wayfarerRuntimeIndexTraitDefinitions(
                    is_array($config['traits'] ?? null)
                        ? $config['traits']
                        : []
                );
        }


        $stmt =
            $pdo->prepare(
                "
                SELECT
                    l.id,
                    l.config
                FROM wf_locations l
                INNER JOIN wf_regions r
                    ON r.id = l.region_id
                WHERE r.game_id = ?
                "
            );

        $stmt->execute([$gameId]);

        foreach (
            $stmt->fetchAll(PDO::FETCH_ASSOC)
            as $row
        ) {
            $id =
                (string)((int)($row['id'] ?? 0));

            if ($id === '0') {
                continue;
            }

            $config =
                wayfarerRuntimeDecodeTraitConfig(
                    $row['config']
                        ?? null
                );

            $definitions['locations'][$id] =
                wayfarerRuntimeIndexTraitDefinitions(
                    is_array($config['traits'] ?? null)
                        ? $config['traits']
                        : []
                );
        }


        $stmt =
            $pdo->prepare(
                "
                SELECT
                    id,
                    entity_type,
                    config
                FROM wf_entities
                WHERE game_id = ?
                "
            );

        $stmt->execute([$gameId]);

        foreach (
            $stmt->fetchAll(PDO::FETCH_ASSOC)
            as $row
        ) {
            $id =
                (string)((int)($row['id'] ?? 0));

            if ($id === '0') {
                continue;
            }

            $config =
                wayfarerRuntimeDecodeTraitConfig(
                    $row['config']
                        ?? null
                );

            if (
                function_exists(
                    'wayfarerEntityActiveTraitDefinitions'
                )
            ) {
                $definitions['entities'][$id] =
                    wayfarerEntityActiveTraitDefinitions(
                        $config,
                        (string)(
                            $row['entity_type']
                            ?? ''
                        )
                    );
            } else {
                $definitions['entities'][$id] =
                    wayfarerRuntimeIndexTraitDefinitions(
                        is_array($config['traits'] ?? null)
                            ? $config['traits']
                            : []
                    );
            }
        }
    }


    return $definitions;
}


function wayfarerRuntimeClampValueToTraitDefinition(
    $value,
    ?array $definition
): array {

    $result = [
        'valid' => true,
        'value' => $value,
        'clamped' => false,
        'min' => null,
        'max' => null,
        'error' => '',
    ];


    /*
     * Bounds currently belong only to authored Number Traits.
     */
    if (
        !$definition ||
        strtolower(
            trim(
                (string)(
                    $definition['type']
                    ?? ''
                )
            )
        ) !== 'number'
    ) {
        return $result;
    }


    if (!is_numeric($value)) {

        $result['valid'] =
            false;

        $result['error'] =
            'Numeric Trait runtime state must be numeric.';

        return $result;
    }


    $min =
        isset($definition['min']) &&
        $definition['min'] !== '' &&
        is_numeric($definition['min'])
            ? (float)$definition['min']
            : null;

    $max =
        isset($definition['max']) &&
        $definition['max'] !== '' &&
        is_numeric($definition['max'])
            ? (float)$definition['max']
            : null;


    $numeric =
        (float)$value;

    $bounded =
        $numeric;


    if (
        $min !== null &&
        $bounded < $min
    ) {
        $bounded =
            $min;
    }


    if (
        $max !== null &&
        $bounded > $max
    ) {
        $bounded =
            $max;
    }


    $result['value'] =
        wayfarerNormalizeRuntimeNumber(
            $bounded
        );

    $result['clamped'] =
        $bounded !== $numeric;

    $result['min'] =
        $min === null
            ? null
            : wayfarerNormalizeRuntimeNumber(
                $min
            );

    $result['max'] =
        $max === null
            ? null
            : wayfarerNormalizeRuntimeNumber(
                $max
            );


    return $result;
}


function wayfarerRuntimeApplyBoundedTraitOperation(
    $storedBefore,
    string $operation,
    $effectValue,
    ?array $definition
): array {

    /*
     * Repair an already-illegal persisted value BEFORE applying the new
     * operation. Example: 120 with max 100 and subtract 10 becomes
     * 100 - 10 = 90, not 120 - 10 = 110 -> 100.
     */
    $beforeBound =
        wayfarerRuntimeClampValueToTraitDefinition(
            $storedBefore,
            $definition
        );


    if (!$beforeBound['valid']) {
        return [
            'applied' => false,
            'before' => $storedBefore,
            'normalized_before' =>
                $storedBefore,
            'requested_after' =>
                $storedBefore,
            'after' =>
                $storedBefore,
            'clamped' => false,
            'min' =>
                $beforeBound['min'],
            'max' =>
                $beforeBound['max'],
            'error' =>
                $beforeBound['error'],
        ];
    }


    $normalizedBefore =
        $beforeBound['value'];


    $operationResult =
        wayfarerApplyRuntimeOperation(
            $normalizedBefore,
            $operation,
            $effectValue
        );


    if (!$operationResult['applied']) {
        return [
            'applied' => false,
            'before' => $storedBefore,
            'normalized_before' =>
                $normalizedBefore,
            'requested_after' =>
                $normalizedBefore,
            'after' =>
                $normalizedBefore,
            'clamped' =>
                $beforeBound['clamped'],
            'min' =>
                $beforeBound['min'],
            'max' =>
                $beforeBound['max'],
            'error' =>
                $operationResult['error'],
        ];
    }


    $requestedAfter =
        $operationResult['value'];


    $afterBound =
        wayfarerRuntimeClampValueToTraitDefinition(
            $requestedAfter,
            $definition
        );


    if (!$afterBound['valid']) {
        return [
            'applied' => false,
            'before' => $storedBefore,
            'normalized_before' =>
                $normalizedBefore,
            'requested_after' =>
                $requestedAfter,
            'after' =>
                $normalizedBefore,
            'clamped' =>
                $beforeBound['clamped'],
            'min' =>
                $beforeBound['min'],
            'max' =>
                $beforeBound['max'],
            'error' =>
                $afterBound['error'],
        ];
    }


    return [
        'applied' => true,
        'before' => $storedBefore,
        'normalized_before' =>
            $normalizedBefore,
        'requested_after' =>
            $requestedAfter,
        'after' =>
            $afterBound['value'],
        'clamped' =>
            $beforeBound['clamped'] ||
            $afterBound['clamped'],
        'min' =>
            $afterBound['min'],
        'max' =>
            $afterBound['max'],
        'error' => '',
    ];
}


function wayfarerRuntimeClampApplicableTraitState(
    array &$runtimeState,
    array $traitDefinitions,
    int $currentRegionId
): array {

    $repairs = [];


    // ------------------------------------------------------------
    // GAME TRAITS
    // ------------------------------------------------------------

    $gameTraits =
        $runtimeState['game']['traits']
        ?? null;

    if (is_array($gameTraits)) {

        foreach (
            $traitDefinitions['game']
                ?? []
            as $traitId => $definition
        ) {

            if (
                !array_key_exists(
                    $traitId,
                    $gameTraits
                )
            ) {
                continue;
            }


            $before =
                $runtimeState['game']['traits'][$traitId];

            $bounded =
                wayfarerRuntimeClampValueToTraitDefinition(
                    $before,
                    is_array($definition)
                        ? $definition
                        : null
                );


            if (!$bounded['valid']) {

                $repairs[] = [
                    'scope' => 'game',
                    'target_id' => $traitId,
                    'before' => $before,
                    'after' => $before,
                    'clamped' => false,
                    'min' => $bounded['min'],
                    'max' => $bounded['max'],
                    'error' => $bounded['error'],
                ];

                continue;
            }


            if (!$bounded['clamped']) {
                continue;
            }


            $runtimeState['game']['traits'][$traitId] =
                $bounded['value'];

            $repairs[] = [
                'scope' => 'game',
                'target_id' => $traitId,
                'before' => $before,
                'after' => $bounded['value'],
                'clamped' => true,
                'min' => $bounded['min'],
                'max' => $bounded['max'],
                'error' => '',
            ];
        }
    }


    // ------------------------------------------------------------
    // CURRENT REGION TRAITS
    // ------------------------------------------------------------

    $regionKey =
        (string)$currentRegionId;

    $regionTraits =
        $runtimeState['regions'][$regionKey]['traits']
        ?? null;

    if (is_array($regionTraits)) {

        foreach (
            $traitDefinitions['region']
                ?? []
            as $traitId => $definition
        ) {

            if (
                !array_key_exists(
                    $traitId,
                    $regionTraits
                )
            ) {
                continue;
            }


            $before =
                $runtimeState['regions'][$regionKey]['traits'][$traitId];

            $bounded =
                wayfarerRuntimeClampValueToTraitDefinition(
                    $before,
                    is_array($definition)
                        ? $definition
                        : null
                );


            if (!$bounded['valid']) {

                $repairs[] = [
                    'scope' => 'region',
                    'target_id' => $traitId,
                    'before' => $before,
                    'after' => $before,
                    'clamped' => false,
                    'min' => $bounded['min'],
                    'max' => $bounded['max'],
                    'error' => $bounded['error'],
                ];

                continue;
            }


            if (!$bounded['clamped']) {
                continue;
            }


            $runtimeState['regions'][$regionKey]['traits'][$traitId] =
                $bounded['value'];

            $repairs[] = [
                'scope' => 'region',
                'target_id' => $traitId,
                'before' => $before,
                'after' => $bounded['value'],
                'clamped' => true,
                'min' => $bounded['min'],
                'max' => $bounded['max'],
                'error' => '',
            ];
        }
    }


    return $repairs;
}

function wayfarerApplyRuntimeTickEffect(
    array &$runtimeState,
    array $effect,
    int $currentRegionId,
    array $traitDefinitions = []
): array {

    $selection =
        wayfarerRuntimeSelectTickEffectBranch(
            $runtimeState,
            $effect,
            $currentRegionId
        );


    $scope =
        strtolower(
            trim(
                (string)(
                    $effect['target_scope']
                    ?? ''
                )
            )
        );

    $type =
        strtolower(
            trim(
                (string)(
                    $effect['target_type']
                    ?? ''
                )
            )
        );

    $targetId =
        trim(
            (string)(
                $effect['target_id']
                ?? ''
            )
        );


    if (
        $selection['error'] !== ''
    ) {
        return [
            'scope' => $scope,
            'type' => $type,
            'target_id' => $targetId,
            'matched' => false,
            'branch_index' =>
                $selection['branch_index'],
            'applied' => false,
            'error' =>
                $selection['error'],
        ];
    }


    /*
     * No conditional branch matched and there was no OTHERWISE.
     * This is a valid "do nothing this tick" result.
     */
    if (!$selection['matched']) {
        return [
            'scope' => $scope,
            'type' => $type,
            'target_id' => $targetId,
            'matched' => false,
            'branch_index' => null,
            'applied' => false,
            'error' => '',
        ];
    }


    $branch =
        $selection['branch'];

    $branchIndex =
        (int)$selection['branch_index'];

    $operation =
        strtolower(
            trim(
                (string)(
                    $branch['operation']
                    ?? ''
                )
            )
        );

    $isOtherwise =
        !array_key_exists(
            'conditions',
            $branch
        ) ||
        $branch['conditions'] === null ||
        $branch['conditions'] === [];


    /*
     * Explicit No Change:
     * the branch DID match, so this Tick Effect stops here, but state does
     * not mutate.
     */
    if ($operation === 'none') {

        $current =
            wayfarerRuntimeResolveConditionTarget(
                $runtimeState,
                $currentRegionId,
                $scope,
                $type,
                $targetId
            );

        return [
            'scope' => $scope,
            'type' => $type,
            'target_id' => $targetId,
            'operation' => 'none',
            'amount' => null,
            'before' =>
                $current['found']
                    ? $current['value']
                    : null,
            'after' =>
                $current['found']
                    ? $current['value']
                    : null,
            'matched' => true,
            'branch_index' => $branchIndex,
            'branch_kind' =>
                $isOtherwise
                    ? 'otherwise'
                    : 'conditional',
            'applied' => false,
            'no_change' => true,
            'error' => '',
        ];
    }


    /* WAYFARER_TICK_EFFECT_RANDOM_RUNTIME_V58 */
    $resolvedValue =
        wayfarerRuntimeRollEffectValue(
            $branch
        );

    if (!$resolvedValue['valid']) {
        return [
            'scope' => $scope,
            'type' => $type,
            'target_id' => $targetId,
            'operation' => $operation,
            'matched' => true,
            'branch_index' => $branchIndex,
            'branch_kind' =>
                $isOtherwise
                    ? 'otherwise'
                    : 'conditional',
            'applied' => false,
            'error' =>
                $resolvedValue['error'],
        ];
    }

    /*
     * WAYFARER_BIDIRECTIONAL_TRAVEL_TICK_EFFECT_V71
     *
     * Tick movement is relative to the player's current journey direction.
     * Only Tick Effects are reversed here. One-time narrative Effects remain
     * literal state changes, so an authored "Subtract 3 position" effect does
     * not unexpectedly change meaning because the player is traveling back.
     */
    if (
        $scope === 'navigation' &&
        $type === 'position' &&
        $targetId === 'position' &&
        wayfarerRuntimeNavigationDirection(
            $runtimeState
        ) < 0
    ) {
        if ($operation === 'add') {
            $operation = 'subtract';
        } elseif ($operation === 'subtract') {
            $operation = 'add';
        }
    }

    /*
     * Apply ONLY the selected result branch. The legacy effect-level
     * operation/value fields are deliberately ignored when branches exist.
     */
    $resolvedEffect =
        $effect;

    $resolvedEffect['operation'] =
        $operation;

    $resolvedEffect['value'] =
        $resolvedValue['value'];


    $report =
        wayfarerApplyRuntimeEffect(
            $runtimeState,
            $resolvedEffect,
            $currentRegionId,
            $traitDefinitions
        );


    $report['matched'] =
        true;

    $report['branch_index'] =
        $branchIndex;

    $report['branch_kind'] =
        $isOtherwise
            ? 'otherwise'
            : 'conditional';

    $report['value_mode'] =
        $resolvedValue['mode'];

    $report['rolled_value'] =
        $resolvedValue['value'];

    if ($resolvedValue['mode'] === 'random') {
        $report['random_min'] =
            $resolvedValue['min'];

        $report['random_max'] =
            $resolvedValue['max'];
    }


    return $report;
}


/*
|--------------------------------------------------------------------------
| Party aggregate Effect helpers
| WAYFARER_PARTY_TARGETS_RUNTIME_V85
|--------------------------------------------------------------------------
*/

function wayfarerRuntimePartyNormalizeTraitName(
    string $value
): string {
    $value =
        trim(
            preg_replace(
                '/\\s+/u',
                ' ',
                $value
            ) ?? $value
        );

    if (function_exists('mb_strtolower')) {
        return mb_strtolower(
            $value,
            'UTF-8'
        );
    }

    return strtolower($value);
}


function wayfarerRuntimePartyDecodeTraitTargetId(
    string $targetId
): ?string {
    $prefix =
        'party_name_';

    if (
        strpos(
            $targetId,
            $prefix
        ) !== 0
    ) {
        return null;
    }

    $hex =
        substr(
            $targetId,
            strlen($prefix)
        );

    if (
        $hex === '' ||
        strlen($hex) % 2 !== 0 ||
        preg_match(
            '/^[0-9a-f]+$/i',
            $hex
        ) !== 1
    ) {
        return null;
    }

    $decoded =
        hex2bin($hex);

    return $decoded === false
        ? null
        : wayfarerRuntimePartyNormalizeTraitName(
            $decoded
        );
}


function wayfarerRuntimePartyFindTraitDefinition(
    array $definitions,
    string $normalizedName
): ?array {
    $match = null;

    foreach (
        $definitions
        as $definitionKey => $definition
    ) {
        if (!is_array($definition)) {
            continue;
        }

        $name =
            wayfarerRuntimePartyNormalizeTraitName(
                (string)(
                    $definition['name']
                    ?? ''
                )
            );

        if ($name !== $normalizedName) {
            continue;
        }

        if ($match !== null) {
            return null;
        }

        $traitId =
            trim(
                (string)(
                    $definition['_runtime_id']
                    ?? $definition['id']
                    ?? $definitionKey
                )
            );

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

        $match = [
            'id' => $traitId,
            'definition' => $definition,
        ];
    }

    return $match;
}

function wayfarerApplyRuntimeEffect(
    array &$runtimeState,
    array $effect,
    int $currentRegionId,
    array $traitDefinitions = []
): array {

    $scope =
        strtolower(
            trim(
                (string)(
                    $effect['target_scope'] ??
                    ''
                )
            )
        );

    $type =
        strtolower(
            trim(
                (string)(
                    $effect['target_type'] ??
                    ''
                )
            )
        );

    $targetId =
        trim(
            (string)(
                $effect['target_id'] ??
                ''
            )
        );

    $operation =
        strtolower(
            trim(
                (string)(
                    $effect['operation'] ??
                    ''
                )
            )
        );

    $effectValue =
        $effect['value'] ??
        0;


    // ------------------------------------------------------------
    // PARTY-MEMBER STATUS
    // WAYFARER_STATUS_EFFECT_RUNTIME_V87
    // ------------------------------------------------------------
    if (
        $type === 'status' &&
        preg_match('/^[1-9][0-9]*$/', $targetId) === 1
    ) {
        if ($operation !== 'set') {
            return [
                'scope' => $scope,
                'type' => $type,
                'target_id' => $targetId,
                'operation' => $operation,
                'amount' => $effectValue,
                'before' => null,
                'after' => null,
                'applied' => false,
                'error' => 'Status Effects support Set only.',
            ];
        }

        $active =
            wayfarerRuntimeStatusNormalizeBoolean(
                $effectValue
            );

        if ($scope === 'party') {
            $results = [];
            $partyCount = 0;
            $firstError = '';

            $players =
                isset($runtimeState['players']) &&
                is_array($runtimeState['players'])
                    ? $runtimeState['players']
                    : [];

            foreach ($players as $playerKey => $playerState) {
                if (!is_array($playerState)) {
                    continue;
                }

                $name =
                    trim(
                        (string)(
                            $playerState['name']
                            ?? ''
                        )
                    );

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

                $partyCount++;
                $memberScope =
                    'player:' . (string)$playerKey;

                $child =
                    wayfarerApplyRuntimeEffect(
                        $runtimeState,
                        [
                            'target_scope' => $memberScope,
                            'target_type' => 'status',
                            'target_id' => $targetId,
                            'operation' => 'set',
                            'value' => $active ? 1 : 0,
                        ],
                        $currentRegionId,
                        $traitDefinitions
                    );

                $child['party_member_name'] = $name;
                $child['party_member_scope'] = $memberScope;
                $results[] = $child;

                if (!empty($child['error'])) {
                    $firstError = (string)$child['error'];
                    break;
                }
            }

            if ($firstError === '') {
                $entities =
                    isset($runtimeState['entities']) &&
                    is_array($runtimeState['entities'])
                        ? $runtimeState['entities']
                        : [];

                foreach ($entities as $entityKey => $entityState) {
                    if (!is_array($entityState)) {
                        continue;
                    }

                    $runtimeTraits =
                        isset($entityState['traits']) &&
                        is_array($entityState['traits'])
                            ? $entityState['traits']
                            : [];

                    if (empty($runtimeTraits['sys_character_party_member'])) {
                        continue;
                    }

                    $partyCount++;
                    $memberScope =
                        'entity:' . (string)$entityKey;

                    $child =
                        wayfarerApplyRuntimeEffect(
                            $runtimeState,
                            [
                                'target_scope' => $memberScope,
                                'target_type' => 'status',
                                'target_id' => $targetId,
                                'operation' => 'set',
                                'value' => $active ? 1 : 0,
                            ],
                            $currentRegionId,
                            $traitDefinitions
                        );

                    $child['party_member_scope'] = $memberScope;
                    $results[] = $child;

                    if (!empty($child['error'])) {
                        $firstError = (string)$child['error'];
                        break;
                    }
                }
            }

            if ($firstError === '' && $partyCount === 0) {
                $firstError = 'There are no current party members.';
            }

            return [
                'scope' => $scope,
                'type' => $type,
                'target_id' => $targetId,
                'operation' => $operation,
                'amount' => $active ? 1 : 0,
                'before' => null,
                'after' => null,
                'party_count' => $partyCount,
                'eligible_count' => $partyCount,
                'skipped_count' => 0,
                'results' => $results,
                'applied' =>
                    $firstError === '' &&
                    $partyCount > 0,
                'error' => $firstError,
            ];
        }

        if (
            preg_match(
                '/^(?:player:[0-9]+|entity:[1-9][0-9]*)$/',
                $scope
            ) === 1
        ) {
            $statusResult =
                wayfarerRuntimeSetStatus(
                    $runtimeState,
                    $scope,
                    (int)$targetId,
                    $active
                );

            return [
                'scope' => $scope,
                'type' => $type,
                'target_id' => $targetId,
                'operation' => $operation,
                'amount' => $active ? 1 : 0,
                'before' => $statusResult['before'],
                'after' => $statusResult['after'],
                'started_tick' => $statusResult['started_tick'],
                'applied' => $statusResult['applied'],
                'error' => $statusResult['error'],
            ];
        }

        return [
            'scope' => $scope,
            'type' => $type,
            'target_id' => $targetId,
            'operation' => $operation,
            'amount' => $effectValue,
            'before' => null,
            'after' => null,
            'applied' => false,
            'error' => 'Status Effect target scope is invalid.',
        ];
    }


    // ------------------------------------------------------------
    // NAVIGATION POSITION
    // ------------------------------------------------------------

    if (
        $scope === 'navigation' &&
        $type === 'position' &&
        $targetId === 'position'
    ) {

        if (
            !isset($runtimeState['navigation']) ||
            !is_array($runtimeState['navigation'])
        ) {
            $runtimeState['navigation'] = [];
        }

        $before =
            $runtimeState['navigation']['position'] ??
            0;

        $result =
            wayfarerApplyRuntimeOperation(
                $before,
                $operation,
                $effectValue
            );

        $after =
            $before;

        if (
            $result['applied'] &&
            !is_numeric($result['value'])
        ) {

            $result['applied'] =
                false;

            $result['error'] =
                'Navigation position must be numeric.';
        }

        if ($result['applied']) {

            /*
             * Global navigation rule:
             * position may never be less than zero.
             */
            $after =
                max(
                    0,
                    $result['value']
                );

            $runtimeState['navigation']['position'] =
                $after;
        }

        return [
            'scope'     => $scope,
            'type'      => $type,
            'target_id' => $targetId,
            'operation' => $operation,
            'amount'    => $effectValue,
            'before'    => $before,
            'after'     => $after,
            'applied'   => $result['applied'],
            'error'     => $result['error'],
        ];
    }


    // ------------------------------------------------------------
    // GAME TRAIT
    // ------------------------------------------------------------

    if (
        $scope === 'game' &&
        $type === 'trait' &&
        $targetId !== ''
    ) {

        if (
            !isset($runtimeState['game']) ||
            !is_array($runtimeState['game'])
        ) {
            $runtimeState['game'] = [];
        }

        if (
            !isset($runtimeState['game']['traits']) ||
            !is_array($runtimeState['game']['traits'])
        ) {
            $runtimeState['game']['traits'] = [];
        }

        $before =
            $runtimeState['game']['traits'][$targetId] ??
            0;

        $definition =
            isset(
                $traitDefinitions['game'][$targetId]
            ) &&
            is_array(
                $traitDefinitions['game'][$targetId]
            )
                ? $traitDefinitions['game'][$targetId]
                : null;

        $result =
            wayfarerRuntimeApplyBoundedTraitOperation(
                $before,
                $operation,
                $effectValue,
                $definition
            );

        /*
         * Persist the normalized value even when a malformed operation fails
         * after an existing illegal value was repaired.
         */
        if (
            $result['normalized_before'] !== $before
        ) {
            $runtimeState['game']['traits'][$targetId] =
                $result['normalized_before'];
        }

        if ($result['applied']) {
            $runtimeState['game']['traits'][$targetId] =
                $result['after'];
        }

        return [
            'scope'     => $scope,
            'type'      => $type,
            'target_id' => $targetId,
            'operation' => $operation,
            'amount'    => $effectValue,
            'before'    => $result['before'],
            'normalized_before' =>
                $result['normalized_before'],
            'requested_after' =>
                $result['requested_after'],
            'after'     => $result['after'],
            'clamped'   => $result['clamped'],
            'min'       => $result['min'],
            'max'       => $result['max'],
            'applied'   => $result['applied'],
            'error'     => $result['error'],
        ];
    }



    // ------------------------------------------------------------
    // ALL PARTY MEMBERS - LOGICAL TRAIT BY NAME
    // WAYFARER_PARTY_TARGETS_RUNTIME_V85
    // ------------------------------------------------------------

    if (
        $scope === 'party' &&
        $type === 'trait' &&
        $targetId !== ''
    ) {
        $normalizedName =
            wayfarerRuntimePartyDecodeTraitTargetId(
                $targetId
            );

        if ($normalizedName === null) {
            return [
                'scope' => $scope,
                'type' => $type,
                'target_id' => $targetId,
                'operation' => $operation,
                'amount' => $effectValue,
                'before' => null,
                'after' => null,
                'applied' => false,
                'error' =>
                    'Party Trait target is invalid.',
            ];
        }

        $results = [];
        $eligibleCount = 0;
        $partyCount = 0;
        $firstError = '';

        $players =
            isset($runtimeState['players']) &&
            is_array($runtimeState['players'])
                ? $runtimeState['players']
                : [];

        $playerDefinitions =
            isset($traitDefinitions['player']) &&
            is_array($traitDefinitions['player'])
                ? $traitDefinitions['player']
                : [];

        $playerTrait =
            wayfarerRuntimePartyFindTraitDefinition(
                $playerDefinitions,
                $normalizedName
            );

        foreach ($players as $playerKey => $playerState) {
            if (!is_array($playerState)) {
                continue;
            }

            $name =
                trim(
                    (string)(
                        $playerState['name']
                        ?? ''
                    )
                );

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

            $partyCount++;

            if (!is_array($playerTrait)) {
                continue;
            }

            $actualTargetId =
                (string)$playerTrait['id'];

            $runtimeTraits =
                isset($playerState['traits']) &&
                is_array($playerState['traits'])
                    ? $playerState['traits']
                    : [];

            if (
                !array_key_exists(
                    $actualTargetId,
                    $runtimeTraits
                )
            ) {
                continue;
            }

            $eligibleCount++;
            $memberScope =
                'player:' .
                (string)$playerKey;

            $childEffect = [
                'target_scope' => $memberScope,
                'target_type' => 'trait',
                'target_id' => $actualTargetId,
                'operation' => $operation,
                'value' => $effectValue,
            ];

            $child =
                wayfarerApplyRuntimeEffect(
                    $runtimeState,
                    $childEffect,
                    $currentRegionId,
                    $traitDefinitions
                );

            $child['party_member_name'] =
                $name;
            $child['party_member_scope'] =
                $memberScope;

            $results[] =
                $child;

            if (!empty($child['error'])) {
                $firstError =
                    (string)$child['error'];
                break;
            }
        }

        if ($firstError === '') {
            $entities =
                isset($runtimeState['entities']) &&
                is_array($runtimeState['entities'])
                    ? $runtimeState['entities']
                    : [];

            foreach ($entities as $entityKey => $entityState) {
                if (!is_array($entityState)) {
                    continue;
                }

                $runtimeTraits =
                    isset($entityState['traits']) &&
                    is_array($entityState['traits'])
                        ? $entityState['traits']
                        : [];

                if (
                    empty(
                        $runtimeTraits[
                            'sys_character_party_member'
                        ]
                    )
                ) {
                    continue;
                }

                $partyCount++;

                $definitions =
                    isset(
                        $traitDefinitions['entities'][
                            (string)$entityKey
                        ]
                    ) &&
                    is_array(
                        $traitDefinitions['entities'][
                            (string)$entityKey
                        ]
                    )
                        ? $traitDefinitions['entities'][
                            (string)$entityKey
                        ]
                        : [];

                $entityTrait =
                    wayfarerRuntimePartyFindTraitDefinition(
                        $definitions,
                        $normalizedName
                    );

                if (!is_array($entityTrait)) {
                    continue;
                }

                $actualTargetId =
                    (string)$entityTrait['id'];

                if (
                    !array_key_exists(
                        $actualTargetId,
                        $runtimeTraits
                    )
                ) {
                    continue;
                }

                $eligibleCount++;
                $memberScope =
                    'entity:' .
                    (string)$entityKey;

                $childEffect = [
                    'target_scope' => $memberScope,
                    'target_type' => 'trait',
                    'target_id' => $actualTargetId,
                    'operation' => $operation,
                    'value' => $effectValue,
                ];

                $child =
                    wayfarerApplyRuntimeEffect(
                        $runtimeState,
                        $childEffect,
                        $currentRegionId,
                        $traitDefinitions
                    );

                $child['party_member_scope'] =
                    $memberScope;

                $results[] =
                    $child;

                if (!empty($child['error'])) {
                    $firstError =
                        (string)$child['error'];
                    break;
                }
            }
        }

        if (
            $firstError === '' &&
            $eligibleCount === 0
        ) {
            $firstError =
                'No current party member exposes the selected Trait.';
        }

        return [
            'scope' => $scope,
            'type' => $type,
            'target_id' => $targetId,
            'operation' => $operation,
            'amount' => $effectValue,
            'before' => null,
            'after' => null,
            'party_count' => $partyCount,
            'eligible_count' => $eligibleCount,
            'skipped_count' =>
                max(
                    0,
                    $partyCount - $eligibleCount
                ),
            'results' => $results,
            'applied' =>
                $firstError === '' &&
                $eligibleCount > 0,
            'error' =>
                $firstError,
        ];
    }



    // ------------------------------------------------------------
    // ITEM ENTITY QUANTITY
    // WAYFARER_STARTING_CHOICE_ITEM_QUANTITY_V54
    // ------------------------------------------------------------

    if (
        $type === 'trait' &&
        $targetId !== '' &&
        preg_match(
            '/^entity:([1-9][0-9]*)$/',
            $scope,
            $entityScopeMatch
        ) === 1 &&
        (
            (string)(
                $effect['target_system_key']
                ?? ''
            ) === 'quantity' ||
            $targetId === 'sys_item_quantity'
        )
    ) {
        $entityKey =
            (string)(
                (int)$entityScopeMatch[1]
            );

        if (
            !isset(
                $runtimeState['entities'][$entityKey]
            ) ||
            !is_array(
                $runtimeState['entities'][$entityKey]
            ) ||
            !isset(
                $runtimeState['entities'][$entityKey]['traits']
            ) ||
            !is_array(
                $runtimeState['entities'][$entityKey]['traits']
            )
        ) {
            return [
                'scope' =>
                    $scope,
                'type' =>
                    $type,
                'target_id' =>
                    $targetId,
                'operation' =>
                    $operation,
                'amount' =>
                    $effectValue,
                'before' =>
                    null,
                'after' =>
                    null,
                'applied' =>
                    false,
                'error' =>
                    'Item Entity runtime state was not initialized.',
            ];
        }

        if (
            !array_key_exists(
                $targetId,
                $runtimeState['entities'][$entityKey]['traits']
            )
        ) {
            return [
                'scope' =>
                    $scope,
                'type' =>
                    $type,
                'target_id' =>
                    $targetId,
                'operation' =>
                    $operation,
                'amount' =>
                    $effectValue,
                'before' =>
                    null,
                'after' =>
                    null,
                'applied' =>
                    false,
                'error' =>
                    'Item Quantity runtime state was not found.',
            ];
        }

        $before =
            $runtimeState['entities'][$entityKey]['traits'][$targetId];

        $result =
            wayfarerApplyRuntimeOperation(
                $before,
                $operation,
                $effectValue
            );

        if (
            !$result['applied'] ||
            !is_numeric(
                $result['value']
                ?? null
            )
        ) {
            return [
                'scope' =>
                    $scope,
                'type' =>
                    $type,
                'target_id' =>
                    $targetId,
                'operation' =>
                    $operation,
                'amount' =>
                    $effectValue,
                'before' =>
                    $before,
                'after' =>
                    $before,
                'applied' =>
                    false,
                'error' =>
                    $result['error'] !== ''
                        ? $result['error']
                        : 'Item Quantity must remain numeric.',
            ];
        }

        $requestedAfter =
            wayfarerNormalizeRuntimeNumber(
                (float)$result['value']
            );

        /*
         * Quantity is globally non-negative.
         */
        $after =
            wayfarerNormalizeRuntimeNumber(
                max(
                    0.0,
                    (float)$requestedAfter
                )
            );

        $runtimeState['entities'][$entityKey]['traits'][$targetId] =
            $after;

        /*
         * Discovery is persistent. Receiving any positive starting quantity
         * discovers the Item; setting it back to zero never undiscoveres it.
         */
        if (
            (float)$after > 0
        ) {
            $runtimeState['entities'][$entityKey]['discovered'] =
                true;
        }

        return [
            'scope' =>
                $scope,
            'type' =>
                $type,
            'target_id' =>
                $targetId,
            'target_system_key' =>
                'quantity',
            'operation' =>
                $operation,
            'amount' =>
                $effectValue,
            'before' =>
                $before,
            'requested_after' =>
                $requestedAfter,
            'after' =>
                $after,
            'clamped' =>
                (float)$after !==
                (float)$requestedAfter,
            'min' =>
                0,
            'max' =>
                null,
            'applied' =>
                true,
            'error' =>
                '',
        ];
    }

    // ------------------------------------------------------------
    // SPECIFIC PLAYER / REGION / LOCATION / ENTITY TRAITS
    // WAYFARER_RUNTIME_UNIVERSAL_EFFECT_TARGETS_V56
    // ------------------------------------------------------------

    $stateBucket = null;
    $stateKey = null;
    $definition = null;

    if (
        $type === 'trait' &&
        $targetId !== '' &&
        preg_match(
            '/^player:([0-9]+)$/',
            $scope,
            $scopeMatch
        ) === 1
    ) {
        $stateBucket = 'players';
        $stateKey =
            (string)((int)$scopeMatch[1]);

        $definition =
            $traitDefinitions['player'][$targetId]
            ?? null;

    } elseif (
        $type === 'trait' &&
        $targetId !== '' &&
        preg_match(
            '/^region:([1-9][0-9]*)$/',
            $scope,
            $scopeMatch
        ) === 1
    ) {
        $stateBucket = 'regions';
        $stateKey =
            (string)((int)$scopeMatch[1]);

        $definition =
            $traitDefinitions['regions'][$stateKey][$targetId]
            ?? null;

    } elseif (
        $type === 'trait' &&
        $targetId !== '' &&
        preg_match(
            '/^location:([1-9][0-9]*)$/',
            $scope,
            $scopeMatch
        ) === 1
    ) {
        $stateBucket = 'locations';
        $stateKey =
            (string)((int)$scopeMatch[1]);

        $definition =
            $traitDefinitions['locations'][$stateKey][$targetId]
            ?? null;

    } elseif (
        $type === 'trait' &&
        $targetId !== '' &&
        preg_match(
            '/^entity:([1-9][0-9]*)$/',
            $scope,
            $scopeMatch
        ) === 1 &&
        $targetId !== 'sys_item_quantity'
    ) {
        $stateBucket = 'entities';
        $stateKey =
            (string)((int)$scopeMatch[1]);

        $definition =
            $traitDefinitions['entities'][$stateKey][$targetId]
            ?? null;
    }


    if (
        $stateBucket !== null &&
        $stateKey !== null
    ) {
        if (
            !isset($runtimeState[$stateBucket][$stateKey]) ||
            !is_array($runtimeState[$stateBucket][$stateKey]) ||
            !isset($runtimeState[$stateBucket][$stateKey]['traits']) ||
            !is_array($runtimeState[$stateBucket][$stateKey]['traits']) ||
            !array_key_exists(
                $targetId,
                $runtimeState[$stateBucket][$stateKey]['traits']
            )
        ) {
            return [
                'scope' => $scope,
                'type' => $type,
                'target_id' => $targetId,
                'operation' => $operation,
                'amount' => $effectValue,
                'before' => null,
                'after' => null,
                'applied' => false,
                'error' => 'Runtime Trait target was not found.',
            ];
        }

        $before =
            $runtimeState[$stateBucket][$stateKey]['traits'][$targetId];

        /*
         * Party Membership is mutable runtime state, but still a binary
         * Wayfarer system property. The 0/1 rule is enforced internally and is
         * never exposed as a separate Target/max metadata value.
         */
        if (
            $stateBucket === 'entities' &&
            $targetId === 'sys_character_party_member'
        ) {
            $operationResult =
                wayfarerApplyRuntimeOperation(
                    $before,
                    $operation,
                    $effectValue
                );

            if (
                !$operationResult['applied'] ||
                !is_numeric(
                    $operationResult['value']
                        ?? null
                )
            ) {
                return [
                    'scope' => $scope,
                    'type' => $type,
                    'target_id' => $targetId,
                    'operation' => $operation,
                    'amount' => $effectValue,
                    'before' => $before,
                    'after' => $before,
                    'applied' => false,
                    'error' =>
                        $operationResult['error'] !== ''
                            ? $operationResult['error']
                            : 'Party Membership requires a numeric 0/1 result.',
                ];
            }

            $after =
                (float)$operationResult['value'] > 0
                    ? 1
                    : 0;

            $runtimeState[$stateBucket][$stateKey]['traits'][$targetId] =
                $after;

            return [
                'scope' => $scope,
                'type' => $type,
                'target_id' => $targetId,
                'target_system_key' => 'party_member',
                'operation' => $operation,
                'amount' => $effectValue,
                'before' => $before,
                'after' => $after,
                'applied' => true,
                'error' => '',
            ];
        }

        $result =
            wayfarerRuntimeApplyBoundedTraitOperation(
                $before,
                $operation,
                $effectValue,
                is_array($definition)
                    ? $definition
                    : null
            );

        if ($result['applied']) {
            $runtimeState[$stateBucket][$stateKey]['traits'][$targetId] =
                $result['after'];
        }

        return [
            'scope' => $scope,
            'type' => $type,
            'target_id' => $targetId,
            'operation' => $operation,
            'amount' => $effectValue,
            'before' => $result['before'],
            'normalized_before' => $result['normalized_before'],
            'requested_after' => $result['requested_after'],
            'after' => $result['after'],
            'clamped' => $result['clamped'],
            'min' => $result['min'],
            'max' => $result['max'],
            'applied' => $result['applied'],
            'error' => $result['error'],
        ];
    }

    // ------------------------------------------------------------
    // PLAYER TRAIT
    // WAYFARER_STARTING_CHOICE_PLAYER_TARGETS_V53
    // ------------------------------------------------------------

    if (
        $scope === 'player' &&
        $type === 'trait' &&
        $targetId !== ''
    ) {
        if (
            !isset($runtimeState['players']) ||
            !is_array($runtimeState['players'])
        ) {
            $runtimeState['players'] = [];
        }

        $selector =
            strtolower(
                trim(
                    (string)(
                        $effect['target_selector']
                        ?? ''
                    )
                )
            );

        $targetKeys = [];

        if ($selector === 'all') {

            foreach (
                $runtimeState['players']
                as $playerKey => $playerState
            ) {
                if (is_array($playerState)) {
                    $targetKeys[] =
                        (string)$playerKey;
                }
            }

        } elseif (
            $selector === 'slot' &&
            array_key_exists(
                'target_slot',
                $effect
            )
        ) {
            $slot =
                max(
                    0,
                    (int)$effect['target_slot']
                );

            $targetKeys[] =
                (string)$slot;

        } else {
            return [
                'scope' =>
                    $scope,
                'type' =>
                    $type,
                'target_id' =>
                    $targetId,
                'operation' =>
                    $operation,
                'amount' =>
                    $effectValue,
                'before' =>
                    null,
                'after' =>
                    null,
                'applied' =>
                    false,
                'error' =>
                    'Player Trait effect requires an All Players or Player Slot target.',
            ];
        }

        if (empty($targetKeys)) {
            return [
                'scope' =>
                    $scope,
                'type' =>
                    $type,
                'target_id' =>
                    $targetId,
                'operation' =>
                    $operation,
                'amount' =>
                    $effectValue,
                'before' =>
                    null,
                'after' =>
                    null,
                'applied' =>
                    false,
                'error' =>
                    'Player Trait effect did not resolve any Player Characters.',
            ];
        }

        $definition =
            isset(
                $traitDefinitions['player'][$targetId]
            ) &&
            is_array(
                $traitDefinitions['player'][$targetId]
            )
                ? $traitDefinitions['player'][$targetId]
                : null;

        $results = [];
        $firstError = '';

        foreach ($targetKeys as $playerKey) {

            if (
                !isset(
                    $runtimeState['players'][$playerKey]
                ) ||
                !is_array(
                    $runtimeState['players'][$playerKey]
                )
            ) {
                $firstError =
                    'Player Character slot ' .
                    ((int)$playerKey + 1) .
                    ' does not exist in runtime state.';

                $results[$playerKey] = [
                    'applied' =>
                        false,
                    'error' =>
                        $firstError,
                ];

                break;
            }

            if (
                !isset(
                    $runtimeState['players'][$playerKey]['traits']
                ) ||
                !is_array(
                    $runtimeState['players'][$playerKey]['traits']
                )
            ) {
                $runtimeState['players'][$playerKey]['traits'] =
                    [];
            }

            $before =
                $runtimeState['players'][$playerKey]['traits'][$targetId]
                ?? 0;

            $result =
                wayfarerRuntimeApplyBoundedTraitOperation(
                    $before,
                    $operation,
                    $effectValue,
                    $definition
                );

            if (
                $result['normalized_before'] !==
                $before
            ) {
                $runtimeState['players'][$playerKey]['traits'][$targetId] =
                    $result['normalized_before'];
            }

            if ($result['applied']) {
                $runtimeState['players'][$playerKey]['traits'][$targetId] =
                    $result['after'];
            }

            $results[$playerKey] = [
                'slot' =>
                    (int)$playerKey,
                'name' =>
                    (string)(
                        $runtimeState['players'][$playerKey]['name']
                        ?? (
                            'Player ' .
                            ((int)$playerKey + 1)
                        )
                    ),
                'before' =>
                    $result['before'],
                'normalized_before' =>
                    $result['normalized_before'],
                'requested_after' =>
                    $result['requested_after'],
                'after' =>
                    $result['after'],
                'clamped' =>
                    $result['clamped'],
                'min' =>
                    $result['min'],
                'max' =>
                    $result['max'],
                'applied' =>
                    $result['applied'],
                'error' =>
                    $result['error'],
            ];

            if (
                !$result['applied'] ||
                $result['error'] !== ''
            ) {
                $firstError =
                    $result['error'] !== ''
                        ? $result['error']
                        : 'Player Trait effect could not be applied.';

                break;
            }
        }

        $allApplied =
            $firstError === '';

        return [
            'scope' =>
                $scope,
            'type' =>
                $type,
            'target_id' =>
                $targetId,
            'target_selector' =>
                $selector,
            'target_slot' =>
                $selector === 'slot'
                    ? (int)(
                        $effect['target_slot']
                        ?? 0
                    )
                    : null,
            'operation' =>
                $operation,
            'amount' =>
                $effectValue,
            'before' =>
                null,
            'after' =>
                null,
            'results' =>
                $results,
            'applied' =>
                $allApplied,
            'error' =>
                $firstError,
        ];
    }

    // ------------------------------------------------------------
    // CURRENT REGION TRAIT
    // ------------------------------------------------------------

    if (
        $scope === 'region' &&
        $type === 'trait' &&
        $targetId !== ''
    ) {

        $regionKey =
            (string)$currentRegionId;

        if (
            !isset($runtimeState['regions']) ||
            !is_array($runtimeState['regions'])
        ) {
            $runtimeState['regions'] = [];
        }

        if (
            !isset($runtimeState['regions'][$regionKey]) ||
            !is_array($runtimeState['regions'][$regionKey])
        ) {
            $runtimeState['regions'][$regionKey] = [];
        }

        if (
            !isset($runtimeState['regions'][$regionKey]['traits']) ||
            !is_array($runtimeState['regions'][$regionKey]['traits'])
        ) {
            $runtimeState['regions'][$regionKey]['traits'] = [];
        }

        $before =
            $runtimeState['regions'][$regionKey]['traits'][$targetId] ??
            0;

        $definition =
            isset(
                $traitDefinitions['region'][$targetId]
            ) &&
            is_array(
                $traitDefinitions['region'][$targetId]
            )
                ? $traitDefinitions['region'][$targetId]
                : null;

        $result =
            wayfarerRuntimeApplyBoundedTraitOperation(
                $before,
                $operation,
                $effectValue,
                $definition
            );

        if (
            $result['normalized_before'] !== $before
        ) {
            $runtimeState['regions'][$regionKey]['traits'][$targetId] =
                $result['normalized_before'];
        }

        if ($result['applied']) {
            $runtimeState['regions'][$regionKey]['traits'][$targetId] =
                $result['after'];
        }

        return [
            'scope'     => $scope,
            'type'      => $type,
            'target_id' => $targetId,
            'operation' => $operation,
            'amount'    => $effectValue,
            'before'    => $result['before'],
            'normalized_before' =>
                $result['normalized_before'],
            'requested_after' =>
                $result['requested_after'],
            'after'     => $result['after'],
            'clamped'   => $result['clamped'],
            'min'       => $result['min'],
            'max'       => $result['max'],
            'applied'   => $result['applied'],
            'error'     => $result['error'],
        ];
    }


    return [
        'scope'     => $scope,
        'type'      => $type,
        'target_id' => $targetId,
        'operation' => $operation,
        'amount'    => $effectValue,
        'before'    => null,
        'after'     => null,
        'applied'   => false,
        'error'     =>
            'Unsupported runtime target.',
    ];
}


/*
|--------------------------------------------------------------------------
| Game Tick Effects
|--------------------------------------------------------------------------
|
| WAYFARER_GAME_TICK_EFFECT_RUNTIME_V33
|
| Game Tick Effects execute once on every successful runtime tick before
| the active Region's Tick Effects. This creates a deterministic layering:
|
|     Game rules -> Region rules
|
*/
function wayfarerApplyGameTickEffects(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): array {

    if ($gameId <= 0) {

        $reports = [
            [
                'applied' => false,
                'error' =>
                    'No active game is available for Game Tick Effects.',
            ]
        ];

        if (
            !isset($runtimeState['runtime']) ||
            !is_array($runtimeState['runtime'])
        ) {
            $runtimeState['runtime'] = [];
        }

        $runtimeState['runtime']['last_game_tick_effects'] =
            $reports;

        return $reports;
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_games
            WHERE id = ?
            LIMIT 1
            "
        );

    $stmt->execute([
        $gameId
    ]);

    $rawConfig =
        $stmt->fetchColumn();

    if ($rawConfig === false) {

        $reports = [
            [
                'applied' => false,
                'error' =>
                    'Game ' .
                    $gameId .
                    ' was not found.',
            ]
        ];

        if (
            !isset($runtimeState['runtime']) ||
            !is_array($runtimeState['runtime'])
        ) {
            $runtimeState['runtime'] = [];
        }

        $runtimeState['runtime']['last_game_tick_effects'] =
            $reports;

        return $reports;
    }

    $gameConfig = [];

    if (
        $rawConfig !== null &&
        $rawConfig !== ''
    ) {

        $decoded =
            json_decode(
                (string)$rawConfig,
                true
            );

        if (is_array($decoded)) {
            $gameConfig =
                $decoded;
        }
    }

    $currentRegionId =
        (int)(
            $runtimeState['navigation']['region_id']
            ?? 0
        );

    $traitDefinitions =
        wayfarerRuntimeLoadTickTraitDefinitions(
            $pdo,
            $gameId,
            []
        );

    $boundRepairs =
        wayfarerRuntimeClampApplicableTraitState(
            $runtimeState,
            $traitDefinitions,
            $currentRegionId
        );

    $gameEffects =
        $gameConfig['tick_effects']
        ?? [];

    if (!is_array($gameEffects)) {
        $gameEffects = [];
    }

    $reports = [];

    foreach ($gameEffects as $effect) {

        if (!is_array($effect)) {

            $reports[] = [
                'applied' => false,
                'error' =>
                    'Malformed Game Tick Effect.',
            ];

            continue;
        }

        $reports[] =
            wayfarerApplyRuntimeTickEffect(
                $runtimeState,
                $effect,
                $currentRegionId,
                $traitDefinitions
            );
    }

    if (
        !isset($runtimeState['runtime']) ||
        !is_array($runtimeState['runtime'])
    ) {
        $runtimeState['runtime'] = [];
    }

    $runtimeState['runtime']['last_game_tick_effects'] =
        $reports;

    $runtimeState['runtime']['last_game_trait_bound_repairs'] =
        $boundRepairs;

    return $reports;
}

/*
|--------------------------------------------------------------------------
| Generalized one-time Effect runtime
| WAYFARER_GENERALIZED_EFFECT_RUNTIME_V43
|--------------------------------------------------------------------------
|
| Conditions use the same shared evaluator as Tick Effect branches.
| Random values are resolved exactly once, immediately before the selected
| result mutates runtime state.
|
*/

function wayfarerRuntimeEffectBranches(
    array $effect
): array {

    if (
        array_key_exists(
            'branches',
            $effect
        )
    ) {

        if (
            !is_array(
                $effect['branches']
            )
        ) {
            return [];
        }

        $branches = [];

        foreach (
            $effect['branches']
            as $branch
        ) {

            if (is_array($branch)) {
                $branches[] =
                    $branch;
            }
        }

        return $branches;
    }


    /*
     * v42 compatibility: one Effect was one unconditional operation/value.
     */
    if (
        array_key_exists(
            'operation',
            $effect
        ) ||
        array_key_exists(
            'value',
            $effect
        ) ||
        array_key_exists(
            'value_mode',
            $effect
        ) ||
        array_key_exists(
            'value_min',
            $effect
        ) ||
        array_key_exists(
            'value_max',
            $effect
        )
    ) {

        $branch = [
            'conditions' =>
                null,

            'operation' =>
                $effect['operation']
                ?? 'add',

            'value_mode' =>
                $effect['value_mode']
                ?? 'fixed',
        ];


        if (
            strtolower(
                trim(
                    (string)(
                        $branch[
                            'value_mode'
                        ]
                    )
                )
            ) ===
                'random'
        ) {

            $branch['value_min'] =
                $effect['value_min']
                ?? 0;

            $branch['value_max'] =
                $effect['value_max']
                ?? 0;

        } else {

            $branch['value'] =
                $effect['value']
                ?? 0;
        }


        return [
            $branch
        ];
    }


    return [];
}


function wayfarerRuntimeSelectEffectBranch(
    array &$runtimeState,
    array $effect,
    int $currentRegionId
): array {

    $branches =
        wayfarerRuntimeEffectBranches(
            $effect
        );


    if ($branches === []) {

        return [
            'matched' =>
                false,

            'branch' =>
                null,

            'branch_index' =>
                null,

            'error' =>
                'Effect has no result branches.',
        ];
    }


    $resolver =
        function (
            string $scope,
            string $targetType,
            string $targetId
        ) use (
            &$runtimeState,
            $currentRegionId
        ): array {

            return
                wayfarerRuntimeResolveConditionTarget(
                    $runtimeState,
                    $currentRegionId,
                    $scope,
                    $targetType,
                    $targetId
                );
        };


    foreach (
        $branches
        as $branchIndex => $branch
    ) {

        $conditions =
            $branch['conditions']
            ?? null;


        $validation =
            wayfarerConditionValidateNode(
                $conditions
            );


        if (
            !$validation['valid']
        ) {

            return [
                'matched' =>
                    false,

                'branch' =>
                    null,

                'branch_index' =>
                    (int)$branchIndex,

                'error' =>
                    'Invalid Effect condition: ' .
                    (
                        $validation['error']
                        ?? 'unknown condition error'
                    ),
            ];
        }


        $passes =
            wayfarerConditionEvaluate(
                $validation['node'],
                $resolver
            );


        if (!$passes) {
            continue;
        }


        return [
            'matched' =>
                true,

            'branch' =>
                $branch,

            'branch_index' =>
                (int)$branchIndex,

            'error' =>
                '',
        ];
    }


    return [
        'matched' =>
            false,

        'branch' =>
            null,

        'branch_index' =>
            null,

        'error' =>
            '',
    ];
}


function wayfarerRuntimeRollEffectValue(
    array $branch
): array {

    $mode =
        strtolower(
            trim(
                (string)(
                    $branch[
                        'value_mode'
                    ]
                    ?? 'fixed'
                )
            )
        );


    if ($mode !== 'random') {

        $value =
            $branch['value']
            ?? null;

        /* WAYFARER_FIXED_SCALAR_EFFECT_RUNTIME_V58 */
        return [
            'valid' =>
                true,

            'mode' =>
                'fixed',

            'value' =>
                is_numeric($value)
                    ? wayfarerNormalizeRuntimeNumber(
                        (float)$value
                    )
                    : $value,

            'min' =>
                null,

            'max' =>
                null,

            'error' =>
                '',
        ];
    }


    $minimum =
        $branch['value_min']
        ?? null;

    $maximum =
        $branch['value_max']
        ?? null;


    if (
        !is_numeric($minimum) ||
        !is_numeric($maximum)
    ) {

        return [
            'valid' =>
                false,

            'mode' =>
                'random',

            'value' =>
                null,

            'min' =>
                $minimum,

            'max' =>
                $maximum,

            'error' =>
                'Random Effect requires numeric Min and Max values.',
        ];
    }


    $min =
        (float)$minimum;

    $max =
        (float)$maximum;


    if ($min > $max) {

        return [
            'valid' =>
                false,

            'mode' =>
                'random',

            'value' =>
                null,

            'min' =>
                wayfarerNormalizeRuntimeNumber(
                    $min
                ),

            'max' =>
                wayfarerNormalizeRuntimeNumber(
                    $max
                ),

            'error' =>
                'Random Effect Min cannot be greater than Max.',
        ];
    }


    if (
        floor($min) === $min &&
        floor($max) === $max
    ) {

        $rolled =
            random_int(
                (int)$min,
                (int)$max
            );

    } else {

        /*
         * Continuous decimal range. Six decimal places of entropy are more
         * than sufficient for authored simulation values and preserve generic
         * numeric Min/Max support without requiring authored precision metadata.
         */
        $fraction =
            random_int(
                0,
                1000000
            ) /
            1000000;

        $rolled =
            $min +
            (($max - $min) * $fraction);
    }


    return [
        'valid' =>
            true,

        'mode' =>
            'random',

        'value' =>
            wayfarerNormalizeRuntimeNumber(
                (float)$rolled
            ),

        'min' =>
            wayfarerNormalizeRuntimeNumber(
                $min
            ),

        'max' =>
            wayfarerNormalizeRuntimeNumber(
                $max
            ),

        'error' =>
            '',
    ];
}


function wayfarerApplyRuntimeOneTimeEffect(
    array &$runtimeState,
    array $effect,
    int $currentRegionId,
    array $traitDefinitions = []
): array {

    $selection =
        wayfarerRuntimeSelectEffectBranch(
            $runtimeState,
            $effect,
            $currentRegionId
        );


    $scope =
        strtolower(
            trim(
                (string)(
                    $effect[
                        'target_scope'
                    ]
                    ?? ''
                )
            )
        );

    $type =
        strtolower(
            trim(
                (string)(
                    $effect[
                        'target_type'
                    ]
                    ?? ''
                )
            )
        );

    $targetId =
        trim(
            (string)(
                $effect[
                    'target_id'
                ]
                ?? ''
            )
        );


    if (
        $selection['error'] !==
        ''
    ) {

        return [
            'scope' =>
                $scope,

            'type' =>
                $type,

            'target_id' =>
                $targetId,

            'matched' =>
                false,

            'branch_index' =>
                $selection[
                    'branch_index'
                ],

            'applied' =>
                false,

            'error' =>
                $selection[
                    'error'
                ],
        ];
    }


    if (
        !$selection['matched']
    ) {

        return [
            'scope' =>
                $scope,

            'type' =>
                $type,

            'target_id' =>
                $targetId,

            'matched' =>
                false,

            'branch_index' =>
                null,

            'applied' =>
                false,

            'error' =>
                '',
        ];
    }


    $branch =
        $selection['branch'];

    $branchIndex =
        (int)$selection[
            'branch_index'
        ];

    $operation =
        strtolower(
            trim(
                (string)(
                    $branch[
                        'operation'
                    ]
                    ?? ''
                )
            )
        );

    $isOtherwise =
        !array_key_exists(
            'conditions',
            $branch
        ) ||
        $branch['conditions'] ===
            null ||
        $branch['conditions'] ===
            [];


    if ($operation === 'none') {

        return [
            'scope' =>
                $scope,

            'type' =>
                $type,

            'target_id' =>
                $targetId,

            'operation' =>
                'none',

            'matched' =>
                true,

            'branch_index' =>
                $branchIndex,

            'branch_kind' =>
                $isOtherwise
                    ? 'otherwise'
                    : 'conditional',

            'value_mode' =>
                null,

            'rolled_value' =>
                null,

            'applied' =>
                false,

            'error' =>
                '',
        ];
    }


    $resolved =
        wayfarerRuntimeRollEffectValue(
            $branch
        );


    if (!$resolved['valid']) {

        return [
            'scope' =>
                $scope,

            'type' =>
                $type,

            'target_id' =>
                $targetId,

            'operation' =>
                $operation,

            'matched' =>
                true,

            'branch_index' =>
                $branchIndex,

            'branch_kind' =>
                $isOtherwise
                    ? 'otherwise'
                    : 'conditional',

            'value_mode' =>
                $resolved[
                    'mode'
                ],

            'rolled_value' =>
                null,

            'random_min' =>
                $resolved[
                    'min'
                ],

            'random_max' =>
                $resolved[
                    'max'
                ],

            'applied' =>
                false,

            'error' =>
                $resolved[
                    'error'
                ],
        ];
    }


    $concreteEffect = [
        'target_scope' =>
            $scope,

        'target_type' =>
            $type,

        'target_id' =>
            $targetId,

        'operation' =>
            $operation,

        'value' =>
            $resolved[
                'value'
            ],
    ];


    $report =
        wayfarerApplyRuntimeEffect(
            $runtimeState,
            $concreteEffect,
            $currentRegionId,
            $traitDefinitions
        );


    $report['matched'] =
        true;

    $report['branch_index'] =
        $branchIndex;

    $report['branch_kind'] =
        $isOtherwise
            ? 'otherwise'
            : 'conditional';

    $report['value_mode'] =
        $resolved[
            'mode'
        ];

    $report['rolled_value'] =
        $resolved[
            'value'
        ];


    if (
        $resolved['mode'] ===
        'random'
    ) {

        $report['random_min'] =
            $resolved[
                'min'
            ];

        $report['random_max'] =
            $resolved[
                'max'
            ];
    }


    return $report;
}





/*
|--------------------------------------------------------------------------
| One-time Effect player feedback
| WAYFARER_ONE_TIME_EFFECT_FEEDBACK_V70
|--------------------------------------------------------------------------
|
| Change events are derived from the Effect report AFTER runtime mutation.
| Therefore Random rolls and min/max/non-negative clamps are already reflected
| in before/after, and the player sees the quantity that truly changed.
|
| This layer is intentionally called only by narrative one-time Effect paths.
| Tick Effects remain silent.
|
*/

function wayfarerRuntimeFeedbackFindTrait(
    array $config,
    string $targetId,
    string $collection = 'traits'
): ?array {

    $traits =
        isset($config[$collection]) &&
        is_array($config[$collection])
            ? $config[$collection]
            : [];

    foreach ($traits as $trait) {
        if (!is_array($trait)) {
            continue;
        }

        $id = trim(
            (string)(
                $trait['id']
                ?? $trait['system_key']
                ?? ''
            )
        );

        if ($id === $targetId) {
            return $trait;
        }
    }

    return null;
}


function wayfarerRuntimeFeedbackTraitIsPlayerFacing(array $trait): bool
{
    $feedback = strtolower(
        trim(
            (string)(
                $trait['feedback']
                ?? ''
            )
        )
    );

    if ($feedback === 'hide') {
        return false;
    }

    if ($feedback === 'show') {
        return true;
    }

    $display =
        isset($trait['display']) &&
        is_array($trait['display'])
            ? $trait['display']
            : [];

    $surfaces =
        isset($display['surfaces']) &&
        is_array($display['surfaces'])
            ? $display['surfaces']
            : [];

    return !empty($surfaces);
}


function wayfarerRuntimeFeedbackTraitMetadata(
    array $trait,
    string $fallbackLabel,
    string $ownerLabel = ''
): ?array {

    if (!wayfarerRuntimeFeedbackTraitIsPlayerFacing($trait)) {
        return null;
    }

    $label = trim(
        (string)(
            $trait['name']
            ?? $fallbackLabel
        )
    );

    if ($label === '') {
        $label = $fallbackLabel;
    }

    $type = strtolower(
        trim(
            (string)(
                $trait['type']
                ?? 'number'
            )
        )
    );

    if ($type === 'binary') {
        $type = 'boolean';
    }

    return [
        'kind' => 'trait',
        'label' => $label,
        'owner_label' => $ownerLabel,
        'data_type' => $type,
    ];
}


function wayfarerRuntimeFeedbackTargetMetadata(
    PDO $pdo,
    int $gameId,
    array $runtimeState,
    array $report
): ?array {

    $scope = strtolower(
        trim(
            (string)(
                $report['scope']
                ?? ''
            )
        )
    );

    $type = strtolower(
        trim(
            (string)(
                $report['type']
                ?? ''
            )
        )
    );

    $targetId = trim(
        (string)(
            $report['target_id']
            ?? ''
        )
    );

    if (
        $scope === '' ||
        $targetId === '' ||
        !in_array($type, ['trait', 'status'], true)
    ) {
        return null;
    }

    /* WAYFARER_STATUS_EFFECT_FEEDBACK_V87 */
    if (
        $type === 'status' &&
        preg_match('/^[1-9][0-9]*$/', $targetId) === 1
    ) {
        $definition =
            wayfarerRuntimeStatusDefinition(
                $pdo,
                $gameId,
                (int)$targetId,
                true
            );

        if (
            !is_array($definition) ||
            empty($definition['show_to_player'])
        ) {
            return null;
        }

        $ownerLabel = '';

        if (
            preg_match(
                '/^player:([0-9]+)$/',
                $scope,
                $playerStatusMatch
            ) === 1
        ) {
            $slot = (string)((int)$playerStatusMatch[1]);
            $ownerLabel =
                trim(
                    (string)(
                        $runtimeState['players'][$slot]['name']
                        ?? ('Player ' . ((int)$slot + 1))
                    )
                );
        } elseif (
            preg_match(
                '/^entity:([1-9][0-9]*)$/',
                $scope,
                $entityStatusMatch
            ) === 1
        ) {
            $entityId = (int)$entityStatusMatch[1];
            $stmt = $pdo->prepare(
                "
                SELECT name
                FROM wf_entities
                WHERE id = ?
                  AND game_id = ?
                LIMIT 1
                "
            );
            $stmt->execute([
                $entityId,
                $gameId,
            ]);
            $name = $stmt->fetchColumn();
            if ($name !== false) {
                $ownerLabel = trim((string)$name);
            }
        }

        return [
            'kind' => 'status',
            'label' => (string)($definition['name'] ?? ('Status ' . $targetId)),
            'owner_label' => $ownerLabel,
            'data_type' => 'boolean',
        ];
    }

    /* Navigation is deliberately silent even for one-time Effects. */
    if ($scope === 'navigation') {
        return null;
    }

    /* --------------------------------------------------------------
     * Entity state: Quantity and Party Membership are intrinsically visible.
     * ----------------------------------------------------------- */
    if (
        preg_match(
            '/^entity:([1-9][0-9]*)$/',
            $scope,
            $entityMatch
        ) === 1
    ) {
        $entityId = (int)$entityMatch[1];

        $stmt = $pdo->prepare(
            "
            SELECT name, entity_type, config
            FROM wf_entities
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

        $stmt->execute([
            $entityId,
            $gameId,
        ]);

        $row = $stmt->fetch(PDO::FETCH_ASSOC);
        if (!$row) {
            return null;
        }

        $entityName = trim(
            (string)(
                $row['name']
                ?? ('Entity ' . $entityId)
            )
        );

        if ($entityName === '') {
            $entityName = 'Entity ' . $entityId;
        }

        $systemKey = strtolower(
            trim(
                (string)(
                    $report['target_system_key']
                    ?? ''
                )
            )
        );

        if (
            $targetId === 'sys_item_quantity' ||
            $systemKey === 'quantity'
        ) {
            return [
                'kind' => 'item_quantity',
                'label' => $entityName,
                'owner_label' => $entityName,
                'data_type' => 'number',
            ];
        }

        if (
            $targetId === 'sys_character_party_member' ||
            $systemKey === 'party_member'
        ) {
            return [
                'kind' => 'party_membership',
                'label' => $entityName,
                'owner_label' => $entityName,
                'data_type' => 'boolean',
            ];
        }

        $config = wayfarerRuntimeDecodeTraitConfig(
            $row['config']
            ?? null
        );

        $trait = wayfarerRuntimeFeedbackFindTrait(
            $config,
            $targetId
        );

        return is_array($trait)
            ? wayfarerRuntimeFeedbackTraitMetadata(
                $trait,
                $targetId,
                $entityName
            )
            : null;
    }

    /* --------------------------------------------------------------
     * Game Trait.
     * ----------------------------------------------------------- */
    if ($scope === 'game') {
        $stmt = $pdo->prepare(
            'SELECT config FROM wf_games WHERE id = ? LIMIT 1'
        );
        $stmt->execute([$gameId]);
        $raw = $stmt->fetchColumn();

        if ($raw === false) {
            return null;
        }

        $config = wayfarerRuntimeDecodeTraitConfig($raw);
        $trait = wayfarerRuntimeFeedbackFindTrait(
            $config,
            $targetId
        );

        return is_array($trait)
            ? wayfarerRuntimeFeedbackTraitMetadata(
                $trait,
                $targetId,
                'Game'
            )
            : null;
    }

    /* --------------------------------------------------------------
     * Specific Region Trait, plus legacy current-Region compatibility.
     * ----------------------------------------------------------- */
    $regionId = 0;

    if (
        preg_match(
            '/^region:([1-9][0-9]*)$/',
            $scope,
            $regionMatch
        ) === 1
    ) {
        $regionId = (int)$regionMatch[1];
    } elseif ($scope === 'region') {
        $regionId = (int)(
            $runtimeState['navigation']['region_id']
            ?? 0
        );
    }

    if ($regionId > 0) {
        $stmt = $pdo->prepare(
            "
            SELECT name, config
            FROM wf_regions
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );
        $stmt->execute([
            $regionId,
            $gameId,
        ]);
        $row = $stmt->fetch(PDO::FETCH_ASSOC);

        if (!$row) {
            return null;
        }

        $config = wayfarerRuntimeDecodeTraitConfig(
            $row['config']
            ?? null
        );
        $trait = wayfarerRuntimeFeedbackFindTrait(
            $config,
            $targetId
        );

        return is_array($trait)
            ? wayfarerRuntimeFeedbackTraitMetadata(
                $trait,
                $targetId,
                trim((string)($row['name'] ?? 'Region'))
            )
            : null;
    }

    /* --------------------------------------------------------------
     * Location Trait.
     * ----------------------------------------------------------- */
    if (
        preg_match(
            '/^location:([1-9][0-9]*)$/',
            $scope,
            $locationMatch
        ) === 1
    ) {
        $locationId = (int)$locationMatch[1];
        $stmt = $pdo->prepare(
            "
            SELECT l.name, l.config
            FROM wf_locations l
            INNER JOIN wf_regions r
                ON r.id = l.region_id
            WHERE l.id = ?
              AND r.game_id = ?
            LIMIT 1
            "
        );
        $stmt->execute([
            $locationId,
            $gameId,
        ]);
        $row = $stmt->fetch(PDO::FETCH_ASSOC);

        if (!$row) {
            return null;
        }

        $config = wayfarerRuntimeDecodeTraitConfig(
            $row['config']
            ?? null
        );
        $trait = wayfarerRuntimeFeedbackFindTrait(
            $config,
            $targetId
        );

        return is_array($trait)
            ? wayfarerRuntimeFeedbackTraitMetadata(
                $trait,
                $targetId,
                trim((string)($row['name'] ?? 'Location'))
            )
            : null;
    }

    /* --------------------------------------------------------------
     * Specific Player Character Trait.
     * ----------------------------------------------------------- */
    if (
        preg_match(
            '/^player:([0-9]+)$/',
            $scope,
            $playerMatch
        ) === 1
    ) {
        $slot = (int)$playerMatch[1];
        $stmt = $pdo->prepare(
            'SELECT config FROM wf_games WHERE id = ? LIMIT 1'
        );
        $stmt->execute([$gameId]);
        $raw = $stmt->fetchColumn();

        if ($raw === false) {
            return null;
        }

        $config = wayfarerRuntimeDecodeTraitConfig($raw);
        $trait = wayfarerRuntimeFeedbackFindTrait(
            $config,
            $targetId,
            'player_traits'
        );

        if (!is_array($trait)) {
            return null;
        }

        $playerName = trim(
            (string)(
                $runtimeState['players'][(string)$slot]['name']
                ?? ('Player ' . ($slot + 1))
            )
        );

        return wayfarerRuntimeFeedbackTraitMetadata(
            $trait,
            $targetId,
            $playerName
        );
    }

    return null;
}


function wayfarerRuntimeBuildEffectChangeEvents(
    PDO $pdo,
    int $gameId,
    array $runtimeState,
    array $reports
): array {

    $changes = [];

    foreach ($reports as $report) {
        if (
            !is_array($report) ||
            empty($report['applied'])
        ) {
            continue;
        }

        /* WAYFARER_PARTY_TARGETS_RUNTIME_V85 */
        if (
            strtolower(
                trim(
                    (string)(
                        $report['scope']
                        ?? ''
                    )
                )
            ) === 'party' &&
            isset($report['results']) &&
            is_array($report['results'])
        ) {
            foreach (
                wayfarerRuntimeBuildEffectChangeEvents(
                    $pdo,
                    $gameId,
                    $runtimeState,
                    $report['results']
                )
                as $partyChange
            ) {
                $changes[] =
                    $partyChange;
            }

            continue;
        }

        $metadata =
            wayfarerRuntimeFeedbackTargetMetadata(
                $pdo,
                $gameId,
                $runtimeState,
                $report
            );

        if (!is_array($metadata)) {
            continue;
        }

        $before = $report['before'] ?? null;
        $after = $report['after'] ?? null;
        $kind = (string)($metadata['kind'] ?? 'trait');
        $label = trim((string)($metadata['label'] ?? ''));
        $ownerLabel = trim((string)($metadata['owner_label'] ?? ''));

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

        if ($kind === 'status') {
            if (!is_numeric($before) || !is_numeric($after)) {
                continue;
            }

            $beforeActive = (float)$before > 0;
            $afterActive = (float)$after > 0;

            if ($beforeActive === $afterActive) {
                continue;
            }

            $displayLabel =
                $ownerLabel !== ''
                    ? $label . ' — ' . $ownerLabel
                    : $label;

            $changes[] = [
                'kind' => 'status',
                'direction' => $afterActive ? 'gain' : 'loss',
                'label' => $label,
                'owner_label' => $ownerLabel,
                'before' => $beforeActive ? 1 : 0,
                'after' => $afterActive ? 1 : 0,
                'delta' => $afterActive ? 1 : -1,
                'text' =>
                    $displayLabel .
                    ': ' .
                    ($afterActive ? 'Active' : 'Inactive'),
                'aria_text' =>
                    ($ownerLabel !== ''
                        ? $ownerLabel . ': ' . $label
                        : $label) .
                    ' is now ' .
                    ($afterActive ? 'active.' : 'inactive.'),
            ];
            continue;
        }

        if ($kind === 'party_membership') {
            if (!is_numeric($before) || !is_numeric($after)) {
                continue;
            }

            $beforeMember = (float)$before > 0;
            $afterMember = (float)$after > 0;

            if ($beforeMember === $afterMember) {
                continue;
            }

            $joined = $afterMember;
            $changes[] = [
                'kind' => 'party_membership',
                'direction' => $joined ? 'gain' : 'loss',
                'label' => $label,
                'before' => $beforeMember ? 1 : 0,
                'after' => $afterMember ? 1 : 0,
                'delta' => $joined ? 1 : -1,
                'text' =>
                    $label .
                    ($joined
                        ? ' joined your party.'
                        : ' left your party.'),
                'aria_text' =>
                    $label .
                    ($joined
                        ? ' joined your party.'
                        : ' left your party.'),
            ];
            continue;
        }

        $dataType = strtolower(
            trim((string)($metadata['data_type'] ?? 'number'))
        );

        if ($dataType === 'boolean') {
            if (!is_numeric($before) || !is_numeric($after)) {
                continue;
            }

            $beforeBool = (float)$before > 0;
            $afterBool = (float)$after > 0;

            if ($beforeBool === $afterBool) {
                continue;
            }

            $displayLabel =
                $ownerLabel !== '' &&
                $ownerLabel !== $label
                    ? $label . ' — ' . $ownerLabel
                    : $label;

            $changes[] = [
                'kind' => $kind,
                'direction' => $afterBool ? 'gain' : 'loss',
                'label' => $label,
                'owner_label' => $ownerLabel,
                'before' => $beforeBool ? 1 : 0,
                'after' => $afterBool ? 1 : 0,
                'delta' => $afterBool ? 1 : -1,
                'text' => $displayLabel . ': ' . ($afterBool ? 'On' : 'Off'),
                'aria_text' =>
                    ($ownerLabel !== '' && $ownerLabel !== $label
                        ? $ownerLabel . ': ' . $label
                        : $label) .
                    ' is now ' .
                    ($afterBool ? 'on.' : 'off.'),
            ];
            continue;
        }

        if (!is_numeric($before) || !is_numeric($after)) {
            continue;
        }

        $deltaFloat = (float)$after - (float)$before;

        if (abs($deltaFloat) < 0.000000000001) {
            continue;
        }

        $delta = wayfarerNormalizeRuntimeNumber($deltaFloat);
        $amount = wayfarerNormalizeRuntimeNumber(abs($deltaFloat));
        $gain = $deltaFloat > 0;

        $displayLabel =
            $ownerLabel !== '' &&
            $ownerLabel !== $label &&
            $kind !== 'item_quantity'
                ? $label . ' — ' . $ownerLabel
                : $label;

        $text =
            ($gain ? '+' : '-') .
            (string)$amount .
            ' ' .
            $displayLabel;

        if ($kind === 'item_quantity') {
            $ariaText =
                ($gain ? 'Gained ' : 'Lost ') .
                (string)$amount .
                ' ' .
                $label .
                '.';
        } else {
            $ariaSubject =
                $ownerLabel !== '' &&
                $ownerLabel !== $label
                    ? $ownerLabel . ': ' . $label
                    : $label;

            $ariaText =
                $ariaSubject .
                ($gain ? ' increased by ' : ' decreased by ') .
                (string)$amount .
                '.';
        }

        $changes[] = [
            'kind' => $kind,
            'direction' => $gain ? 'gain' : 'loss',
            'label' => $label,
            'owner_label' => $ownerLabel,
            'before' => $before,
            'after' => $after,
            'delta' => $delta,
            'text' => $text,
            'aria_text' => $ariaText,
        ];
    }

    return $changes;
}

/*
|--------------------------------------------------------------------------
| Location Effects
|--------------------------------------------------------------------------
|
| WAYFARER_LOCATION_ONE_TIME_EFFECT_RUNTIME_V42
|
| These are event Effects, not Tick Effects. The caller decides that a
| Location has been triggered and invokes this function exactly once for that
| trigger. Effects execute top-to-bottom against current runtime state.
|
*/

function wayfarerApplyLocationEffects(
    PDO $pdo,
    int $gameId,
    array $location,
    array &$runtimeState
): array {

    $locationId =
        (int)(
            $location['id']
            ?? 0
        );

    $locationConfig =
        isset(
            $location['_runtime_config']
        ) &&
        is_array(
            $location['_runtime_config']
        )
            ? $location['_runtime_config']
            : wayfarerRuntimeDecodeTraitConfig(
                $location['config']
                ?? null
            );


    $effects =
        $locationConfig['effects']
        ?? [];

    if (!is_array($effects)) {
        $effects = [];
    }


    $currentRegionId =
        (int)(
            $runtimeState['navigation']['region_id']
            ?? 0
        );


    $regionConfig = [];

    if ($currentRegionId > 0) {

        $regionStmt =
            $pdo->prepare(
                "
                SELECT config
                FROM wf_regions
                WHERE id = ?
                  AND game_id = ?
                LIMIT 1
                "
            );

        $regionStmt->execute([
            $currentRegionId,
            $gameId,
        ]);

        $rawRegionConfig =
            $regionStmt->fetchColumn();

        if (
            $rawRegionConfig !== false
        ) {

            $regionConfig =
                wayfarerRuntimeDecodeTraitConfig(
                    $rawRegionConfig
                );
        }
    }


    $traitDefinitions =
        wayfarerRuntimeLoadTickTraitDefinitions(
            $pdo,
            $gameId,
            $regionConfig
        );


    $boundRepairs =
        wayfarerRuntimeClampApplicableTraitState(
            $runtimeState,
            $traitDefinitions,
            $currentRegionId
        );


    $reports =
        [];

    foreach ($effects as $effect) {

        if (!is_array($effect)) {

            $reports[] = [
                'applied' =>
                    false,

                'error' =>
                    'Malformed Location Effect.',
            ];

            continue;
        }


        $reports[] =
            wayfarerApplyRuntimeOneTimeEffect(
                $runtimeState,
                $effect,
                $currentRegionId,
                $traitDefinitions
            );
    }


    if (
        !isset(
            $runtimeState['runtime']
        ) ||
        !is_array(
            $runtimeState['runtime']
        )
    ) {
        $runtimeState['runtime'] = [];
    }


    $runtimeState['runtime']['last_location_effects'] = [
        'location_id' =>
            $locationId,

        'tick' =>
            (int)(
                $runtimeState['runtime']['tick']
                ?? 0
            ),

        'reports' =>
            $reports,

        /* WAYFARER_LOCATION_EFFECT_FEEDBACK_V70 */
        'changes' =>
            wayfarerRuntimeBuildEffectChangeEvents(
                $pdo,
                $gameId,
                $runtimeState,
                $reports
            ),

        'bound_repairs' =>
            $boundRepairs,
    ];


    return $reports;
}


/*
|--------------------------------------------------------------------------
| Current Location Tick Effects
|--------------------------------------------------------------------------
|
| WAYFARER_LOCATION_TICK_EFFECT_RUNTIME_V35
|
| Linear Regions resolve a current Location by exact authored Position,
| matching the player-scene resolver. Location Tick Effects run after Region
| Tick Effects, so movement performed by the Region can cause arrival effects
| at the newly reached Location on the same tick.
|
*/

function wayfarerRuntimeFindCurrentLocation(
    PDO $pdo,
    int $gameId,
    array $runtimeState
): ?array {

    $regionId =
        (int)(
            $runtimeState['navigation']['region_id']
            ?? 0
        );

    if (
        $gameId <= 0 ||
        $regionId <= 0
    ) {
        return null;
    }


    $position =
        $runtimeState['navigation']['position']
        ?? null;

    if (!is_numeric($position)) {
        return null;
    }


    $regionStmt =
        $pdo->prepare(
            "
            SELECT navigation_type
            FROM wf_regions
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

    $regionStmt->execute([
        $regionId,
        $gameId,
    ]);

    $navigationType =
        $regionStmt->fetchColumn();

    if (
        $navigationType === false ||
        strtolower(
            trim(
                (string)$navigationType
            )
        ) !== 'linear'
    ) {
        return null;
    }


    $locationStmt =
        $pdo->prepare(
            "
            SELECT *
            FROM wf_locations
            WHERE region_id = ?
              AND status = 'active'
            ORDER BY id
            "
        );

    $locationStmt->execute([
        $regionId
    ]);

    $locations =
        $locationStmt->fetchAll(
            PDO::FETCH_ASSOC
        );


    foreach ($locations as $location) {

        $config = [];

        if (
            !empty(
                $location['config']
            )
        ) {

            $decoded =
                json_decode(
                    (string)$location['config'],
                    true
                );

            if (is_array($decoded)) {
                $config =
                    $decoded;
            }
        }


        if (
            !array_key_exists(
                'position',
                $config
            ) ||
            !is_numeric(
                $config['position']
            )
        ) {
            continue;
        }


        if (
            (float)$config['position'] ===
            (float)$position
        ) {

            $location['_runtime_config'] =
                $config;

            /*
             * WAYFARER_LOCATION_CONDITIONS_CURRENT_V45
             */
            if (
                !wayfarerRuntimeLocationConditionsPass(
                    $pdo,
                    $gameId,
                    $location,
                    $runtimeState
                )
            ) {
                continue;
            }

            return $location;
        }
    }


    return null;
}


function wayfarerApplyCurrentLocationTickEffects(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): array {

    $location =
        wayfarerRuntimeFindCurrentLocation(
            $pdo,
            $gameId,
            $runtimeState
        );


    if (
        !isset(
            $runtimeState['runtime']
        ) ||
        !is_array(
            $runtimeState['runtime']
        )
    ) {
        $runtimeState['runtime'] = [];
    }


    /*
     * Being between authored Locations is normal. Record an empty result
     * rather than treating the absence of a Location as an error.
     */
    if (!$location) {

        $runtimeState['runtime']['last_location_id'] =
            null;

        $runtimeState['runtime']['last_location_tick_effects'] =
            [];

        return [];
    }


    $locationId =
        (int)(
            $location['id']
            ?? 0
        );

    $locationConfig =
        isset(
            $location['_runtime_config']
        ) &&
        is_array(
            $location['_runtime_config']
        )
            ? $location['_runtime_config']
            : [];


    $currentRegionId =
        (int)(
            $runtimeState['navigation']['region_id']
            ?? 0
        );


    /*
     * Location effects may target Current Region Traits, so load the active
     * Region's Trait definitions rather than the Location's authored Traits.
     */
    $regionConfig = [];

    if ($currentRegionId > 0) {

        $regionStmt =
            $pdo->prepare(
                "
                SELECT config
                FROM wf_regions
                WHERE id = ?
                  AND game_id = ?
                LIMIT 1
                "
            );

        $regionStmt->execute([
            $currentRegionId,
            $gameId,
        ]);

        $rawRegionConfig =
            $regionStmt->fetchColumn();

        if (
            $rawRegionConfig !== false &&
            $rawRegionConfig !== null &&
            $rawRegionConfig !== ''
        ) {

            $decoded =
                json_decode(
                    (string)$rawRegionConfig,
                    true
                );

            if (is_array($decoded)) {
                $regionConfig =
                    $decoded;
            }
        }
    }


    $traitDefinitions =
        wayfarerRuntimeLoadTickTraitDefinitions(
            $pdo,
            $gameId,
            $regionConfig
        );


    $boundRepairs =
        wayfarerRuntimeClampApplicableTraitState(
            $runtimeState,
            $traitDefinitions,
            $currentRegionId
        );


    $locationEffects =
        $locationConfig['tick_effects']
        ?? [];

    if (!is_array($locationEffects)) {
        $locationEffects = [];
    }


    $reports = [];

    foreach (
        $locationEffects
        as $effect
    ) {

        if (!is_array($effect)) {

            $reports[] = [
                'applied' => false,
                'error' =>
                    'Malformed Location Tick Effect.',
            ];

            continue;
        }


        $reports[] =
            wayfarerApplyRuntimeTickEffect(
                $runtimeState,
                $effect,
                $currentRegionId,
                $traitDefinitions
            );
    }


    $runtimeState['runtime']['last_location_id'] =
        $locationId;

    $runtimeState['runtime']['last_location_tick_effects'] =
        $reports;

    $runtimeState['runtime']['last_location_trait_bound_repairs'] =
        $boundRepairs;


    return $reports;
}

/*
 * WAYFARER_GAME_TRAVEL_MODIFIERS_RUNTIME_V73
 *
 * Game Travel Modifiers are evaluated only when dedicated Linear Travel is
 * about to move the player. They do not mutate state by themselves and are
 * intentionally silent in normal Effect feedback.
 */
function wayfarerRuntimeEvaluateGameTravelModifiers(
    PDO $pdo,
    int $gameId,
    int $currentRegionId,
    array &$runtimeState
): array {
    $result = [
        'adjustment' => 0,
        'matched' => [],
    ];

    if ($gameId <= 0) {
        return $result;
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_games
            WHERE id = ?
            LIMIT 1
            "
        );

    $stmt->execute([
        $gameId
    ]);

    $rawConfig =
        $stmt->fetchColumn();

    if (
        $rawConfig === false ||
        $rawConfig === null ||
        $rawConfig === ''
    ) {
        return $result;
    }

    $gameConfig =
        json_decode(
            (string)$rawConfig,
            true
        );

    if (!is_array($gameConfig)) {
        return $result;
    }

    $modifiers =
        $gameConfig['travel']['modifiers']
        ?? [];

    if (!is_array($modifiers)) {
        return $result;
    }

    $resolver =
        function (
            string $scope,
            string $targetType,
            string $targetId
        ) use (
            &$runtimeState,
            $currentRegionId
        ): array {
            return
                wayfarerRuntimeResolveConditionTarget(
                    $runtimeState,
                    $currentRegionId,
                    $scope,
                    $targetType,
                    $targetId
                );
        };

    $adjustment =
        0.0;

    foreach (
        array_values($modifiers)
        as $modifier
    ) {
        if (!is_array($modifier)) {
            continue;
        }

        $operation =
            strtolower(
                trim(
                    (string)(
                        $modifier['operation']
                        ?? ''
                    )
                )
            );

        $value =
            $modifier['value']
            ?? null;

        if (
            !in_array(
                $operation,
                ['add', 'subtract'],
                true
            ) ||
            !is_numeric($value) ||
            (float)$value <= 0
        ) {
            continue;
        }

        if (
            !wayfarerConditionsPass(
                $modifier['conditions']
                    ?? null,
                $resolver
            )
        ) {
            continue;
        }

        $delta =
            $operation === 'subtract'
                ? -(float)$value
                : (float)$value;

        $adjustment +=
            $delta;

        $result['matched'][] = [
            'id' =>
                (string)(
                    $modifier['id']
                    ?? ''
                ),
            'name' =>
                (string)(
                    $modifier['name']
                    ?? 'Travel Modifier'
                ),
            'operation' =>
                $operation,
            'value' =>
                wayfarerNormalizeRuntimeNumber(
                    (float)$value
                ),
            'adjustment' =>
                wayfarerNormalizeRuntimeNumber(
                    $delta
                ),
        ];
    }

    $result['adjustment'] =
        wayfarerNormalizeRuntimeNumber(
            $adjustment
        );

    return $result;
}

function wayfarerApplyCurrentRegionTickEffects(
    PDO $pdo,
    array &$runtimeState
): array {

    $regionId =
        (int)(
            $runtimeState['navigation']['region_id'] ??
            0
        );

    if ($regionId <= 0) {

        $reports = [
            [
                'applied' => false,
                'error'   =>
                    'No active navigation region.',
            ]
        ];

        /*
         * WAYFARER_RUNTIME_DIAGNOSTIC_CLEANUP_V55
         * Reports are returned for the current request, not persisted.
         */
        return $reports;
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                game_id,
                config
            FROM wf_regions
            WHERE id = ?
            LIMIT 1
            "
        );

    $stmt->execute([
        $regionId
    ]);

    $region =
        $stmt->fetch(
            PDO::FETCH_ASSOC
        );

    if (!$region) {

        $reports = [
            [
                'applied' => false,
                'error'   =>
                    'Active Region ' .
                    $regionId .
                    ' was not found.',
            ]
        ];

        /*
         * WAYFARER_RUNTIME_DIAGNOSTIC_CLEANUP_V55
         * Reports are returned for the current request, not persisted.
         */
        return $reports;
    }

    $config = [];

    if (!empty($region['config'])) {

        $decoded =
            json_decode(
                $region['config'],
                true
            );

        if (is_array($decoded)) {
            $config = $decoded;
        }
    }

    /* WAYFARER_LINEAR_TRAVEL_TICK_PIPELINE_V72 */
    $dedicatedTravel =
        wayfarerRuntimeDedicatedLinearTravel(
            $config
        );

    $traitDefinitions =
        wayfarerRuntimeLoadTickTraitDefinitions(
            $pdo,
            (int)(
                $region['game_id']
                ?? 0
            ),
            $config
        );

    /*
     * Enforce the invariant before any branch condition is evaluated.
     * This also repairs state produced by older runtime versions.
     */
    $boundRepairs =
        wayfarerRuntimeClampApplicableTraitState(
            $runtimeState,
            $traitDefinitions,
            $regionId
        );


    $effects =
        $config['tick_effects'] ??
        [];

    if (!is_array($effects)) {
        $effects = [];
    }

    $reports = [];

    foreach ($effects as $effect) {

        if (!is_array($effect)) {

            $reports[] = [
                'applied' => false,
                'error'   =>
                    'Malformed tick effect.',
            ];

            continue;
        }

        /*
         * WAYFARER_LINEAR_TRAVEL_RUNTIME_V72
         *
         * A dedicated travel Region owns movement through config.travel.
         * Ignore only Region Tick Effects that target Navigation Position;
         * every other recurring Region Effect continues normally.
         */
        if (
            $dedicatedTravel !== null &&
            strtolower(
                trim(
                    (string)(
                        $effect['target_scope']
                        ?? ''
                    )
                )
            ) === 'navigation' &&
            strtolower(
                trim(
                    (string)(
                        $effect['target_type']
                        ?? ''
                    )
                )
            ) === 'position' &&
            (string)(
                $effect['target_id']
                ?? ''
            ) === 'position'
        ) {
            $reports[] = [
                'scope' => 'navigation',
                'type' => 'position',
                'target_id' => 'position',
                'applied' => false,
                'ignored' => true,
                'reason' =>
                    'Dedicated Linear Travel owns Region movement.',
                'error' => '',
            ];

            continue;
        }

        $reports[] =
            wayfarerApplyRuntimeTickEffect(
                $runtimeState,
                $effect,
                $regionId,
                $traitDefinitions
            );
    }

    /* WAYFARER_GAME_TRAVEL_MODIFIERS_RUNTIME_V73 */
    if ($dedicatedTravel !== null) {
        $gameTravelModifierResult =
            wayfarerRuntimeEvaluateGameTravelModifiers(
                $pdo,
                (int)(
                    $region['game_id']
                    ?? 0
                ),
                $regionId,
                $runtimeState
            );

        $reports[] =
            wayfarerRuntimeApplyDedicatedLinearTravelMovement(
                $runtimeState,
                $dedicatedTravel,
                (float)(
                    $gameTravelModifierResult[
                        'adjustment'
                    ]
                    ?? 0
                ),
                $gameTravelModifierResult[
                    'matched'
                ]
                ?? []
            );
    }

    /*
     * WAYFARER_RUNTIME_DIAGNOSTIC_CLEANUP_V55
     * Tick reports and bound-repair reports are immediate diagnostics only.
     */
    return $reports;
}



==============================================================================
FILE: play/includes/ending-screen.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Terminal Game Ending
 * WAYFARER_GAME_ENDING_SCREEN_V45
 * --------------------------------------------------------------------------
 */

$ending =
    $state['runtime']['ending']
    ?? null;

if (
    !is_array($ending) ||
    empty($ending['id'])
) {
    return;
}


$endingImageUrl =
    '';

$imageMediaId =
    (int)(
        $ending['image_media_id']
        ?? 0
    );

if ($imageMediaId > 0) {

    $stmt =
        $pdo->prepare(
            "
            SELECT relative_path
            FROM wf_media
            WHERE id = ?
              AND game_id = ?
              AND media_type = 'image'
            LIMIT 1
            "
        );

    $stmt->execute([
        $imageMediaId,
        (int)$gameId,
    ]);

    $relativePath =
        $stmt->fetchColumn();

    if ($relativePath !== false) {

        $relativePath =
            ltrim(
                str_replace(
                    '\\',
                    '/',
                    (string)$relativePath
                ),
                '/'
            );

        if (
            $relativePath !== '' &&
            strpos(
                $relativePath,
                '..'
            ) === false
        ) {
            $endingImageUrl =
                '../' .
                $relativePath;
        }
    }
}

?>
<script>
document.body.classList.add('wayfarer-game-ended');
</script>

<section
    class="wayfarer-ending-screen"
    data-wayfarer-ending-screen
    role="dialog"
    aria-modal="true"
    aria-labelledby="wayfarer-ending-title"
>
    <div class="wayfarer-ending-inner">

        <?php if ($endingImageUrl !== ''): ?>

            <figure class="wayfarer-ending-media">
                <img
                    src="<?= htmlspecialchars(
                        $endingImageUrl,
                        ENT_QUOTES,
                        'UTF-8'
                    ) ?>"
                    alt=""
                >
            </figure>

        <?php endif; ?>


        <div class="wayfarer-ending-copy">
            <p class="wayfarer-ending-eyebrow">
                The End
            </p>

            <h1 id="wayfarer-ending-title">
                <?= htmlspecialchars(
                    (string)(
                        $ending['title']
                        ?? 'The End'
                    )
                ) ?>
            </h1>

            <?php if (
                trim(
                    (string)(
                        $ending['text']
                        ?? ''
                    )
                ) !== ''
            ): ?>

                <div class="wayfarer-ending-text">
                    <?= nl2br(
                        htmlspecialchars(
                            (string)$ending['text']
                        )
                    ) ?>
                </div>

            <?php endif; ?>

            <!-- WAYFARER_ENDING_RESTART_V63 -->
            <div class="wayfarer-ending-actions">
                <button
                    type="button"
                    class="wayfarer-ending-restart"
                    data-wayfarer-restart-game
                >
                    Start Over
                </button>
            </div>
        </div>

    </div>
</section>


==============================================================================
FILE: play/includes/entity-state.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Canonical Entity runtime state
 * WAYFARER_ENTITY_RUNTIME_STATE_V49
 * --------------------------------------------------------------------------
 *
 * Entity definitions remain authored in wf_entities/config.
 * Per-playthrough mutable values live only in wf_game_users.state.
 *
 * Runtime shape:
 *
 *   entities[ENTITY_ID] = [
 *       'traits' => [
 *           TRAIT_ID => CURRENT_VALUE,
 *       ],
 *       'discovered' => true|false,   // Items only
 *   ];
 *
 * The helper is intentionally additive. Existing state wins.
 */


function wayfarerEntityDecodeConfig($rawConfig): array
{
    if (is_array($rawConfig)) {
        return $rawConfig;
    }

    if (
        $rawConfig === null ||
        $rawConfig === ''
    ) {
        return [];
    }

    $decoded =
        json_decode(
            (string)$rawConfig,
            true
        );

    return is_array($decoded)
        ? $decoded
        : [];
}


function wayfarerEntityActiveTraitDefinitions(
    array $config,
    string $entityType = ''
): array {
    $definitions = [];

    /*
     * WAYFARER_ENTITY_SYSTEM_CONFIG_V55
     *
     * Rehydrate only mutable universal Entity state. Static presentation rules
     * such as inventory_visibility remain authored configuration and are not
     * copied into wf_game_users.state.
     */
    $system =
        isset($config['system']) &&
        is_array($config['system'])
            ? $config['system']
            : [];

    $entityType =
        strtolower(
            trim($entityType)
        );

    if ($entityType === 'item') {
        $quantity =
            isset($system['quantity']) &&
            is_array($system['quantity'])
                ? $system['quantity']
                : [];

        $definitions['sys_item_quantity'] = [
            'id' => 'sys_item_quantity',
            'name' => 'quantity',
            'type' => 'number',
            'min' => 0,
            'max' => $quantity['max'] ?? null,
            'initial' => $quantity['initial'] ?? 0,
            'active' => true,
            'system' => true,
            'system_group' => 'item',
            'system_key' => 'quantity',
            '_runtime_id' => 'sys_item_quantity',
        ];
    }

    if ($entityType === 'character') {
        $definitions['sys_character_party_member'] = [
            'id' => 'sys_character_party_member',
            'name' => 'party_member',
            'type' => 'binary',
            'min' => 0,
            'max' => 1,
            'initial' => (int)($system['party_member'] ?? 0),
            'active' => true,
            'system' => true,
            'system_group' => 'character',
            'system_key' => 'party_member',
            '_runtime_id' => 'sys_character_party_member',
        ];
    }

    $traits =
        $config['traits']
        ?? [];

    if (!is_array($traits)) {
        $traits = [];
    }

    foreach ($traits as $trait) {

        if (!is_array($trait)) {
            continue;
        }

        if (
            array_key_exists(
                'active',
                $trait
            ) &&
            !$trait['active']
        ) {
            continue;
        }

        /*
         * Legacy safety: if an unmigrated V49-V54 system Trait is encountered,
         * do not allow it to override the canonical V55 definition.
         */
        if (!empty($trait['system'])) {
            continue;
        }

        $traitId =
            trim(
                (string)(
                    $trait['id']
                    ?? ''
                )
            );

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

        $trait['_runtime_id'] =
            $traitId;

        $definitions[$traitId] =
            $trait;
    }

    return $definitions;
}


function wayfarerEntitySystemConfigValue(
    array $config,
    string $key,
    $default = null
) {
    $system =
        isset($config['system']) &&
        is_array($config['system'])
            ? $config['system']
            : [];

    return array_key_exists($key, $system)
        ? $system[$key]
        : $default;
}


function wayfarerEntitySystemTraitId(
    array $definitions,
    string $systemKey
): ?string {
    foreach (
        $definitions
        as $traitId => $definition
    ) {
        if (
            !is_array($definition) ||
            empty($definition['system'])
        ) {
            continue;
        }

        if (
            (string)(
                $definition['system_key']
                ?? ''
            ) === $systemKey
        ) {
            return (string)$traitId;
        }
    }

    return null;
}


function wayfarerEntityTraitShownOn(
    array $definition,
    string $surface
): bool {
    if (!empty($definition['system'])) {
        return false;
    }

    $surfaces =
        $definition['display']['surfaces']
        ?? [];

    return
        is_array($surfaces) &&
        in_array(
            $surface,
            $surfaces,
            true
        );
}


function wayfarerEntityDisplayValue($value): string
{
    if (is_bool($value)) {
        return $value
            ? 'Yes'
            : 'No';
    }

    if ($value === null) {
        return '—';
    }

    if (is_array($value)) {
        $json =
            json_encode(
                $value,
                JSON_UNESCAPED_SLASHES |
                JSON_UNESCAPED_UNICODE
            );

        return $json === false
            ? '—'
            : $json;
    }

    return (string)$value;
}


function wayfarerRuntimeLoadActiveEntities(
    PDO $pdo,
    int $gameId
): array {
    if ($gameId <= 0) {
        return [];
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                name,
                description,
                entity_type,
                status,
                config
            FROM wf_entities
            WHERE game_id = ?
              AND status = 'active'
            ORDER BY name, id
            "
        );

    $stmt->execute([
        $gameId
    ]);

    $rows =
        $stmt->fetchAll(
            PDO::FETCH_ASSOC
        );

    return is_array($rows)
        ? $rows
        : [];
}


/*
 * Additive/recovery-safe Entity initialization.
 *
 * Returns true only when runtime state was changed.
 */
function wayfarerRuntimeEnsureEntityState(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): bool {
    if ($gameId <= 0) {
        return false;
    }

    $changed =
        false;

    if (
        !isset($runtimeState['entities']) ||
        !is_array(
            $runtimeState['entities']
        )
    ) {
        $runtimeState['entities'] =
            [];

        $changed =
            true;
    }

    foreach (
        wayfarerRuntimeLoadActiveEntities(
            $pdo,
            $gameId
        )
        as $entity
    ) {
        $entityId =
            (int)(
                $entity['id']
                ?? 0
            );

        if ($entityId <= 0) {
            continue;
        }

        $entityKey =
            (string)$entityId;

        $config =
            wayfarerEntityDecodeConfig(
                $entity['config']
                ?? null
            );

        $entityType =
            strtolower(
                trim(
                    (string)(
                        $entity['entity_type']
                        ?? ''
                    )
                )
            );

        $definitions =
            wayfarerEntityActiveTraitDefinitions(
                $config,
                $entityType
            );

        if (
            !isset(
                $runtimeState['entities'][$entityKey]
            ) ||
            !is_array(
                $runtimeState['entities'][$entityKey]
            )
        ) {
            $runtimeState['entities'][$entityKey] =
                [];

            $changed =
                true;
        }

        if (
            !isset(
                $runtimeState['entities'][$entityKey]['traits']
            ) ||
            !is_array(
                $runtimeState['entities'][$entityKey]['traits']
            )
        ) {
            $runtimeState['entities'][$entityKey]['traits'] =
                [];

            $changed =
                true;
        }

        foreach (
            $definitions
            as $traitId => $definition
        ) {
            if (
                array_key_exists(
                    $traitId,
                    $runtimeState['entities'][$entityKey]['traits']
                )
            ) {
                continue;
            }

            /*
             * Reuse Wayfarer's canonical initial-value semantics.
             */
            $runtimeState['entities'][$entityKey]['traits'][$traitId] =
                wayfarerRuntimeInitialTraitValue(
                    $definition
                );

            $changed =
                true;
        }

        if (
            strtolower(
                trim(
                    (string)(
                        $entity['entity_type']
                        ?? ''
                    )
                )
            ) !== 'item'
        ) {
            continue;
        }

        $quantityTraitId =
            wayfarerEntitySystemTraitId(
                $definitions,
                'quantity'
            );

        $quantity =
            $quantityTraitId !== null
                ? (
                    $runtimeState['entities'][$entityKey]['traits']
                        [$quantityTraitId]
                    ?? 0
                )
                : 0;

        /*
         * Discovery is persistent. Possessing the Item at any recovery point
         * discovers it; returning to zero later never clears discovery.
         */
        if (
            !array_key_exists(
                'discovered',
                $runtimeState['entities'][$entityKey]
            )
        ) {
            $runtimeState['entities'][$entityKey]['discovered'] =
                is_numeric($quantity) &&
                (float)$quantity > 0;

            $changed =
                true;

        } elseif (
            !$runtimeState['entities'][$entityKey]['discovered'] &&
            is_numeric($quantity) &&
            (float)$quantity > 0
        ) {
            $runtimeState['entities'][$entityKey]['discovered'] =
                true;

            $changed =
                true;
        }
    }

    return $changed;
}


/*
 * Resolve the player-facing Inventory and Status models.
 *
 * Presentation metadata never changes whether a Trait exists in runtime.
 */
/*
 * WAYFARER_ENTITY_DETAIL_VIEW_V50
 *
 * Authored media links use the underlying table name as object_type.
 * Entity images therefore use object_type = wf_entities.
 */
function wayfarerEntityImageUrl(
    PDO $pdo,
    int $gameId,
    int $entityId
): string {
    if (
        $gameId <= 0 ||
        $entityId <= 0
    ) {
        return '';
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT
                m.relative_path
            FROM wf_media_links ml
            INNER JOIN wf_media m
                ON m.id = ml.media_id
            WHERE ml.object_type = 'wf_entities'
              AND ml.object_id = ?
              AND ml.slot = 'image'
              AND m.game_id = ?
              AND m.media_type = 'image'
            LIMIT 1
            "
        );

    $stmt->execute([
        $entityId,
        $gameId,
    ]);

    $relativePath =
        $stmt->fetchColumn();

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

    $relativePath =
        ltrim(
            str_replace(
                '\\',
                '/',
                (string)$relativePath
            ),
            '/'
        );

    /*
     * Media uploads live beneath the Wayfarer root. play/ is one level below.
     * Reject traversal rather than attempting to normalize it.
     */
    if (
        $relativePath === '' ||
        strpos(
            $relativePath,
            '..'
        ) !== false
    ) {
        return '';
    }

    return '../' .
        $relativePath;
}


/*
 * WAYFARER_STATUS_TRAIT_DISPLAY_V86
 *
 * Builds presentation metadata for a Trait shown on the Status screen.
 * Existing Traits default to Number/Value. Bar modes require a bounded
 * numeric Trait; malformed/legacy metadata fails safely back to Number.
 */
function wayfarerRuntimeStatusTraitPresentation(
    array $definition,
    $value
): array {
    $mode =
        strtolower(
            trim(
                (string)(
                    $definition['display']['status_mode']
                    ?? 'number'
                )
            )
        );

    if (
        !in_array(
            $mode,
            ['number', 'bar', 'both'],
            true
        )
    ) {
        $mode =
            'number';
    }

    $type =
        strtolower(
            trim(
                (string)(
                    $definition['type']
                    ?? ''
                )
            )
        );

    if ($type === 'binary') {
        $type =
            'boolean';
    }

    $minimum =
        $definition['min']
        ?? null;

    $maximum =
        $definition['max']
        ?? null;

    $barAvailable =
        $type === 'number' &&
        is_numeric($value) &&
        is_numeric($minimum) &&
        is_numeric($maximum) &&
        (float)$maximum > (float)$minimum;

    $barPercent =
        null;

    if ($barAvailable) {
        $barPercent =
            (
                (
                    (float)$value -
                    (float)$minimum
                ) /
                (
                    (float)$maximum -
                    (float)$minimum
                )
            ) *
            100;

        $barPercent =
            max(
                0,
                min(
                    100,
                    $barPercent
                )
            );
    } elseif (
        $mode === 'bar' ||
        $mode === 'both'
    ) {
        $mode =
            'number';
    }

    return [
        'value' =>
            wayfarerEntityDisplayValue(
                $value
            ),
        'display_mode' =>
            $mode,
        'bar_available' =>
            $barAvailable,
        'bar_percent' =>
            $barPercent,
        'bar_min' =>
            $barAvailable
                ? (float)$minimum
                : null,
        'bar_max' =>
            $barAvailable
                ? (float)$maximum
                : null,
        'bar_value' =>
            $barAvailable
                ? (float)$value
                : null,
    ];
}


function wayfarerRuntimeBuildEntityPresentation(
    PDO $pdo,
    int $gameId,
    array $runtimeState,
    array $gameConfig = []
): array {
    $result = [
        'inventory' => [],
        'party' => [],
    ];

    /*
     * WAYFARER_PLAYER_TRAITS_RUNTIME_V52
     * Game and built-in Player presentation now lives in player-state.php.
     * This resolver owns only Item Inventory and joined Character Entities.
     */

    foreach (
        wayfarerRuntimeLoadActiveEntities(
            $pdo,
            $gameId
        )
        as $entity
    ) {
        $entityId =
            (int)(
                $entity['id']
                ?? 0
            );

        if ($entityId <= 0) {
            continue;
        }

        $entityKey =
            (string)$entityId;

        $entityState =
            $runtimeState['entities'][$entityKey]
            ?? [];

        $traitState =
            is_array(
                $entityState['traits']
                ?? null
            )
                ? $entityState['traits']
                : [];

        $config =
            wayfarerEntityDecodeConfig(
                $entity['config']
                ?? null
            );

        $entityType =
            strtolower(
                trim(
                    (string)(
                        $entity['entity_type']
                        ?? ''
                    )
                )
            );

        $definitions =
            wayfarerEntityActiveTraitDefinitions(
                $config,
                $entityType
            );

        /*
         * --------------------------------------------------------------
         * INVENTORY
         * --------------------------------------------------------------
         */
        if ($entityType === 'item') {

            $quantityTraitId =
                wayfarerEntitySystemTraitId(
                    $definitions,
                    'quantity'
                );

            $quantity =
                $quantityTraitId !== null
                    ? (
                        $traitState[$quantityTraitId]
                        ?? 0
                    )
                    : 0;

            /*
             * WAYFARER_ENTITY_SYSTEM_CONFIG_V55
             * Inventory visibility is authored presentation configuration,
             * not mutable playthrough state.
             */
            $visibility =
                (string)
                wayfarerEntitySystemConfigValue(
                    $config,
                    'inventory_visibility',
                    'while_possessed'
                );

            $discovered =
                !empty(
                    $entityState['discovered']
                );

            $show =
                false;

            switch ($visibility) {

                case 'always':
                    $show =
                        true;
                    break;

                case 'never':
                    $show =
                        false;
                    break;

                case 'once_discovered':
                    $show =
                        $discovered;
                    break;

                case 'while_possessed':
                default:
                    $show =
                        is_numeric($quantity) &&
                        (float)$quantity > 0;
                    break;
            }

            if (!$show) {
                continue;
            }

            $visibleTraits = [];

            foreach (
                $definitions
                as $traitId => $definition
            ) {
                if (
                    !wayfarerEntityTraitShownOn(
                        $definition,
                        'inventory'
                    ) ||
                    !array_key_exists(
                        $traitId,
                        $traitState
                    )
                ) {
                    continue;
                }

                $visibleTraits[] = [
                    'id' =>
                        $traitId,

                    'name' =>
                        (string)(
                            $definition['name']
                            ?? $traitId
                        ),

                    'value' =>
                        wayfarerEntityDisplayValue(
                            $traitState[$traitId]
                        ),
                ];
            }

            $result['inventory'][] = [
                'id' =>
                    $entityId,

                'name' =>
                    (string)(
                        $entity['name']
                        ?? 'Item'
                    ),

                'description' =>
                    trim(
                        (string)(
                            $entity['description']
                            ?? ''
                        )
                    ),

                'image_url' =>
                    wayfarerEntityImageUrl(
                        $pdo,
                        $gameId,
                        $entityId
                    ),

                'quantity' =>
                    wayfarerEntityDisplayValue(
                        $quantity
                    ),

                'traits' =>
                    $visibleTraits,
            ];

            continue;
        }


        /*
         * --------------------------------------------------------------
         * STATUS / PARTY
         * --------------------------------------------------------------
         */
        if ($entityType === 'character') {

            $partyTraitId =
                wayfarerEntitySystemTraitId(
                    $definitions,
                    'party_member'
                );

            $inParty =
                $partyTraitId !== null &&
                !empty(
                    $traitState[$partyTraitId]
                );

            if (!$inParty) {
                continue;
            }

            $visibleTraits = [];

            foreach (
                $definitions
                as $traitId => $definition
            ) {
                if (
                    !wayfarerEntityTraitShownOn(
                        $definition,
                        'status'
                    ) ||
                    !array_key_exists(
                        $traitId,
                        $traitState
                    )
                ) {
                    continue;
                }

                $traitPresentation =
                    wayfarerRuntimeStatusTraitPresentation(
                        $definition,
                        $traitState[$traitId]
                    );

                $visibleTraits[] =
                    array_merge(
                        [
                            'id' =>
                                $traitId,

                            'name' =>
                                (string)(
                                    $definition['name']
                                    ?? $traitId
                                ),
                        ],
                        $traitPresentation
                    );
            }

            $result['party'][] = [
                'id' =>
                    $entityId,

                'name' =>
                    (string)(
                        $entity['name']
                        ?? 'Character'
                    ),

                'description' =>
                    trim(
                        (string)(
                            $entity['description']
                            ?? ''
                        )
                    ),

                'image_url' =>
                    wayfarerEntityImageUrl(
                        $pdo,
                        $gameId,
                        $entityId
                    ),

                'traits' =>
                    $visibleTraits,
            ];
        }
    }

    return $result;
}


==============================================================================
FILE: play/includes/hud.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Persistent Player HUD
 * WAYFARER_PLAYER_HUD_V64
 * --------------------------------------------------------------------------
 *
 * The current Region decides which state values are exposed here.
 * V64 renders progress_bar components backed by bounded Number Traits.
 */

if (
    !isset($state) ||
    !is_array($state) ||
    !isset($pdo) ||
    !($pdo instanceof PDO)
) {
    return;
}

$hudRegionId =
    (int)(
        $state['navigation']['region_id']
        ?? 0
    );

if ($hudRegionId <= 0) {
    return;
}

$hudRegionStmt =
    $pdo->prepare(
        "
        SELECT
            config
        FROM wf_regions
        WHERE id = ?
          AND game_id = ?
        LIMIT 1
        "
    );

$hudRegionStmt->execute([
    $hudRegionId,
    (int)$gameId,
]);

$hudRegionRaw =
    $hudRegionStmt->fetchColumn();

$hudRegionConfig =
    $hudRegionRaw
        ? json_decode(
            (string)$hudRegionRaw,
            true
        )
        : [];

if (!is_array($hudRegionConfig)) {
    $hudRegionConfig = [];
}

$hudConfig =
    isset($hudRegionConfig['hud']) &&
    is_array($hudRegionConfig['hud'])
        ? $hudRegionConfig['hud']
        : [];

if (empty($hudConfig['enabled'])) {
    return;
}

$hudComponents =
    isset($hudConfig['components']) &&
    is_array($hudConfig['components'])
        ? array_values(
            $hudConfig['components']
        )
        : [];

if (!$hudComponents) {
    return;
}


/*
 * Definition catalogs supply labels/min/max while runtime state supplies values.
 */
$hudGameDefinitions = [];

foreach (
    (
        isset($gameConfig['traits']) &&
        is_array($gameConfig['traits'])
            ? $gameConfig['traits']
            : []
    )
    as $trait
) {
    if (
        is_array($trait) &&
        !empty($trait['id'])
    ) {
        $hudGameDefinitions[
            (string)$trait['id']
        ] = $trait;
    }
}

$hudRegionDefinitions = [];

foreach (
    (
        isset($hudRegionConfig['traits']) &&
        is_array($hudRegionConfig['traits'])
            ? $hudRegionConfig['traits']
            : []
    )
    as $trait
) {
    if (
        is_array($trait) &&
        !empty($trait['id'])
    ) {
        $hudRegionDefinitions[
            (string)$trait['id']
        ] = $trait;
    }
}


$hudRendered = [];

foreach ($hudComponents as $component) {

    if (!is_array($component)) {
        continue;
    }

    $type =
        strtolower(
            trim(
                (string)(
                    $component['type']
                    ?? ''
                )
            )
        );

    if ($type !== 'progress_bar') {
        continue;
    }

    $scope =
        strtolower(
            trim(
                (string)(
                    $component['source_scope']
                    ?? ''
                )
            )
        );

    $sourceId =
        trim(
            (string)(
                $component['source_id']
                ?? ''
            )
        );

    if (
        !in_array(
            $scope,
            ['game', 'region'],
            true
        ) ||
        $sourceId === ''
    ) {
        continue;
    }

    $definition =
        $scope === 'game'
            ? (
                $hudGameDefinitions[
                    $sourceId
                ]
                ?? null
            )
            : (
                $hudRegionDefinitions[
                    $sourceId
                ]
                ?? null
            );

    if (
        !is_array($definition) ||
        strtolower(
            trim(
                (string)(
                    $definition['type']
                    ?? ''
                )
            )
        ) !== 'number' ||
        !is_numeric(
            $definition['min']
            ?? null
        ) ||
        !is_numeric(
            $definition['max']
            ?? null
        )
    ) {
        continue;
    }

    $min =
        (float)$definition['min'];

    $max =
        (float)$definition['max'];

    if ($max <= $min) {
        continue;
    }

    if ($scope === 'game') {

        $runtimeTraits =
            isset($state['game']['traits']) &&
            is_array(
                $state['game']['traits']
            )
                ? $state['game']['traits']
                : [];

    } else {

        $runtimeTraits =
            isset(
                $state['regions'][
                    (string)$hudRegionId
                ]['traits']
            ) &&
            is_array(
                $state['regions'][
                    (string)$hudRegionId
                ]['traits']
            )
                ? $state['regions'][
                    (string)$hudRegionId
                ]['traits']
                : [];
    }

    $value =
        $runtimeTraits[
            $sourceId
        ]
        ?? (
            $definition['initial']
            ?? $min
        );

    if (!is_numeric($value)) {
        continue;
    }

    $value =
        (float)$value;

    $percent =
        (($value - $min) /
        ($max - $min)) *
        100;

    $percent =
        max(
            0,
            min(
                100,
                $percent
            )
        );

    $label =
        trim(
            (string)(
                $component['label']
                ?? ''
            )
        );

    if ($label === '') {
        $label =
            trim(
                (string)(
                    $definition['name']
                    ?? $sourceId
                )
            );
    }

    $hudRendered[] = [
        'id' =>
            (string)(
                $component['id']
                ?? ''
            ),

        'scope' =>
            $scope,

        'source_id' =>
            $sourceId,

        'label' =>
            $label !== ''
                ? $label
                : $sourceId,

        'min' =>
            $min,

        'max' =>
            $max,

        'value' =>
            $value,

        'percent' =>
            $percent,

        'show_value' =>
            !empty(
                $component['show_value']
            ),
    ];
}

if (!$hudRendered) {
    return;
}


$hudPresentationActive =
    !empty(
        $state['runtime']['presentation']
    );

$hudEndingActive =
    !empty(
        $state['runtime']['ending']
    );

?>
<section
    class="wayfarer-player-hud"
    data-wayfarer-hud
    aria-label="Status"
    <?= (
        $hudPresentationActive ||
        $hudEndingActive
    )
        ? 'hidden'
        : '' ?>
>
    <div class="wayfarer-hud-components">

        <?php foreach (
            $hudRendered
            as $component
        ): ?>

            <div
                class="wayfarer-hud-component wayfarer-hud-progress-component"
                data-wayfarer-hud-component
                data-wayfarer-hud-type="progress_bar"
                data-wayfarer-hud-scope="<?= htmlspecialchars(
                    $component['scope']
                ) ?>"
                data-wayfarer-hud-source-id="<?= htmlspecialchars(
                    $component['source_id']
                ) ?>"
                data-wayfarer-hud-region-id="<?= (int)$hudRegionId ?>"
                data-wayfarer-hud-min="<?= htmlspecialchars(
                    (string)$component['min']
                ) ?>"
                data-wayfarer-hud-max="<?= htmlspecialchars(
                    (string)$component['max']
                ) ?>"
            >
                <div class="wayfarer-hud-progress-heading">
                    <span class="wayfarer-hud-label">
                        <?= htmlspecialchars(
                            $component['label']
                        ) ?>
                    </span>

                    <?php if (
                        $component['show_value']
                    ): ?>

                        <span
                            class="wayfarer-hud-value"
                            data-wayfarer-hud-value
                        >
                            <?= htmlspecialchars(
                                (string)$component['value']
                            ) ?>
                        </span>

                    <?php endif; ?>
                </div>

                <div
                    class="wayfarer-hud-progress-track"
                    role="progressbar"
                    aria-label="<?= htmlspecialchars(
                        $component['label']
                    ) ?>"
                    aria-valuemin="<?= htmlspecialchars(
                        (string)$component['min']
                    ) ?>"
                    aria-valuemax="<?= htmlspecialchars(
                        (string)$component['max']
                    ) ?>"
                    aria-valuenow="<?= htmlspecialchars(
                        (string)$component['value']
                    ) ?>"
                    data-wayfarer-hud-meter
                >
                    <div
                        class="wayfarer-hud-progress-fill"
                        data-wayfarer-hud-fill
                        style="width:<?= htmlspecialchars(
                            number_format(
                                $component['percent'],
                                4,
                                '.',
                                ''
                            )
                        ) ?>%;"
                    ></div>
                </div>
            </div>

        <?php endforeach; ?>

    </div>
</section>


==============================================================================
FILE: play/includes/player-state.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Player Character runtime state
 * WAYFARER_PLAYER_TRAITS_RUNTIME_V52
 * --------------------------------------------------------------------------
 *
 * Player Traits are authored once at Game level in config.player_traits.
 * Each named player slot receives an independent runtime value for each Trait.
 *
 * Game Traits remain one shared value for the whole playthrough.
 * Character Entity Traits remain one value per authored Character Entity.
 */

function wayfarerPlayerTraitDefinitions(
    array $gameConfig
): array {
    return
        wayfarerRuntimeActiveTraitDefinitions([
            'traits' =>
                is_array(
                    $gameConfig['player_traits']
                    ?? null
                )
                    ? $gameConfig['player_traits']
                    : [],
        ]);
}


function wayfarerPlayerTraitShownOn(
    array $definition,
    string $surface
): bool {
    $surfaces =
        $definition['display']['surfaces']
        ?? [];

    return
        is_array($surfaces) &&
        in_array(
            $surface,
            $surfaces,
            true
        );
}


function wayfarerPlayerDisplayValue($value): string
{
    if (is_bool($value)) {
        return $value ? 'Yes' : 'No';
    }

    if ($value === null) {
        return '—';
    }

    if (is_array($value)) {
        $json = json_encode(
            $value,
            JSON_UNESCAPED_SLASHES |
            JSON_UNESCAPED_UNICODE
        );

        return $json === false
            ? '—'
            : $json;
    }

    return (string)$value;
}


/*
 * Add newly-authored Game Traits to an existing playthrough without changing
 * any current values. This also fixes the development case where a Game Trait
 * is added after the playthrough was initialized.
 */
function wayfarerRuntimeEnsureGameTraitState(
    array $gameConfig,
    array &$runtimeState
): bool {
    $changed = false;

    if (
        !isset($runtimeState['game']) ||
        !is_array($runtimeState['game'])
    ) {
        $runtimeState['game'] = [];
        $changed = true;
    }

    if (
        !isset($runtimeState['game']['traits']) ||
        !is_array($runtimeState['game']['traits'])
    ) {
        $runtimeState['game']['traits'] = [];
        $changed = true;
    }

    foreach (
        wayfarerRuntimeActiveTraitDefinitions(
            $gameConfig
        )
        as $definition
    ) {
        $traitId =
            (string)(
                $definition['_runtime_id']
                ?? ''
            );

        if ($traitId === '') {
            continue;
        }
        if (
            array_key_exists(
                $traitId,
                $runtimeState['game']['traits']
            )
        ) {
            continue;
        }

        $runtimeState['game']['traits'][$traitId] =
            wayfarerRuntimeInitialTraitValue(
                $definition
            );

        $changed = true;
    }

    return $changed;
}


/*
 * Additive Player-state initializer / recovery path.
 *
 * The saved setup.player_names collection is canonical for which built-in
 * player characters belong to this playthrough. Changing the authored slot
 * count later therefore does not invent unnamed people or delete saved people.
 */
function wayfarerRuntimeEnsurePlayerState(
    array $gameConfig,
    int $playerSlots,
    array &$runtimeState
): bool {
    $changed = false;

    if (
        !isset($runtimeState['players']) ||
        !is_array($runtimeState['players'])
    ) {
        $runtimeState['players'] = [];
        $changed = true;
    }

    $storedNames =
        $runtimeState['setup']['player_names']
        ?? [];

    if (!is_array($storedNames)) {
        $storedNames = [];
    }

    $names = [];

    foreach ($storedNames as $storedName) {
        $storedName = trim((string)$storedName);
        if ($storedName !== '') {
            $names[] = $storedName;
        }
    }

    /*
     * New games validate one name per configured slot before this function is
     * called. For older playthroughs, saved names win over a later authoring
     * change to player_slots.
     */
    $definitions =
        wayfarerPlayerTraitDefinitions(
            $gameConfig
        );

    foreach ($names as $slot => $name) {
        $key = (string)$slot;

        if (
            !isset($runtimeState['players'][$key]) ||
            !is_array($runtimeState['players'][$key])
        ) {
            $runtimeState['players'][$key] = [];
            $changed = true;
        }

        if (
            (int)(
                $runtimeState['players'][$key]['slot']
                ?? -1
            ) !== $slot
        ) {
            $runtimeState['players'][$key]['slot'] = $slot;
            $changed = true;
        }

        if (
            (string)(
                $runtimeState['players'][$key]['name']
                ?? ''
            ) !== $name
        ) {
            $runtimeState['players'][$key]['name'] = $name;
            $changed = true;
        }

        if (
            !isset($runtimeState['players'][$key]['traits']) ||
            !is_array($runtimeState['players'][$key]['traits'])
        ) {
            $runtimeState['players'][$key]['traits'] = [];
            $changed = true;
        }

        foreach ($definitions as $definition) {
            $traitId =
                (string)(
                    $definition['_runtime_id']
                    ?? ''
                );

            if ($traitId === '') {
                continue;
            }
            if (
                array_key_exists(
                    $traitId,
                    $runtimeState['players'][$key]['traits']
                )
            ) {
                continue;
            }

            $runtimeState['players'][$key]['traits'][$traitId] =
                wayfarerRuntimeInitialTraitValue(
                    $definition
                );

            $changed = true;
        }
    }

    return $changed;
}


/*
 * Convenience recovery used by the play page and tick API.
 */
function wayfarerRuntimeEnsurePlayerAndGameState(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): bool {
    if ($gameId <= 0) {
        return false;
    }

    $stmt = $pdo->prepare(
        "
        SELECT
            config,
            player_slots
        FROM wf_games
        WHERE id = ?
        LIMIT 1
        "
    );

    $stmt->execute([
        $gameId
    ]);

    $game = $stmt->fetch(PDO::FETCH_ASSOC);

    if (!$game) {
        return false;
    }

    $gameConfig =
        wayfarerRuntimeDecodeConfig(
            $game['config']
            ?? null
        );

    $changed =
        wayfarerRuntimeEnsureGameTraitState(
            $gameConfig,
            $runtimeState
        );

    if (
        wayfarerRuntimeEnsurePlayerState(
            $gameConfig,
            (int)(
                $game['player_slots']
                ?? 0
            ),
            $runtimeState
        )
    ) {
        $changed = true;
    }

    return $changed;
}


function wayfarerRuntimeBuildPlayerPresentation(
    array $gameConfig,
    array $runtimeState
): array {
    $result = [
        'players' => [],
        'game_status_traits' => [],
    ];

    /* Shared Game Traits. */
    foreach (
        wayfarerRuntimeActiveTraitDefinitions(
            $gameConfig
        )
        as $definition
    ) {
        $traitId =
            (string)(
                $definition['_runtime_id']
                ?? ''
            );

        if ($traitId === '') {
            continue;
        }
        if (
            !wayfarerPlayerTraitShownOn(
                $definition,
                'status'
            ) ||
            !array_key_exists(
                $traitId,
                $runtimeState['game']['traits']
                ?? []
            )
        ) {
            continue;
        }

        /* WAYFARER_STATUS_TRAIT_DISPLAY_V86 */
        $traitPresentation =
            wayfarerRuntimeStatusTraitPresentation(
                $definition,
                $runtimeState['game']['traits'][$traitId]
            );

        $result['game_status_traits'][] =
            array_merge(
                [
                    'id' => $traitId,
                    'name' => (string)(
                        $definition['name']
                        ?? $traitId
                    ),
                ],
                $traitPresentation
            );
    }

    $playerDefinitions =
        wayfarerPlayerTraitDefinitions(
            $gameConfig
        );

    $players =
        is_array($runtimeState['players'] ?? null)
            ? $runtimeState['players']
            : [];

    uasort(
        $players,
        function ($a, $b) {
            return (int)($a['slot'] ?? 0) <=> (int)($b['slot'] ?? 0);
        }
    );

    foreach ($players as $key => $player) {
        if (!is_array($player)) {
            continue;
        }

        $name = trim(
            (string)(
                $player['name']
                ?? ''
            )
        );

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

        $traitState =
            is_array($player['traits'] ?? null)
                ? $player['traits']
                : [];

        $visibleTraits = [];

        foreach ($playerDefinitions as $definition) {
            $traitId =
                (string)(
                    $definition['_runtime_id']
                    ?? ''
                );

            if ($traitId === '') {
                continue;
            }
            if (
                !wayfarerPlayerTraitShownOn(
                    $definition,
                    'status'
                ) ||
                !array_key_exists(
                    $traitId,
                    $traitState
                )
            ) {
                continue;
            }

            $traitPresentation =
                wayfarerRuntimeStatusTraitPresentation(
                    $definition,
                    $traitState[$traitId]
                );

            $visibleTraits[] =
                array_merge(
                    [
                        'id' => $traitId,
                        'name' => (string)(
                            $definition['name']
                            ?? $traitId
                        ),
                    ],
                    $traitPresentation
                );
        }

        $result['players'][] = [
            'slot' => (int)($player['slot'] ?? $key),
            'name' => $name,
            'traits' => $visibleTraits,
        ];
    }

    return $result;
}


==============================================================================
FILE: play/includes/presentation-screen.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Player Presentation Screen
 * WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40
 * --------------------------------------------------------------------------
 *
 * v40 renders Location presentations. The runtime state is deliberately
 * generic so automatic Storylets can use this shell later.
 */

$presentation =
    $state['runtime']['presentation']
    ?? null;

if (
    !is_array($presentation) ||
    empty($presentation['type']) ||
    empty($presentation['id'])
) {
    return;
}


$presentationType =
    (string)$presentation['type'];

$presentationId =
    (int)$presentation['id'];

$presentationRecord =
    null;

$presentationImage =
    null;

$presentationBranches =
    [];

/* WAYFARER_PRESENTATION_EFFECT_FEEDBACK_V70 */
$presentationChanges = [];

$presentationFeedbackPackage = null;
$presentationFeedbackIdKey = '';

if ($presentationType === 'location') {
    $presentationFeedbackPackage =
        $state['runtime']['last_location_effects']
        ?? null;
    $presentationFeedbackIdKey =
        'location_id';
} elseif ($presentationType === 'storylet') {
    $presentationFeedbackPackage =
        $state['runtime']['last_storylet_effects']
        ?? null;
    $presentationFeedbackIdKey =
        'storylet_id';
}

if (
    is_array($presentationFeedbackPackage) &&
    $presentationFeedbackIdKey !== '' &&
    (int)(
        $presentationFeedbackPackage[
            $presentationFeedbackIdKey
        ]
        ?? 0
    ) === $presentationId &&
    (int)(
        $presentationFeedbackPackage['tick']
        ?? -1
    ) === (int)(
        $presentation['tick']
        ?? -2
    ) &&
    isset($presentationFeedbackPackage['changes']) &&
    is_array($presentationFeedbackPackage['changes'])
) {
    foreach (
        $presentationFeedbackPackage['changes']
        as $change
    ) {
        if (
            !is_array($change) ||
            trim((string)($change['text'] ?? '')) === ''
        ) {
            continue;
        }

        $presentationChanges[] =
            $change;
    }
}


/*
 * ---------------------------------------------------------------
 * LOCATION
 * ---------------------------------------------------------------
 */
if (
    $presentationType ===
    'location'
) {

    $stmt =
        $pdo->prepare(
            "
            SELECT
                l.*,
                r.game_id,
                r.name AS region_name
            FROM wf_locations l
            INNER JOIN wf_regions r
                ON r.id = l.region_id
            WHERE l.id = ?
              AND r.game_id = ?
            LIMIT 1
            "
        );

    $stmt->execute([
        $presentationId,
        (int)$gameId,
    ]);

    $presentationRecord =
        $stmt->fetch(
            PDO::FETCH_ASSOC
        );


    if ($presentationRecord) {

        /*
         * Media links use the authored table name as object_type.
         */
        $mediaStmt =
            $pdo->prepare(
                "
                SELECT
                    m.id,
                    m.name,
                    m.relative_path,
                    m.mime_type
                FROM wf_media_links ml
                INNER JOIN wf_media m
                    ON m.id = ml.media_id
                WHERE ml.object_type = 'wf_locations'
                  AND ml.object_id = ?
                  AND ml.slot = 'image'
                  AND m.game_id = ?
                  AND m.media_type = 'image'
                LIMIT 1
                "
            );

        $mediaStmt->execute([
            $presentationId,
            (int)$gameId,
        ]);

        $presentationImage =
            $mediaStmt->fetch(
                PDO::FETCH_ASSOC
            );
    }
}

/*
 * ---------------------------------------------------------------
 * STORYLET
 * WAYFARER_STORYLET_PRESENTATION_V59
 * ---------------------------------------------------------------
 */
if (
    $presentationType ===
    'storylet'
) {
    $presentationRecord =
        wayfarerRuntimeLoadStorylet(
            $pdo,
            (int)$gameId,
            $presentationId
        );

    if ($presentationRecord) {
        $mediaStmt =
            $pdo->prepare(
                "
                SELECT
                    m.id,
                    m.name,
                    m.relative_path,
                    m.mime_type
                FROM wf_media_links ml
                INNER JOIN wf_media m
                    ON m.id = ml.media_id
                WHERE ml.object_type = 'wf_storylets'
                  AND ml.object_id = ?
                  AND ml.slot = 'image'
                  AND m.game_id = ?
                  AND m.media_type = 'image'
                LIMIT 1
                "
            );

        $mediaStmt->execute([
            $presentationId,
            (int)$gameId,
        ]);

        $presentationImage =
            $mediaStmt->fetch(
                PDO::FETCH_ASSOC
            );

        /*
         * Conditions are evaluated AFTER the current Storylet's Effects have
         * executed, because entry persisted the mutated state first.
         */
        $presentationBranches =
            wayfarerRuntimeEligibleStoryletBranches(
                $pdo,
                (int)$gameId,
                $presentationId,
                $state
            );
    }
}


if (!$presentationRecord) {

    /*
     * Keep the player from becoming trapped if an authored object is removed
     * after its presentation state was persisted.
     */
    $presentationRecord = [
        'name' =>
            'Continue',

        'description' =>
            'This presentation is no longer available.',
    ];
}


$presentationName =
    trim(
        (string)(
            $presentationRecord['name']
            ?? ''
        )
    );

if ($presentationName === '') {
    $presentationName =
        $presentationType === 'storylet'
            ? 'Storylet'
            : 'Location';
}


$presentationDescription =
    trim(
        (string)(
            $presentationRecord['description']
            ?? ''
        )
    );

/* WAYFARER_STORYLET_BINDING_RUNTIME_V79 */
if (
    $presentationType === 'storylet' &&
    isset($presentation['bindings']) &&
    is_array($presentation['bindings'])
) {
    $presentationName =
        wayfarerRuntimeInterpolateStoryletBindings(
            $presentationName,
            $presentation['bindings']
        );

    $presentationDescription =
        wayfarerRuntimeInterpolateStoryletBindings(
            $presentationDescription,
            $presentation['bindings']
        );
}


$presentationImageUrl =
    '';

if (
    is_array($presentationImage) &&
    !empty(
        $presentationImage['relative_path']
    )
) {

    $relativePath =
        ltrim(
            str_replace(
                '\\',
                '/',
                (string)$presentationImage[
                    'relative_path'
                ]
            ),
            '/'
        );

    /*
     * Media uploads are stored beneath the Wayfarer root. play/ is one level
     * below that root.
     */
    if (
        $relativePath !== '' &&
        strpos(
            $relativePath,
            '..'
        ) === false
    ) {
        $presentationImageUrl =
            '../' .
            $relativePath;
    }
}

?>
<section
    class="wayfarer-presentation-screen"
    data-wayfarer-presentation-screen
    data-wayfarer-presentation-type="<?= htmlspecialchars(
        $presentationType,
        ENT_QUOTES,
        'UTF-8'
    ) ?>"
    data-wayfarer-presentation-id="<?= $presentationId ?>"
    role="dialog"
    aria-modal="true"
    aria-labelledby="wayfarer-presentation-title"
>
    <div class="wayfarer-presentation-inner">

        <?php if ($presentationImageUrl !== ''): ?>

            <figure class="wayfarer-presentation-media">
                <img
                    src="<?= htmlspecialchars(
                        $presentationImageUrl,
                        ENT_QUOTES,
                        'UTF-8'
                    ) ?>"
                    alt=""
                >
            </figure>

        <?php endif; ?>


        <div class="wayfarer-presentation-copy">

            <?php if (
                $presentationType ===
                'location'
            ): ?>

                <p class="wayfarer-presentation-eyebrow">
                    You've arrived at
                </p>

            <?php endif; ?>


            <h1 id="wayfarer-presentation-title">
                <?= htmlspecialchars(
                    $presentationName
                ) ?>
            </h1>


            <?php if (
                $presentationDescription !==
                ''
            ): ?>

                <div class="wayfarer-presentation-description">
                    <?= nl2br(
                        htmlspecialchars(
                            $presentationDescription
                        )
                    ) ?>
                </div>

            <?php endif; ?>

            <?php if ($presentationChanges): ?>

                <aside
                    class="wayfarer-presentation-changes"
                    aria-label="Changes"
                >
                    <p class="wayfarer-presentation-changes-heading">
                        Changes
                    </p>

                    <ul class="wayfarer-presentation-changes-list">
                        <?php foreach ($presentationChanges as $change): ?>
                            <?php
                            $changeDirection =
                                trim(
                                    (string)(
                                        $change['direction']
                                        ?? ''
                                    )
                                );

                            $changeKind =
                                trim(
                                    (string)(
                                        $change['kind']
                                        ?? ''
                                    )
                                );
                            ?>

                            <li
                                class="wayfarer-presentation-change<?= $changeDirection !== '' ? ' is-' . htmlspecialchars($changeDirection, ENT_QUOTES, 'UTF-8') : '' ?>"
                                data-wayfarer-change-kind="<?= htmlspecialchars($changeKind, ENT_QUOTES, 'UTF-8') ?>"
                                aria-label="<?= htmlspecialchars(
                                    (string)(
                                        $change['aria_text']
                                        ?? $change['text']
                                        ?? ''
                                    ),
                                    ENT_QUOTES,
                                    'UTF-8'
                                ) ?>"
                            >
                                <?= htmlspecialchars(
                                    (string)$change['text'],
                                    ENT_QUOTES,
                                    'UTF-8'
                                ) ?>
                            </li>
                        <?php endforeach; ?>
                    </ul>
                </aside>

            <?php endif; ?>

        </div>


        <div class="wayfarer-presentation-actions<?= (
            $presentationType === 'storylet' &&
            $presentationBranches
        ) ? ' wayfarer-has-storylet-branches' : '' ?>">

            <?php if (
                $presentationType === 'storylet' &&
                $presentationBranches
            ): ?>

                <div
                    class="wayfarer-storylet-branch-list"
                    data-wayfarer-storylet-branches
                >
                    <p class="wayfarer-storylet-branch-prompt">
                        What do you do?
                    </p>

                    <?php foreach (
                        $presentationBranches
                        as $branchIndex => $branch
                    ): ?>
                        <button
                            type="button"
                            class="wayfarer-storylet-branch-button"
                            data-wayfarer-storylet-branch-id="<?= (int)$branch['id'] ?>"
                            data-wayfarer-storylet-parent-id="<?= $presentationId ?>"
                            <?= $branchIndex === 0 ? 'autofocus' : '' ?>
                        >
                            <?= htmlspecialchars(
                                (string)(
                                    $branch['label']
                                    ?? $branch['name']
                                    ?? 'Continue'
                                )
                            ) ?>
                        </button>
                    <?php endforeach; ?>
                </div>

            <?php endif; ?>

            <div>
                <button
                    type="button"
                    class="wayfarer-presentation-continue"
                    data-wayfarer-presentation-continue
                    autofocus
                >
                    Continue
                </button>

                <p class="wayfarer-presentation-key-hint">
                    Enter or Space
                </p>
            </div>

        </div>

    </div>
</section>


==============================================================================
FILE: play/includes/runtime-bootstrap.php
==============================================================================

<?php

/*
 * --------------------------------------------------------------------------
 * Player Runtime Bootstrap
 * WAYFARER_ACTION_SCREEN_V39
 * --------------------------------------------------------------------------
 *
 * Supplies the tick controller to every initialized player, independently of
 * Author Mode.
 */

if (
    !isset($state) ||
    !is_array($state) ||
    !isset($gameUser['game_user_id'])
) {
    return;
}

if (session_status() !== PHP_SESSION_ACTIVE) {
    session_start();
}

if (
    empty($_SESSION['wayfarer_tick_csrf']) ||
    !is_string(
        $_SESSION['wayfarer_tick_csrf']
    )
) {
    $_SESSION['wayfarer_tick_csrf'] =
        bin2hex(
            random_bytes(32)
        );
}

?>
<script>
window.wayfarerTickRuntime = <?= json_encode(
    [
        'gameUserId' =>
            (int)$gameUser['game_user_id'],

        'initialTick' =>
            (int)(
                $state['runtime']['tick']
                ?? 0
            ),

        /* WAYFARER_BIDIRECTIONAL_TRAVEL_BOOTSTRAP_V71 */
        'initialDirection' =>
            (
                (int)(
                    $state['navigation']['direction']
                    ?? 1
                ) < 0
            )
                ? -1
                : 1,

        'csrfToken' =>
            $_SESSION['wayfarer_tick_csrf'],

        'endpoint' =>
            'api/tick.php',

        /*
         * WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40
         */
        'presentationEndpoint' =>
            'api/presentation.php',

        /* WAYFARER_STORYLET_ACTION_RUNTIME_V59 */
        'storyletEndpoint' =>
            'api/storylet.php',

        /* WAYFARER_ENDING_RESTART_V63 */
        'restartEndpoint' =>
            'api/restart.php',

        'intervalMs' =>
            1500,
    ],
    JSON_UNESCAPED_SLASHES |
    JSON_UNESCAPED_UNICODE
) ?>;
</script>


==============================================================================
FILE: play/includes/runtime.php
==============================================================================

<?php

require_once __DIR__ . '/statuses.php'; /* WAYFARER_STATUSES_RUNTIME_V87 */
require_once __DIR__ . '/effects.php';
require_once __DIR__ . '/setup.php';
require_once __DIR__ . '/entity-state.php';
require_once __DIR__ . '/player-state.php';
require_once __DIR__ . '/storylets.php';
/* WAYFARER_STORYLET_ACTION_RUNTIME_V59 */
/* WAYFARER_RUNTIME_STARTING_SETUP_V36 */
/* WAYFARER_ENTITY_RUNTIME_STATE_V49 */
/* WAYFARER_PLAYER_TRAITS_RUNTIME_V52 */

/**
 * Minimal Wayfarer play-runtime helpers.
 *
 * v14 deliberately implements only a persisted tick counter.
 */


/**
 * Decode wf_game_users.state safely.
 */
function wayfarerRuntimeDecodeState($rawState): array
{
    if (is_array($rawState)) {
        return $rawState;
    }

    if ($rawState === null || $rawState === '') {
        return [];
    }

    $decoded = json_decode(
        (string)$rawState,
        true
    );

    return is_array($decoded)
        ? $decoded
        : [];
}


/**
 * Encode runtime state for the JSON column.
 */
function wayfarerRuntimeEncodeState(array $state): string
{
    $json = json_encode(
        $state,
        JSON_UNESCAPED_SLASHES |
        JSON_UNESCAPED_UNICODE
    );

    if ($json === false) {
        throw new RuntimeException(
            'Unable to encode Wayfarer runtime state.'
        );
    }

    return $json;
}


/*
|--------------------------------------------------------------------------
| Canonical Runtime Initialization
|--------------------------------------------------------------------------
|
| WAYFARER_RUNTIME_INITIALIZATION_V31
|
| New-game state is created here rather than piecemeal by the play page.
| Future startup systems (inventory, entities, calendar, etc.) can extend this
| single initializer.
|
*/


function wayfarerRuntimeDecodeConfig(
    $rawConfig
): array {

    if (is_array($rawConfig)) {
        return $rawConfig;
    }

    if (
        $rawConfig === null ||
        $rawConfig === ''
    ) {
        return [];
    }

    $decoded =
        json_decode(
            (string)$rawConfig,
            true
        );

    return is_array($decoded)
        ? $decoded
        : [];
}


/*
|--------------------------------------------------------------------------
| Game clock + Linear travel HUD
| WAYFARER_TRAVEL_TIME_HUD_V61
|--------------------------------------------------------------------------
*/
function wayfarerRuntimeTimeConfig(array $gameConfig): array
{
    $raw = isset($gameConfig['time']) && is_array($gameConfig['time'])
        ? $gameConfig['time']
        : [];

    $mode = strtolower(trim((string)($raw['mode'] ?? 'none')));
    if (!in_array($mode, ['none', 'days', 'hours'], true)) {
        $mode = 'none';
    }

    $config = [
        'mode' => $mode,
        'starting_day' => max(1, (int)($raw['starting_day'] ?? 1)),
        'ticks_per_day' => max(1, (int)($raw['ticks_per_day'] ?? 1)),
        'starting_hour' => max(0, (int)($raw['starting_hour'] ?? 8)),
        'ticks_per_hour' => max(1, (int)($raw['ticks_per_hour'] ?? 1)),
        'hours_per_day' => max(1, (int)($raw['hours_per_day'] ?? 24)),
    ];

    if ($config['starting_hour'] >= $config['hours_per_day']) {
        $config['starting_hour'] = $config['hours_per_day'] - 1;
    }

    return $config;
}

function wayfarerRuntimeInitializeClockFromConfig(
    array $gameConfig,
    array &$runtimeState
): void {
    if (!isset($runtimeState['runtime']) || !is_array($runtimeState['runtime'])) {
        $runtimeState['runtime'] = [];
    }

    $config = wayfarerRuntimeTimeConfig($gameConfig);
    if ($config['mode'] === 'none') {
        unset($runtimeState['runtime']['clock']);
        return;
    }

    $clock = [
        'mode' => $config['mode'],
        'day' => $config['starting_day'],
    ];

    if ($config['mode'] === 'days') {
        $clock['tick_in_day'] = 0;
    } else {
        $clock['hour'] = $config['starting_hour'];
        $clock['tick_in_hour'] = 0;
    }

    $runtimeState['runtime']['clock'] = $clock;
}

function wayfarerRuntimeLoadGameConfig(PDO $pdo, int $gameId): array
{
    if ($gameId <= 0) {
        return [];
    }

    $stmt = $pdo->prepare('SELECT config FROM wf_games WHERE id = ? LIMIT 1');
    $stmt->execute([$gameId]);
    $raw = $stmt->fetchColumn();

    return wayfarerRuntimeDecodeConfig($raw === false ? null : $raw);
}

function wayfarerRuntimeEnsureClock(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): array {
    $gameConfig = wayfarerRuntimeLoadGameConfig($pdo, $gameId);
    $timeConfig = wayfarerRuntimeTimeConfig($gameConfig);
    $clock = $runtimeState['runtime']['clock'] ?? null;

    if ($timeConfig['mode'] === 'none') {
        unset($runtimeState['runtime']['clock']);
        return $timeConfig;
    }

    if (!is_array($clock) || (string)($clock['mode'] ?? '') !== $timeConfig['mode']) {
        wayfarerRuntimeInitializeClockFromConfig($gameConfig, $runtimeState);
    }

    return $timeConfig;
}

function wayfarerRuntimeAdvanceClock(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): void {
    $config = wayfarerRuntimeEnsureClock($pdo, $gameId, $runtimeState);
    if ($config['mode'] === 'none') {
        return;
    }

    $clock =& $runtimeState['runtime']['clock'];
    $clock['day'] = max(1, (int)($clock['day'] ?? $config['starting_day']));

    if ($config['mode'] === 'days') {
        $clock['tick_in_day'] = max(0, (int)($clock['tick_in_day'] ?? 0)) + 1;
        if ($clock['tick_in_day'] >= $config['ticks_per_day']) {
            $clock['day']++;
            $clock['tick_in_day'] = 0;
        }
        return;
    }

    $clock['hour'] = max(0, (int)($clock['hour'] ?? $config['starting_hour']));
    $clock['tick_in_hour'] = max(0, (int)($clock['tick_in_hour'] ?? 0)) + 1;
    if ($clock['tick_in_hour'] >= $config['ticks_per_hour']) {
        $clock['tick_in_hour'] = 0;
        $clock['hour']++;
        if ($clock['hour'] >= $config['hours_per_day']) {
            $clock['hour'] = 0;
            $clock['day']++;
        }
    }
}

function wayfarerRuntimeClockLabel(array $runtimeState, array $timeConfig): string
{
    if ($timeConfig['mode'] === 'none') {
        return '';
    }

    $clock = $runtimeState['runtime']['clock'] ?? [];
    $day = max(1, (int)($clock['day'] ?? $timeConfig['starting_day']));

    if ($timeConfig['mode'] === 'days') {
        return 'Day ' . $day;
    }

    $hour = max(0, (int)($clock['hour'] ?? $timeConfig['starting_hour']));
    if ($timeConfig['hours_per_day'] === 24) {
        $displayHour = $hour % 12;
        if ($displayHour === 0) {
            $displayHour = 12;
        }
        $suffix = $hour < 12 ? 'AM' : 'PM';
        return 'Day ' . $day . ' · ' . $displayHour . ':00 ' . $suffix;
    }

    return 'Day ' . $day . ' · Hour ' . $hour;
}

/*
 * WAYFARER_BIDIRECTIONAL_TRAVEL_V71
 *
 * Runtime direction is journey state, not Region authoring state. +1 follows
 * the Region's authored forward Tick Effect; -1 reverses it. Keeping the
 * authored Add/Subtract sign as the base preserves existing Regions while
 * allowing the same line to be traversed in either direction.
 */
function wayfarerRuntimeNavigationDirection(array $runtimeState): int
{
    $direction =
        (int)(
            $runtimeState['navigation']['direction']
            ?? 1
        );

    return $direction < 0
        ? -1
        : 1;
}

/*
 * WAYFARER_LINEAR_TRAVEL_RUNTIME_V72
 *
 * Returns canonical dedicated travel configuration, or null for Regions that
 * still use the legacy Position Tick Effect movement path.
 */
function wayfarerRuntimeDedicatedLinearTravel(
    array $regionConfig
): ?array {
    $travel =
        isset($regionConfig['travel']) &&
        is_array($regionConfig['travel'])
            ? $regionConfig['travel']
            : null;

    if (
        $travel === null ||
        empty($travel['enabled']) ||
        !isset($travel['base_distance']) ||
        !is_numeric($travel['base_distance']) ||
        (float)$travel['base_distance'] <= 0
    ) {
        return null;
    }

    return [
        'base_distance' =>
            (float)$travel['base_distance'],
        'allow_turnaround' =>
            !empty(
                $travel['allow_turnaround']
            ),
    ];
}

/* WAYFARER_GAME_TRAVEL_MODIFIERS_MOVEMENT_V73 */
function wayfarerRuntimeApplyDedicatedLinearTravelMovement(
    array &$runtimeState,
    array $travel,
    float $modifierAdjustment = 0.0,
    array $matchedModifiers = []
): array {
    if (
        !isset($runtimeState['navigation']) ||
        !is_array($runtimeState['navigation'])
    ) {
        $runtimeState['navigation'] = [];
    }

    $before =
        $runtimeState['navigation']['position']
        ?? 0;

    if (!is_numeric($before)) {
        return [
            'scope' => 'navigation',
            'type' => 'position',
            'target_id' => 'position',
            'applied' => false,
            'error' =>
                'Navigation position must be numeric.',
        ];
    }

    $baseDistance =
        max(
            0.0,
            (float)(
                $travel['base_distance']
                ?? 0
            )
        );

    /*
     * Modifiers may slow travel to zero, but never reverse the player's
     * chosen direction. Direction is applied only after effective distance is
     * clamped to a non-negative value.
     */
    $distance =
        max(
            0.0,
            $baseDistance +
            $modifierAdjustment
        );

    $direction =
        wayfarerRuntimeNavigationDirection(
            $runtimeState
        );

    $after =
        max(
            0.0,
            (float)$before +
            ($distance * $direction)
        );

    $after =
        wayfarerNormalizeRuntimeNumber(
            $after
        );

    $runtimeState['navigation']['position'] =
        $after;

    return [
        'scope' => 'navigation',
        'type' => 'position',
        'target_id' => 'position',
        'operation' => 'travel',
        'base_distance' =>
            wayfarerNormalizeRuntimeNumber(
                $baseDistance
            ),
        'modifier_adjustment' =>
            wayfarerNormalizeRuntimeNumber(
                $modifierAdjustment
            ),
        'matched_modifiers' =>
            array_values(
                $matchedModifiers
            ),
        'amount' =>
            wayfarerNormalizeRuntimeNumber(
                $distance
            ),
        'direction' =>
            $direction,
        'before' =>
            wayfarerNormalizeRuntimeNumber(
                (float)$before
            ),
        'after' =>
            $after,
        'applied' => true,
        'error' => '',
    ];
}

function wayfarerRuntimeLinearTravelDirection(
    array $regionConfig,
    array $runtimeState
): int {
    $runtimeDirection =
        wayfarerRuntimeNavigationDirection(
            $runtimeState
        );

    /* WAYFARER_LINEAR_TRAVEL_RUNTIME_V72 */
    if (
        wayfarerRuntimeDedicatedLinearTravel(
            $regionConfig
        ) !== null
    ) {
        return $runtimeDirection;
    }

    $effects = isset($regionConfig['tick_effects']) && is_array($regionConfig['tick_effects'])
        ? $regionConfig['tick_effects']
        : [];

    foreach ($effects as $effect) {
        if (!is_array($effect)) {
            continue;
        }
        if (
            (string)($effect['target_scope'] ?? '') !== 'navigation' ||
            (string)($effect['target_type'] ?? '') !== 'position' ||
            (string)($effect['target_id'] ?? '') !== 'position'
        ) {
            continue;
        }

        $branches = wayfarerRuntimeTickEffectBranches($effect);
        foreach ($branches as $branch) {
            $operation = strtolower(trim((string)($branch['operation'] ?? '')));
            if ($operation === 'subtract') {
                return -1 * $runtimeDirection;
            }
            if ($operation === 'add') {
                return 1 * $runtimeDirection;
            }
        }
    }

    return $runtimeDirection;
}

function wayfarerRuntimeBuildTravelStatus(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): array {
    $gameConfig = wayfarerRuntimeLoadGameConfig($pdo, $gameId);
    $timeConfig = wayfarerRuntimeEnsureClock($pdo, $gameId, $runtimeState);

    $result = [
        'time_label' => wayfarerRuntimeClockLabel($runtimeState, $timeConfig),
        'region_name' => '',
        'distance_label' => 'units',
        'next_location_id' => 0,
        'next_location_name' => '',
        'distance_to_next' => null,
        'next_label' => '',

        /* WAYFARER_LINEAR_TRAVEL_RUNTIME_V72 */
        'dedicated_travel' => false,
        'base_distance_per_tick' => null,
        'allow_turnaround' => false,
        'can_turn_around' => false,
        'direction' => 1,
    ];

    $regionId = (int)($runtimeState['navigation']['region_id'] ?? 0);
    $position = $runtimeState['navigation']['position'] ?? null;
    if ($regionId <= 0 || !is_numeric($position)) {
        return $result;
    }

    $stmt = $pdo->prepare(
        'SELECT id, name, navigation_type, config FROM wf_regions WHERE id = ? AND game_id = ? LIMIT 1'
    );
    $stmt->execute([$regionId, $gameId]);
    $region = $stmt->fetch(PDO::FETCH_ASSOC);
    if (!$region) {
        return $result;
    }

    $result['region_name'] = trim((string)($region['name'] ?? ''));
    if (strtolower(trim((string)($region['navigation_type'] ?? ''))) !== 'linear') {
        return $result;
    }

    $regionConfig = wayfarerRuntimeDecodeConfig($region['config'] ?? null);
    $distanceLabel = trim((string)($regionConfig['distance_label'] ?? 'units'));
    $result['distance_label'] = $distanceLabel !== '' ? $distanceLabel : 'units';
    $direction = wayfarerRuntimeLinearTravelDirection($regionConfig, $runtimeState);
    $current = (float)$position;

    /* WAYFARER_LINEAR_TRAVEL_RUNTIME_V72 */
    $dedicatedTravel =
        wayfarerRuntimeDedicatedLinearTravel(
            $regionConfig
        );

    $result['direction'] =
        $direction;

    if ($dedicatedTravel !== null) {
        $result['dedicated_travel'] =
            true;

        $result['base_distance_per_tick'] =
            wayfarerNormalizeRuntimeNumber(
                (float)$dedicatedTravel[
                    'base_distance'
                ]
            );

        $result['allow_turnaround'] =
            !empty(
                $dedicatedTravel[
                    'allow_turnaround'
                ]
            );

        /*
         * Do not offer a reversal that would immediately point out of the
         * legal lower boundary. If already traveling toward Start at zero,
         * turning around toward End remains valid.
         */
        $result['can_turn_around'] =
            $result['allow_turnaround'] &&
            !(
                $current <= 0 &&
                $direction > 0
            );
    }

    $locationStmt = $pdo->prepare(
        "SELECT * FROM wf_locations WHERE region_id = ? AND status = 'active' ORDER BY id"
    );
    $locationStmt->execute([$regionId]);

    $best = null;
    $bestDistance = null;
    foreach ($locationStmt->fetchAll(PDO::FETCH_ASSOC) as $location) {
        $locationConfig = wayfarerRuntimeDecodeConfig($location['config'] ?? null);
        if (!isset($locationConfig['position']) || !is_numeric($locationConfig['position'])) {
            continue;
        }

        $locationPosition = (float)$locationConfig['position'];
        $ahead = $direction < 0
            ? $locationPosition < $current
            : $locationPosition > $current;
        if (!$ahead) {
            continue;
        }

        $location['_runtime_config'] = $locationConfig;
        if (!wayfarerRuntimeLocationConditionsPass($pdo, $gameId, $location, $runtimeState)) {
            continue;
        }

        $distance = abs($locationPosition - $current);
        if ($best === null || $distance < $bestDistance) {
            $best = $location;
            $bestDistance = $distance;
        }
    }

    if ($best !== null) {
        $distance = wayfarerNormalizeRuntimeNumber((float)$bestDistance);
        $name = trim((string)($best['name'] ?? 'Location')) ?: 'Location';
        $result['next_location_id'] = (int)($best['id'] ?? 0);
        $result['next_location_name'] = $name;
        $result['distance_to_next'] = $distance;
        $result['next_label'] = $name . ' — ' . $distance . ' ' . $result['distance_label'];
    }

    return $result;
}


function wayfarerRuntimeActiveTraitDefinitions(
    array $config
): array {

    $traits =
        $config['traits']
        ?? [];

    if (!is_array($traits)) {
        return [];
    }

    $result = [];

    foreach ($traits as $trait) {

        if (!is_array($trait)) {
            continue;
        }

        if (
            array_key_exists(
                'active',
                $trait
            ) &&
            !$trait['active']
        ) {
            continue;
        }

        $traitId =
            trim(
                (string)(
                    $trait['id']
                    ?? $trait['system_key']
                    ?? ''
                )
            );

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

        $trait['_runtime_id'] =
            $traitId;

        $result[] =
            $trait;
    }

    return $result;
}


function wayfarerRuntimeInitialTraitValue(
    array $trait
) {

    if (
        array_key_exists(
            'initial',
            $trait
        )
    ) {
        return $trait['initial'];
    }

    $type =
        strtolower(
            trim(
                (string)(
                    $trait['type']
                    ?? ''
                )
            )
        );

    if (
        $type === 'number' ||
        $type === 'binary' ||
        $type === 'boolean'
    ) {
        return 0;
    }

    return null;
}


function wayfarerRuntimeInitialTraitState(
    array $config
): array {

    $state = [];

    foreach (
        wayfarerRuntimeActiveTraitDefinitions(
            $config
        )
        as $trait
    ) {

        $traitId =
            (string)$trait['_runtime_id'];

        $state[$traitId] =
            wayfarerRuntimeInitialTraitValue(
                $trait
            );
    }

    return $state;
}


/*
|--------------------------------------------------------------------------
| Persisted state for every Region
|--------------------------------------------------------------------------
| WAYFARER_ALL_REGION_STATE_V46
|
| Game-wide Conditions may inspect a Region that the player has never visited.
| Therefore every authored Region needs persistent Trait state, not only the
| current Region.
|
| This helper is additive/recovery-safe:
|   - existing runtime values are never overwritten;
|   - missing Regions or newly-added Traits receive their authored initial;
|   - stale historical values are not destructively removed here.
|
*/

function wayfarerRuntimeEnsureAllRegionTraitState(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): void {

    if ($gameId <= 0) {
        return;
    }


    if (
        !isset($runtimeState['regions']) ||
        !is_array($runtimeState['regions'])
    ) {
        $runtimeState['regions'] =
            [];
    }


    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                config
            FROM wf_regions
            WHERE game_id = ?
            ORDER BY id
            "
        );

    $stmt->execute([
        $gameId
    ]);


    $regions =
        $stmt->fetchAll(
            PDO::FETCH_ASSOC
        );


    foreach ($regions as $region) {

        $regionId =
            (int)(
                $region['id']
                ?? 0
            );

        if ($regionId <= 0) {
            continue;
        }


        $regionKey =
            (string)$regionId;

        $config =
            wayfarerRuntimeDecodeConfig(
                $region['config']
                ?? null
            );

        $initialTraits =
            wayfarerRuntimeInitialTraitState(
                $config
            );


        if (
            !isset(
                $runtimeState['regions'][$regionKey]
            ) ||
            !is_array(
                $runtimeState['regions'][$regionKey]
            )
        ) {
            $runtimeState['regions'][$regionKey] =
                [];
        }


        if (
            !isset(
                $runtimeState['regions'][$regionKey]['traits']
            ) ||
            !is_array(
                $runtimeState['regions'][$regionKey]['traits']
            )
        ) {
            $runtimeState['regions'][$regionKey]['traits'] =
                [];
        }


        foreach (
            $initialTraits
            as $traitId => $initialValue
        ) {

            if (
                array_key_exists(
                    $traitId,
                    $runtimeState['regions'][$regionKey]['traits']
                )
            ) {
                continue;
            }

            $runtimeState['regions'][$regionKey]['traits'][$traitId] =
                $initialValue;
        }
    }
}


/*
|--------------------------------------------------------------------------
| Persisted state for every Location
| WAYFARER_ALL_LOCATION_STATE_V56
|--------------------------------------------------------------------------
|
| Locations can own Traits, so universal Conditions/Effects need persistent
| per-playthrough Location Trait state just like Regions.
|
*/

function wayfarerRuntimeEnsureAllLocationTraitState(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): void {

    if ($gameId <= 0) {
        return;
    }

    if (
        !isset($runtimeState['locations']) ||
        !is_array($runtimeState['locations'])
    ) {
        $runtimeState['locations'] = [];
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT
                l.id,
                l.region_id,
                l.config
            FROM wf_locations l
            INNER JOIN wf_regions r
                ON r.id = l.region_id
            WHERE r.game_id = ?
            ORDER BY l.id
            "
        );

    $stmt->execute([
        $gameId
    ]);

    foreach (
        $stmt->fetchAll(PDO::FETCH_ASSOC)
        as $location
    ) {
        $locationId =
            (int)($location['id'] ?? 0);

        if ($locationId <= 0) {
            continue;
        }

        $locationKey =
            (string)$locationId;

        $config =
            wayfarerRuntimeDecodeConfig(
                $location['config']
                    ?? null
            );

        $initialTraits =
            wayfarerRuntimeInitialTraitState(
                $config
            );

        if (
            !isset($runtimeState['locations'][$locationKey]) ||
            !is_array($runtimeState['locations'][$locationKey])
        ) {
            $runtimeState['locations'][$locationKey] = [];
        }

        /*
         * WAYFARER_LIVE_LOCATION_ANCHORS_V76
         *
         * These are definition-derived spatial facts, so refresh them every
         * ensure pass. Moving a Location in Builder therefore changes the
         * anchor without rewriting authored Conditions.
         */
        $runtimeState['locations'][$locationKey]['region_id'] =
            (int)(
                $location['region_id']
                ?? 0
            );

        $runtimeState['locations'][$locationKey]['position'] =
            isset($config['position']) &&
            is_numeric($config['position'])
                ? (float)$config['position']
                : null;

        if (
            !isset($runtimeState['locations'][$locationKey]['traits']) ||
            !is_array($runtimeState['locations'][$locationKey]['traits'])
        ) {
            $runtimeState['locations'][$locationKey]['traits'] = [];
        }

        foreach (
            $initialTraits
            as $traitId => $initialValue
        ) {
            if (
                array_key_exists(
                    $traitId,
                    $runtimeState['locations'][$locationKey]['traits']
                )
            ) {
                continue;
            }

            $runtimeState['locations'][$locationKey]['traits'][$traitId] =
                $initialValue;
        }
    }
}

function wayfarerRuntimeLoadStartingRegion(
    PDO $pdo,
    int $gameId,
    ?array $gameConfig = null
): ?array {

    if ($gameId <= 0) {
        return null;
    }


    if ($gameConfig === null) {

        $stmt =
            $pdo->prepare(
                "
                SELECT config
                FROM wf_games
                WHERE id = ?
                LIMIT 1
                "
            );

        $stmt->execute([
            $gameId
        ]);

        $rawConfig =
            $stmt->fetchColumn();

        if ($rawConfig === false) {
            return null;
        }

        $gameConfig =
            wayfarerRuntimeDecodeConfig(
                $rawConfig
            );
    }


    $startingRegionId =
        (int)(
            $gameConfig['starting_region_id']
            ?? 0
        );

    if ($startingRegionId <= 0) {
        return null;
    }


    $stmt =
        $pdo->prepare(
            "
            SELECT *
            FROM wf_regions
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

    $stmt->execute([
        $startingRegionId,
        $gameId,
    ]);

    $region =
        $stmt->fetch(
            PDO::FETCH_ASSOC
        );


    return $region ?: null;
}


function wayfarerRuntimeInitializeGame(
    PDO $pdo,
    int $gameUserId,
    array $setupInput = []
): array {

    if ($gameUserId <= 0) {
        throw new RuntimeException(
            'A valid game-user ID is required to initialize the game.'
        );
    }


    try {

        $pdo->beginTransaction();


        /*
         * Lock the playthrough row so two initialize requests cannot create
         * competing starting states.
         */
        $stmt =
            $pdo->prepare(
                "
                SELECT
                    gu.id,
                    gu.game_id,
                    gu.user_id,
                    gu.role,
                    gu.state,
                    g.config AS game_config,
                    g.player_slots AS player_slots
                FROM wf_game_users gu
                INNER JOIN wf_games g
                    ON g.id = gu.game_id
                WHERE gu.id = ?
                LIMIT 1
                FOR UPDATE
                "
            );

        $stmt->execute([
            $gameUserId
        ]);

        $row =
            $stmt->fetch(
                PDO::FETCH_ASSOC
            );

        if (!$row) {
            throw new RuntimeException(
                'Game-user runtime record not found.'
            );
        }


        /*
         * Initialization is intentionally one-way. To restart a development
         * game, clear wf_game_users.state to NULL first.
         */
        if (
            $row['state'] !== null &&
            $row['state'] !== ''
        ) {
            throw new RuntimeException(
                'This game-user already has runtime state.'
            );
        }


        $gameId =
            (int)$row['game_id'];

        $gameConfig =
            wayfarerRuntimeDecodeConfig(
                $row['game_config']
                ?? null
            );


        $startingRegionId =
            (int)(
                $gameConfig['starting_region_id']
                ?? 0
            );

        if ($startingRegionId <= 0) {
            throw new RuntimeException(
                'This Game does not have a Starting Region configured.'
            );
        }


        $startingRegion =
            wayfarerRuntimeLoadStartingRegion(
                $pdo,
                $gameId,
                $gameConfig
            );

        if (!$startingRegion) {
            throw new RuntimeException(
                'The configured Starting Region does not exist for this Game.'
            );
        }


        $regionConfig =
            wayfarerRuntimeDecodeConfig(
                $startingRegion['config']
                ?? null
            );


        $gameTraits =
            wayfarerRuntimeInitialTraitState(
                $gameConfig
            );

        $regionTraits =
            wayfarerRuntimeInitialTraitState(
                $regionConfig
            );


        $navigation = [
            'region_id' =>
                (int)$startingRegion['id'],

            /* WAYFARER_BIDIRECTIONAL_TRAVEL_V71 */
            'direction' =>
                1,
        ];


        /*
         * Linear travel currently begins at coordinate zero.
         * Other navigation modes will get their own authored start-state
         * rules when those modes are implemented.
         */
        if (
            strtolower(
                trim(
                    (string)(
                        $startingRegion['navigation_type']
                        ?? ''
                    )
                )
            ) === 'linear'
        ) {
            $navigation['position'] =
                0;
        }


        $regionKey =
            (string)$startingRegion['id'];


        $state = [
            /*
             * WAYFARER_RUNTIME_SCHEMA_V55
             * WAYFARER_BIDIRECTIONAL_TRAVEL_V71
             * Version the persisted playthrough contract explicitly.
             */
            'schema_version' => 2,

            'game' => [
                'traits' =>
                    $gameTraits,
            ],

            'navigation' =>
                $navigation,

            'regions' => [
                $regionKey => [
                    'traits' =>
                        $regionTraits,
                ],
            ],

            'runtime' => [
                'tick' => 0,
            ],
        ];


        /* WAYFARER_INITIALIZE_GAME_CLOCK_V61 */
        wayfarerRuntimeInitializeClockFromConfig(
            $gameConfig,
            $state
        );

        /*
         * WAYFARER_ALL_REGION_STATE_V46
         *
         * Global conditions can inspect Region state before that Region has
         * ever been visited.
         */
        wayfarerRuntimeEnsureAllRegionTraitState(
            $pdo,
            $gameId,
            $state
        );

        /* WAYFARER_INITIALIZE_LOCATION_STATE_V56 */
        wayfarerRuntimeEnsureAllLocationTraitState(
            $pdo,
            $gameId,
            $state
        );

        /*
         * WAYFARER_ENTITY_RUNTIME_STATE_V49
         *
         * Items and Characters receive canonical per-playthrough state before
         * any starting setup effects are applied.
         */
        wayfarerRuntimeEnsureEntityState(
            $pdo,
            $gameId,
            $state
        );


        /*
         * WAYFARER_APPLY_STARTING_CHOICES_V36
         *
         * Validate all player-entered setup data before persisting anything.
         * Then apply the selected options' starting effects to the canonical
         * initial runtime state.
         */
        $preparedSetup =
            wayfarerRuntimePrepareStartingSetup(
                $gameConfig,
                (int)(
                    $row['player_slots']
                    ?? 0
                ),
                $setupInput
            );

        /*
         * WAYFARER_PLAYER_TRAITS_RUNTIME_V52
         *
         * Persist the validated player-character names before creating the
         * per-player Trait state. Each slot receives independent values.
         */
        $state['setup'] = [
            'player_names' =>
                $preparedSetup['player_names'],
            'choices' =>
                $preparedSetup['choices'],
        ];

        wayfarerRuntimeEnsureGameTraitState(
            $gameConfig,
            $state
        );

        wayfarerRuntimeEnsurePlayerState(
            $gameConfig,
            (int)(
                $row['player_slots']
                ?? 0
            ),
            $state
        );

        $traitDefinitions =
            wayfarerRuntimeLoadTickTraitDefinitions(
                $pdo,
                $gameId,
                $regionConfig
            );

        $startingEffectReports = [];

        foreach (
            $preparedSetup['effects']
            as $startingEffect
        ) {

            /* WAYFARER_STARTING_CHOICE_RANDOM_RUNTIME_V58 */
            $resolvedStartingValue =
                wayfarerRuntimeRollEffectValue(
                    $startingEffect
                );

            if (!$resolvedStartingValue['valid']) {
                throw new RuntimeException(
                    'Unable to resolve a Starting Choice effect value: ' .
                    $resolvedStartingValue['error']
                );
            }

            $concreteStartingEffect =
                $startingEffect;

            $concreteStartingEffect['value'] =
                $resolvedStartingValue['value'];

            $report =
                wayfarerApplyRuntimeEffect(
                    $state,
                    $concreteStartingEffect,
                    (int)$startingRegion['id'],
                    $traitDefinitions
                );

            if (
                !empty($report['error'])
            ) {
                throw new RuntimeException(
                    'Unable to apply a Starting Choice effect: ' .
                    $report['error']
                );
            }

            $report['value_mode'] =
                $resolvedStartingValue['mode'];

            $report['rolled_value'] =
                $resolvedStartingValue['value'];

            if ($resolvedStartingValue['mode'] === 'random') {
                $report['random_min'] =
                    $resolvedStartingValue['min'];

                $report['random_max'] =
                    $resolvedStartingValue['max'];
            }

            $startingEffectReports[] =
                $report;
        }

        /*
         * WAYFARER_RUNTIME_DIAGNOSTIC_CLEANUP_V55
         *
         * Starting-effect reports are intentionally not persisted. The effects
         * themselves have already mutated canonical state.
         */


        /*
         * WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40
         *
         * A game that begins exactly on an active Location should present that
         * Location before ordinary Action Mode.
         */
        $startingLocation =
            wayfarerRuntimeFindCurrentLocation(
                $pdo,
                $gameId,
                $state
            );

        if ($startingLocation) {

            /*
             * WAYFARER_LOCATION_ONE_TIME_EFFECT_TRIGGER_V42
             *
             * Starting on a Location is a real Location trigger. Apply its
             * one-time Effects before opening Presentation Mode.
             */
            wayfarerApplyLocationEffects(
                $pdo,
                $gameId,
                $startingLocation,
                $state
            );

            $state['runtime']['presentation'] = [
                'type' =>
                    'location',

                'id' =>
                    (int)$startingLocation['id'],

                'phase' =>
                    'presentation',

                'trigger' =>
                    'initial',

                'tick' =>
                    (int)(
                        $state['runtime']['tick']
                        ?? 0
                    ),
            ];
        }


        /* WAYFARER_GAME_ENDINGS_INITIAL_V45 */
        wayfarerRuntimeEvaluateGameEndings(
            $pdo,
            $gameId,
            $state
        );


        $encodedState =
            wayfarerRuntimeEncodeState(
                $state
            );


        $update =
            $pdo->prepare(
                "
                UPDATE wf_game_users
                SET state = ?
                WHERE id = ?
                "
            );

        $update->execute([
            $encodedState,
            $gameUserId,
        ]);


        $pdo->commit();


        return [
            'game_user_id' =>
                (int)$row['id'],

            'game_id' =>
                $gameId,

            'starting_region_id' =>
                (int)$startingRegion['id'],

            'state' =>
                $state,
        ];


    } catch (Throwable $exception) {

        if ($pdo->inTransaction()) {
            $pdo->rollBack();
        }

        throw $exception;
    }
}

/**
 * Resolve a game-user record for the tick prototype.
 *
 * Preferred:
 *   explicit wf_game_users.id
 *
 * Temporary development fallback:
 *   first wf_game_users record.
 *
 * The fallback exists only because Wayfarer has not yet wired the play
 * page to authentication / game selection. Once that exists, remove the
 * fallback and always pass the active game_user_id explicitly.
 */
function wayfarerRuntimeResolveGameUserId(
    PDO $pdo,
    ?int $requestedId = null
): int {

    if ($requestedId !== null && $requestedId > 0) {

        $stmt = $pdo->prepare(
            "
            SELECT id
            FROM wf_game_users
            WHERE id = ?
            LIMIT 1
            "
        );

        $stmt->execute([
            $requestedId
        ]);

        $id = $stmt->fetchColumn();

        if ($id !== false) {
            return (int)$id;
        }

        throw new RuntimeException(
            'The requested game-user record does not exist.'
        );
    }

    $id = $pdo
        ->query(
            "
            SELECT id
            FROM wf_game_users
            ORDER BY id
            LIMIT 1
            "
        )
        ->fetchColumn();

    if ($id === false) {
        throw new RuntimeException(
            'No wf_game_users record exists.'
        );
    }

    return (int)$id;
}


/**
 * Load one game-user runtime state.
 */
function wayfarerRuntimeLoad(
    PDO $pdo,
    int $gameUserId
): array {

    $stmt = $pdo->prepare(
        "
        SELECT
            id,
            game_id,
            user_id,
            role,
            state
        FROM wf_game_users
        WHERE id = ?
        LIMIT 1
        "
    );

    $stmt->execute([
        $gameUserId
    ]);

    $row = $stmt->fetch(
        PDO::FETCH_ASSOC
    );

    if (!$row) {
        throw new RuntimeException(
            'Game-user runtime record not found.'
        );
    }

    $state = wayfarerRuntimeDecodeState(
        $row['state']
    );

    return [
        'game_user_id' => (int)$row['id'],
        'game_id'      => (int)$row['game_id'],
        'user_id'      => (int)$row['user_id'],
        'role'         => (string)$row['role'],
        'state'        => $state,
        'tick'         => (int)(
            $state['runtime']['tick']
            ?? 0
        ),
    ];
}


/**
 * Advance exactly one tick.
 *
 * This is intentionally the entire v14 game engine:
 *
 *     state.runtime.tick += 1
 *
 * The transaction and row lock are already in place so later work can add
 * movement/effects without changing the request architecture.
 */
/*
|--------------------------------------------------------------------------
| Linear Location crossing
| WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40
|--------------------------------------------------------------------------
|
| A tick may move farther than the distance to the next authored Location.
| This resolver finds the FIRST active Location crossed in the direction of
| travel. The movement is then clamped to that exact authored coordinate.
|
| Examples:
|     45 -> 55, Location 50  => stop at 50
|     55 -> 45, Location 50  => stop at 50
|
| The starting coordinate is intentionally exclusive so leaving a Location
| does not immediately trigger that same Location again.
|
*/

/*
|--------------------------------------------------------------------------
| Location Conditions
| WAYFARER_LOCATION_CONDITIONS_RUNTIME_V45
|--------------------------------------------------------------------------
*/

function wayfarerRuntimeLocationConditionsPass(
    PDO $pdo,
    int $gameId,
    array $location,
    array &$runtimeState
): bool {

    $config =
        isset(
            $location['_runtime_config']
        ) &&
        is_array(
            $location['_runtime_config']
        )
            ? $location['_runtime_config']
            : wayfarerRuntimeDecodeConfig(
                $location['config']
                ?? null
            );

    $conditions =
        $config['conditions']
        ?? null;

    $regionId =
        (int)(
            $runtimeState['navigation']['region_id']
            ?? 0
        );

    $resolver =
        function (
            string $scope,
            string $targetType,
            string $targetId
        ) use (
            &$runtimeState,
            $regionId
        ): array {

            return
                wayfarerRuntimeResolveConditionTarget(
                    $runtimeState,
                    $regionId,
                    $scope,
                    $targetType,
                    $targetId
                );
        };

    return
        wayfarerConditionsPass(
            $conditions,
            $resolver
        );
}


/*
|--------------------------------------------------------------------------
| Game Endings
| WAYFARER_GAME_ENDINGS_RUNTIME_V45
|--------------------------------------------------------------------------
*/

function wayfarerRuntimeEvaluateGameEndings(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): ?array {

    /*
     * WAYFARER_ALL_REGION_STATE_ENDINGS_V46
     */
    wayfarerRuntimeEnsureAllRegionTraitState(
        $pdo,
        $gameId,
        $runtimeState
    );

    /* WAYFARER_RECOVER_LOCATION_STATE_V56 */
    wayfarerRuntimeEnsureAllLocationTraitState(
        $pdo,
        $gameId,
        $runtimeState
    );


    if (
        isset(
            $runtimeState['runtime']['ending']
        ) &&
        is_array(
            $runtimeState['runtime']['ending']
        )
    ) {
        return
            $runtimeState['runtime']['ending'];
    }


    $stmt =
        $pdo->prepare(
            "
            SELECT config
            FROM wf_games
            WHERE id = ?
            LIMIT 1
            "
        );

    $stmt->execute([
        $gameId
    ]);

    $raw =
        $stmt->fetchColumn();

    $config =
        wayfarerRuntimeDecodeConfig(
            $raw === false
                ? null
                : $raw
        );

    $endings =
        $config['endings']
        ?? [];

    if (!is_array($endings)) {
        return null;
    }


    $ordered =
        [];

    foreach (
        array_values($endings)
        as $index => $ending
    ) {

        if (!is_array($ending)) {
            continue;
        }

        $ending['_runtime_order'] =
            $index;

        $ordered[] =
            $ending;
    }


    usort(
        $ordered,
        function (
            array $a,
            array $b
        ): int {

            $priorityCompare =
                (int)(
                    $b['priority']
                    ?? 0
                ) <=>
                (int)(
                    $a['priority']
                    ?? 0
                );

            if ($priorityCompare !== 0) {
                return
                    $priorityCompare;
            }

            return
                (int)(
                    $a['_runtime_order']
                    ?? 0
                ) <=>
                (int)(
                    $b['_runtime_order']
                    ?? 0
                );
        }
    );


    $regionId =
        (int)(
            $runtimeState['navigation']['region_id']
            ?? 0
        );

    $resolver =
        function (
            string $scope,
            string $targetType,
            string $targetId
        ) use (
            &$runtimeState,
            $regionId
        ): array {

            return
                wayfarerRuntimeResolveConditionTarget(
                    $runtimeState,
                    $regionId,
                    $scope,
                    $targetType,
                    $targetId
                );
        };


    foreach ($ordered as $ending) {

        if (
            !wayfarerConditionsPass(
                $ending['conditions']
                    ?? null,
                $resolver
            )
        ) {
            continue;
        }


        $terminal = [
            'id' =>
                (string)(
                    $ending['id']
                    ?? ''
                ),

            'title' =>
                (string)(
                    $ending['title']
                    ?? 'The End'
                ),

            'text' =>
                (string)(
                    $ending['text']
                    ?? ''
                ),

            'image_media_id' =>
                (int)(
                    $ending['image_media_id']
                    ?? 0
                ),

            'priority' =>
                (int)(
                    $ending['priority']
                    ?? 0
                ),

            'tick' =>
                (int)(
                    $runtimeState['runtime']['tick']
                    ?? 0
                ),
        ];


        if (
            !isset(
                $runtimeState['runtime']
            ) ||
            !is_array(
                $runtimeState['runtime']
            )
        ) {
            $runtimeState['runtime'] =
                [];
        }


        $runtimeState['runtime']['ending'] =
            $terminal;

        unset(
            $runtimeState['runtime']['presentation']
        );

        return
            $terminal;
    }


    return null;
}


function wayfarerRuntimeFindCrossedLocation(
    PDO $pdo,
    int $gameId,
    int $regionId,
    $fromPosition,
    $toPosition,
    array &$runtimeState
): ?array {

    /*
     * WAYFARER_CROSSED_LOCATION_STATE_FIX_V46_1
     *
     * Location Conditions are evaluated against the live runtime state.
     */

    if (
        $gameId <= 0 ||
        $regionId <= 0 ||
        !is_numeric($fromPosition) ||
        !is_numeric($toPosition)
    ) {
        return null;
    }


    $from =
        (float)$fromPosition;

    $to =
        (float)$toPosition;


    if ($from === $to) {
        return null;
    }


    /*
     * Crossing interception currently applies only to Linear Regions.
     */
    $regionStmt =
        $pdo->prepare(
            "
            SELECT navigation_type
            FROM wf_regions
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

    $regionStmt->execute([
        $regionId,
        $gameId,
    ]);

    $navigationType =
        $regionStmt->fetchColumn();

    if (
        $navigationType === false ||
        strtolower(
            trim(
                (string)$navigationType
            )
        ) !== 'linear'
    ) {
        return null;
    }


    $locationStmt =
        $pdo->prepare(
            "
            SELECT *
            FROM wf_locations
            WHERE region_id = ?
              AND status = 'active'
            ORDER BY id
            "
        );

    $locationStmt->execute([
        $regionId
    ]);

    $locations =
        $locationStmt->fetchAll(
            PDO::FETCH_ASSOC
        );


    $forward =
        $to > $from;

    $candidate =
        null;

    $candidatePosition =
        null;


    foreach ($locations as $location) {

        $config =
            wayfarerRuntimeDecodeConfig(
                $location['config']
                ?? null
            );

        if (
            !array_key_exists(
                'position',
                $config
            ) ||
            !is_numeric(
                $config['position']
            )
        ) {
            continue;
        }


        $locationPosition =
            (float)$config['position'];


        /*
         * The starting point is exclusive; the destination is inclusive.
         */
        $crossed =
            $forward
                ? (
                    $locationPosition > $from &&
                    $locationPosition <= $to
                )
                : (
                    $locationPosition < $from &&
                    $locationPosition >= $to
                );

        if (!$crossed) {
            continue;
        }


        $location['_runtime_config'] =
            $config;

        if (
            !wayfarerRuntimeLocationConditionsPass(
                $pdo,
                $gameId,
                $location,
                $runtimeState
            )
        ) {
            continue;
        }


        if ($candidate === null) {

            $candidate =
                $location;

            $candidatePosition =
                $locationPosition;

        } else {

            $nearer =
                $forward
                    ? (
                        $locationPosition <
                        $candidatePosition
                    )
                    : (
                        $locationPosition >
                        $candidatePosition
                    );

            $samePositionLowerId =
                $locationPosition ===
                    $candidatePosition &&
                (int)$location['id'] <
                    (int)$candidate['id'];

            if (
                $nearer ||
                $samePositionLowerId
            ) {

                $candidate =
                    $location;

                $candidatePosition =
                    $locationPosition;
            }
        }
    }


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


    $candidate['_runtime_position'] =
        wayfarerNormalizeRuntimeNumber(
            (float)$candidatePosition
        );

    $candidate['_runtime_config'] =
        wayfarerRuntimeDecodeConfig(
            $candidate['config']
            ?? null
        );


    return $candidate;
}


/*
|--------------------------------------------------------------------------
| Player spatial context
|--------------------------------------------------------------------------
| WAYFARER_PLAYER_CONTEXT_V46_1
|
| This is the canonical player-facing spatial label for Action Mode:
|
|   exact eligible Location -> Location name + Region parent context
|   otherwise               -> Region name
|
| It is returned by runtime APIs so the browser does not keep displaying the
| Location name from the page's original server render after movement.
|
*/

function wayfarerRuntimePlayerContext(
    PDO $pdo,
    int $gameId,
    array $runtimeState
): array {

    $regionId =
        (int)(
            $runtimeState['navigation']['region_id']
            ?? 0
        );

    $regionName =
        '';

    if ($regionId > 0) {

        $stmt =
            $pdo->prepare(
                "
                SELECT name
                FROM wf_regions
                WHERE id = ?
                  AND game_id = ?
                LIMIT 1
                "
            );

        $stmt->execute([
            $regionId,
            $gameId,
        ]);

        $rawRegionName =
            $stmt->fetchColumn();

        if ($rawRegionName !== false) {
            $regionName =
                trim(
                    (string)$rawRegionName
                );
        }
    }


    $location =
        wayfarerRuntimeFindCurrentLocation(
            $pdo,
            $gameId,
            $runtimeState
        );

    $locationId =
        0;

    $locationName =
        '';

    if ($location) {

        $locationId =
            (int)(
                $location['id']
                ?? 0
            );

        $locationName =
            trim(
                (string)(
                    $location['name']
                    ?? ''
                )
            );
    }


    $contextName =
        $locationName !== ''
            ? $locationName
            : (
                $regionName !== ''
                    ? $regionName
                    : 'Actions'
            );


    return [
        'region_id' =>
            $regionId,

        'region_name' =>
            $regionName,

        'location_id' =>
            $locationId,

        'location_name' =>
            $locationName,

        'context_name' =>
            $contextName,

        'parent_context' =>
            $locationName !== ''
                ? $regionName
                : '',
    ];
}


/*
|--------------------------------------------------------------------------
| Presentation dismissal
|--------------------------------------------------------------------------
|
| Presentation is persisted runtime state. This function is intentionally
| generic even though v40 renders only Location presentations; Storylets can
| use the same mechanism later.
|
*/

function wayfarerRuntimeDismissPresentation(
    PDO $pdo,
    int $gameUserId,
    string $expectedType = '',
    int $expectedId = 0
): array {

    try {

        $pdo->beginTransaction();


        $stmt =
            $pdo->prepare(
                "
                SELECT
                    id,
                    game_id,
                    user_id,
                    role,
                    state
                FROM wf_game_users
                WHERE id = ?
                LIMIT 1
                FOR UPDATE
                "
            );

        $stmt->execute([
            $gameUserId
        ]);

        $row =
            $stmt->fetch(
                PDO::FETCH_ASSOC
            );

        if (!$row) {
            throw new RuntimeException(
                'Game-user runtime record not found.'
            );
        }


        $state =
            wayfarerRuntimeDecodeState(
                $row['state']
            );

        $presentation =
            $state['runtime']['presentation']
            ?? null;

        if (
            !is_array($presentation) ||
            empty($presentation['type']) ||
            empty($presentation['id'])
        ) {
            throw new RuntimeException(
                'There is no active presentation to continue.'
            );
        }


        if (
            $expectedType !== '' &&
            (string)$presentation['type'] !==
                $expectedType
        ) {
            throw new RuntimeException(
                'The active presentation changed before it could be dismissed.'
            );
        }


        if (
            $expectedId > 0 &&
            (int)$presentation['id'] !==
                $expectedId
        ) {
            throw new RuntimeException(
                'The active presentation changed before it could be dismissed.'
            );
        }


        /* WAYFARER_STORYLET_BRANCH_DISMISS_GUARD_V59 */
        if (
            (string)($presentation['type'] ?? '') === 'storylet'
        ) {
            $eligibleBranches =
                wayfarerRuntimeEligibleStoryletBranches(
                    $pdo,
                    (int)$row['game_id'],
                    (int)($presentation['id'] ?? 0),
                    $state
                );

            if ($eligibleBranches) {
                throw new RuntimeException(
                    'Choose an available Storylet Branch before continuing.'
                );
            }
        }

        $state['runtime']['last_presentation'] =
            $presentation;

        unset(
            $state['runtime']['presentation']
        );

        /* WAYFARER_STATUS_STORYLET_QUEUE_V88 */
        wayfarerRuntimePromotePendingStatusStorylet(
            $pdo,
            (int)$row['game_id'],
            $state
        );

        wayfarerRuntimeEvaluateGameEndings(
            $pdo,
            (int)$row['game_id'],
            $state
        );


        $encodedState =
            wayfarerRuntimeEncodeState(
                $state
            );

        $update =
            $pdo->prepare(
                "
                UPDATE wf_game_users
                SET state = ?
                WHERE id = ?
                "
            );

        $update->execute([
            $encodedState,
            $gameUserId,
        ]);


        $pdo->commit();


        return [
            'game_user_id' =>
                (int)$row['id'],

            'game_id' =>
                (int)$row['game_id'],

            'state' =>
                $state,

            'context' =>
                wayfarerRuntimePlayerContext(
                    $pdo,
                    (int)$row['game_id'],
                    $state
                ),

            'dismissed' =>
                $presentation,

            /* WAYFARER_STORYLET_ACTIONS_AFTER_PRESENTATION_V59 */
            'actions' =>
                isset($state['runtime']['presentation']) &&
                is_array($state['runtime']['presentation'])
                    ? []
                    : wayfarerRuntimeEligibleRootManualStorylets(
                        $pdo,
                        (int)$row['game_id'],
                        $state
                    ),

            /* WAYFARER_STATUS_STORYLET_QUEUE_V88 */
            'presentation' =>
                isset($state['runtime']['presentation']) &&
                is_array($state['runtime']['presentation'])
                    ? $state['runtime']['presentation']
                    : null,
        ];

    } catch (Throwable $exception) {

        if ($pdo->inTransaction()) {
            $pdo->rollBack();
        }

        throw $exception;
    }
}


/**
 * Advance exactly one tick.
 *
 * WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40
 */
function wayfarerRuntimeAdvanceTick(
    PDO $pdo,
    int $gameUserId,
    ?int $requestedTravelDirection = null
): array {

    try {

        $pdo->beginTransaction();

        $stmt =
            $pdo->prepare(
                "
                SELECT
                    id,
                    game_id,
                    user_id,
                    role,
                    state
                FROM wf_game_users
                WHERE id = ?
                LIMIT 1
                FOR UPDATE
                "
            );

        $stmt->execute([
            $gameUserId
        ]);

        $row =
            $stmt->fetch(
                PDO::FETCH_ASSOC
            );

        if (!$row) {
            throw new RuntimeException(
                'Game-user runtime record not found.'
            );
        }


        $state =
            wayfarerRuntimeDecodeState(
                $row['state']
            );

        if (
            !isset($state['runtime']) ||
            !is_array($state['runtime'])
        ) {
            $state['runtime'] = [];
        }


        /* WAYFARER_BIDIRECTIONAL_TRAVEL_V71 */
        if (
            !isset($state['navigation']) ||
            !is_array($state['navigation'])
        ) {
            $state['navigation'] = [];
        }

        if (
            $requestedTravelDirection !== null &&
            !in_array(
                $requestedTravelDirection,
                [-1, 1],
                true
            )
        ) {
            throw new RuntimeException(
                'Travel direction must be -1 or 1.'
            );
        }

        $state['navigation']['direction'] =
            $requestedTravelDirection !== null
                ? $requestedTravelDirection
                : wayfarerRuntimeNavigationDirection(
                    $state
                );

        $state['schema_version'] =
            max(
                2,
                (int)(
                    $state['schema_version']
                    ?? 1
                )
            );


        /*
         * WAYFARER_GAME_ENDINGS_TERMINAL_V45
         *
         * Endings are terminal runtime state.
         */
        if (
            isset(
                $state['runtime']['ending']
            ) &&
            is_array(
                $state['runtime']['ending']
            )
        ) {
            throw new RuntimeException(
                'This game has ended.'
            );
        }


        /*
         * Narrative presentation is a true runtime pause, not merely a hidden
         * browser control. Even Author Mode cannot advance ticks through it.
         */
        if (
            isset(
                $state['runtime']['presentation']
            ) &&
            is_array(
                $state['runtime']['presentation']
            )
        ) {
            throw new RuntimeException(
                'Continue the current presentation before advancing time.'
            );
        }


        /*
         * WAYFARER_ALL_REGION_STATE_TICK_V46
         *
         * Recovery path for playthroughs initialized before v46, and for
         * Regions/Traits authored after a playthrough began.
         */
        wayfarerRuntimeEnsureAllRegionTraitState(
            $pdo,
            (int)$row['game_id'],
            $state
        );

        /* WAYFARER_LOCATION_STATE_TICK_RECOVERY_V56 */
        wayfarerRuntimeEnsureAllLocationTraitState(
            $pdo,
            (int)$row['game_id'],
            $state
        );

        /*
         * WAYFARER_ENTITY_RUNTIME_STATE_TICK_V49
         *
         * Recovery path for playthroughs created before V49 and for Entities
         * or Traits authored after play began.
         */
        wayfarerRuntimeEnsureEntityState(
            $pdo,
            (int)$row['game_id'],
            $state
        );

        /* WAYFARER_PLAYER_TRAITS_TICK_RECOVERY_V52 */
        wayfarerRuntimeEnsurePlayerAndGameState(
            $pdo,
            (int)$row['game_id'],
            $state
        );


        $regionIdBeforeTick =
            (int)(
                $state['navigation']['region_id']
                ?? 0
            );

        $positionBeforeTick =
            $state['navigation']['position']
            ?? null;


        $currentTick =
            (int)(
                $state['runtime']['tick']
                ?? 0
            );

        $state['runtime']['tick'] =
            $currentTick + 1;

        /* WAYFARER_ADVANCE_GAME_CLOCK_V61 */
        wayfarerRuntimeAdvanceClock(
            $pdo,
            (int)$row['game_id'],
            $state
        );


        /*
         * Global Game Tick Effects run first.
         */
        wayfarerApplyGameTickEffects(
            $pdo,
            (int)$row['game_id'],
            $state
        );


        /*
         * Current Region Tick Effects then perform Region-level movement and
         * state changes.
         */
        wayfarerApplyCurrentRegionTickEffects(
            $pdo,
            $state
        );


        /*
         * Resolve whether the completed movement would have crossed an active
         * Location. If so, stop at the nearest crossed Location rather than
         * accepting the overshot position.
         */
        $regionIdAfterMovement =
            (int)(
                $state['navigation']['region_id']
                ?? 0
            );

        $positionAfterMovement =
            $state['navigation']['position']
            ?? null;

        $crossedLocation =
            null;


        /*
         * We only interpret movement as a continuous path while the player
         * remains in the same Region. Region transitions will later get their
         * own explicit navigation semantics.
         */
        if (
            $regionIdBeforeTick > 0 &&
            $regionIdBeforeTick ===
                $regionIdAfterMovement
        ) {

            $crossedLocation =
                wayfarerRuntimeFindCrossedLocation(
                    $pdo,
                    (int)$row['game_id'],
                    $regionIdAfterMovement,
                    $positionBeforeTick,
                    $positionAfterMovement,
                    $state
                );
        }


        $arrivalPosition =
            null;

        if ($crossedLocation) {

            $arrivalPosition =
                $crossedLocation[
                    '_runtime_position'
                ];

            $state['navigation']['position'] =
                $arrivalPosition;


            /*
             * WAYFARER_LOCATION_ONE_TIME_EFFECT_TRIGGER_V42
             *
             * Event Effects execute once at the trigger boundary. They run
             * before the Location's Tick Effects and before Presentation Mode.
             */
            wayfarerApplyLocationEffects(
                $pdo,
                (int)$row['game_id'],
                $crossedLocation,
                $state
            );
        }


        /*
         * WAYFARER_LOCATION_EFFECTS_ONLY_RUNTIME_V43
         *
         * Locations no longer own Tick Effects. Game and Region Tick Effects
         * have already advanced the simulation; a crossed Location contributes
         * its one-time Effects and then interrupts with Presentation Mode.
         */


        if ($crossedLocation) {

            $state['navigation']['position'] =
                $arrivalPosition;

            $state['runtime']['presentation'] = [
                'type' =>
                    'location',

                'id' =>
                    (int)$crossedLocation['id'],

                'phase' =>
                    'presentation',

                'trigger' =>
                    'arrival',

                'tick' =>
                    (int)$state['runtime']['tick'],
            ];

            $state['runtime']['last_location_arrival'] = [
                'location_id' =>
                    (int)$crossedLocation['id'],

                'region_id' =>
                    $regionIdAfterMovement,

                'position' =>
                    $arrivalPosition,

                'tick' =>
                    (int)$state['runtime']['tick'],
            ];
        }


        /* WAYFARER_STATUS_LIFECYCLE_TICK_V88 */
        wayfarerRuntimeProcessStatusProgression(
            $pdo,
            (int)$row['game_id'],
            $state
        );

        /*
         * A Location presentation keeps priority for the completed travel
         * tick. Status Storylets queue behind it and are promoted as soon as
         * there is no active presentation.
         */
        wayfarerRuntimePromotePendingStatusStorylet(
            $pdo,
            (int)$row['game_id'],
            $state
        );


        /* WAYFARER_GAME_ENDINGS_AFTER_TICK_V45 */
        $ending =
            wayfarerRuntimeEvaluateGameEndings(
                $pdo,
                (int)$row['game_id'],
                $state
            );


        $state['runtime']['last_tick_at'] =
            gmdate('c');


        $encodedState =
            wayfarerRuntimeEncodeState(
                $state
            );

        $update =
            $pdo->prepare(
                "
                UPDATE wf_game_users
                SET state = ?
                WHERE id = ?
                "
            );

        $update->execute([
            $encodedState,
            $gameUserId
        ]);

        $pdo->commit();


        $presentation =
            $state['runtime']['presentation']
            ?? null;

        $pausedForPresentation =
            is_array($presentation) &&
            !empty($presentation['type']) &&
            !empty($presentation['id']);

        $ending =
            $state['runtime']['ending']
            ?? null;

        $ended =
            is_array($ending) &&
            !empty($ending['id']);


        return [
            'game_user_id' =>
                (int)$row['id'],

            'game_id' =>
                (int)$row['game_id'],

            'user_id' =>
                (int)$row['user_id'],

            'role' =>
                (string)$row['role'],

            'tick' =>
                (int)$state['runtime']['tick'],

            'state' =>
                $state,

            'context' =>
                wayfarerRuntimePlayerContext(
                    $pdo,
                    (int)$row['game_id'],
                    $state
                ),

            'pause' =>
                $pausedForPresentation ||
                $ended,

            'pause_reason' =>
                $ended
                    ? 'Game ended.'
                    : (
                        $pausedForPresentation
                            ? (
                                (string)($presentation['type'] ?? '') === 'storylet'
                                    ? 'Storylet opened.'
                                    : 'Location reached.'
                            )
                            : ''
                    ),

            'presentation' =>
                $pausedForPresentation
                    ? $presentation
                    : null,

            'ending' =>
                $ended
                    ? $ending
                    : null,

            /* WAYFARER_STORYLET_ACTIONS_TICK_API_V59 */
            'actions' =>
                !$pausedForPresentation && !$ended
                    ? wayfarerRuntimeEligibleRootManualStorylets(
                        $pdo,
                        (int)$row['game_id'],
                        $state
                    )
                    : [],

            /* WAYFARER_TRAVEL_TIME_HUD_V61 */
            'travel' =>
                wayfarerRuntimeBuildTravelStatus(
                    $pdo,
                    (int)$row['game_id'],
                    $state
                ),
        ];


    } catch (Throwable $exception) {

        if ($pdo->inTransaction()) {
            $pdo->rollBack();
        }

        throw $exception;
    }
}



==============================================================================
FILE: play/includes/scene.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Player Scene - v32
|--------------------------------------------------------------------------
|
| Read-only player-facing representation of runtime state.
|
*/

require_once __DIR__ . '/runtime.php';

if (
    !isset($pdo) ||
    !($pdo instanceof PDO)
) {
    require_once __DIR__ . '/../../config/database.php';
}


function wayfarerV17DecodeConfig($raw): array
{
    if (is_array($raw)) {
        return $raw;
    }

    if ($raw === null || $raw === '') {
        return [];
    }

    $decoded = json_decode((string)$raw, true);

    return is_array($decoded)
        ? $decoded
        : [];
}


function wayfarerV17LoadRegion(
    PDO $pdo,
    int $gameId,
    int $regionId
): ?array {

    if ($regionId <= 0) {
        return null;
    }

    $stmt = $pdo->prepare(
        "
        SELECT *
        FROM wf_regions
        WHERE id = ?
          AND game_id = ?
        LIMIT 1
        "
    );

    $stmt->execute([
        $regionId,
        $gameId,
    ]);

    $region = $stmt->fetch(PDO::FETCH_ASSOC);

    return $region ?: null;
}


function wayfarerV17LoadLocationAtPosition(
    PDO $pdo,
    int $regionId,
    $position
): ?array {

    $stmt = $pdo->prepare(
        "
        SELECT *
        FROM wf_locations
        WHERE region_id = ?
          AND status = 'active'
        ORDER BY id
        "
    );

    $stmt->execute([
        $regionId
    ]);

    $locations = $stmt->fetchAll(PDO::FETCH_ASSOC);

    foreach ($locations as $location) {

        $config = wayfarerV17DecodeConfig(
            $location['config'] ?? null
        );

        if (
            !array_key_exists('position', $config) ||
            !is_numeric($config['position'])
        ) {
            continue;
        }

        if (
            (float)$config['position'] ===
            (float)$position
        ) {
            $location['_runtime_position'] =
                $config['position'];

            return $location;
        }
    }

    return null;
}


$sceneError = '';
$sceneGameUser = null;
$sceneRegion = null;
$sceneLocation = null;
$scenePosition = 0;

try {

    $requestedGameUserId =
        isset($_GET['game_user_id'])
            ? (int)$_GET['game_user_id']
            : null;

    $sceneGameUserId =
        wayfarerRuntimeResolveGameUserId(
            $pdo,
            $requestedGameUserId
        );

    $sceneGameUser =
        wayfarerRuntimeLoad(
            $pdo,
            $sceneGameUserId
        );

    $sceneState =
        $sceneGameUser['state'];

    $sceneRegionId =
        (int)(
            $sceneState['navigation']['region_id']
            ?? 0
        );

    $scenePosition =
        $sceneState['navigation']['position']
        ?? 0;

    $sceneRegion =
        wayfarerV17LoadRegion(
            $pdo,
            (int)$sceneGameUser['game_id'],
            $sceneRegionId
        );

    if (
        $sceneRegion &&
        ($sceneRegion['navigation_type'] ?? '') === 'linear'
    ) {
        $sceneLocation =
            wayfarerV17LoadLocationAtPosition(
                $pdo,
                (int)$sceneRegion['id'],
                $scenePosition
            );
    }

} catch (Throwable $exception) {
    $sceneError =
        $exception->getMessage();
}

?>

<section
    id="wayfarer-player-scene"
    data-wayfarer-player-scene
>

<?php if ($sceneError !== ''): ?>

    <h2>Current Scene</h2>

    <p style="color:red;">
        <?= htmlspecialchars($sceneError) ?>
    </p>

<?php elseif (!$sceneRegion): ?>

    <h2>Current Scene</h2>

    <p>
        No current Region is available.
    </p>

<?php elseif ($sceneLocation): ?>

    <h2>
        <?= htmlspecialchars(
            (string)$sceneLocation['name']
        ) ?>
    </h2>

    <?php if (
        trim(
            (string)(
                $sceneLocation['description']
                ?? ''
            )
        ) !== ''
    ): ?>

        <p>
            <?= nl2br(
                htmlspecialchars(
                    (string)$sceneLocation['description']
                )
            ) ?>
        </p>

    <?php endif; ?>

    <p>
        <small>
            <?= htmlspecialchars(
                (string)$sceneRegion['name']
            ) ?>
        </small>
    </p>

<?php else: ?>

    <h2>
        <?= htmlspecialchars(
            (string)$sceneRegion['name']
        ) ?>
    </h2>

    <?php if (
        trim(
            (string)(
                $sceneRegion['description']
                ?? ''
            )
        ) !== ''
    ): ?>

        <p>
            <?= nl2br(
                htmlspecialchars(
                    (string)$sceneRegion['description']
                )
            ) ?>
        </p>

    <?php endif; ?>

    <!-- Raw navigation position is intentionally author-only. -->

<?php endif; ?>

</section>

<hr>



==============================================================================
FILE: play/includes/setup.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Runtime Starting Setup
|--------------------------------------------------------------------------
| WAYFARER_RUNTIME_STARTING_SETUP_V36
|--------------------------------------------------------------------------
*/


function wayfarerRuntimePrepareStartingSetup(
    array $gameConfig,
    int $playerSlots,
    array $setupInput
): array {

    $playerSlots =
        max(
            0,
            $playerSlots
        );

    $postedNames =
        isset($setupInput['player_names']) &&
        is_array($setupInput['player_names'])
            ? array_values(
                $setupInput['player_names']
            )
            : [];

    $playerNames = [];

    for (
        $slot = 0;
        $slot < $playerSlots;
        $slot++
    ) {
        $name =
            trim(
                (string)(
                    $postedNames[$slot]
                    ?? ''
                )
            );

        if ($name === '') {
            throw new RuntimeException(
                $playerSlots === 1
                    ? 'Enter a character name before beginning the game.'
                    : 'Enter a name for every party member before beginning the game.'
            );
        }

        $playerNames[] =
            $name;
    }


    $definitions =
        isset($gameConfig['setup']['choices']) &&
        is_array($gameConfig['setup']['choices'])
            ? array_values(
                $gameConfig['setup']['choices']
            )
            : [];

    $postedChoices =
        isset($setupInput['choices']) &&
        is_array($setupInput['choices'])
            ? $setupInput['choices']
            : [];

    $selections = [];
    $effects = [];

    foreach ($definitions as $choice) {

        if (!is_array($choice)) {
            continue;
        }

        $choiceId =
            trim(
                (string)(
                    $choice['id']
                    ?? ''
                )
            );

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

        $selectedId =
            trim(
                (string)(
                    $postedChoices[$choiceId]
                    ?? ''
                )
            );

        $required =
            !empty(
                $choice['required']
            );

        if (
            $required &&
            $selectedId === ''
        ) {
            throw new RuntimeException(
                'Choose an option for "' .
                (
                    trim(
                        (string)(
                            $choice['prompt']
                            ?? ''
                        )
                    ) ?: 'Starting Choice'
                ) .
                '".'
            );
        }

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

        $matchedOption = null;

        foreach (
            (
                isset($choice['options']) &&
                is_array($choice['options'])
                    ? $choice['options']
                    : []
            )
            as $option
        ) {
            if (
                is_array($option) &&
                (string)(
                    $option['id']
                    ?? ''
                ) ===
                    $selectedId
            ) {
                $matchedOption =
                    $option;
                break;
            }
        }

        if (!$matchedOption) {
            throw new RuntimeException(
                'A selected Starting Choice option is no longer valid.'
            );
        }

        $selections[$choiceId] =
            $selectedId;

        foreach (
            (
                isset($matchedOption['effects']) &&
                is_array($matchedOption['effects'])
                    ? $matchedOption['effects']
                    : []
            )
            as $effect
        ) {
            if (!is_array($effect)) {
                continue;
            }

            /*
             * WAYFARER_STARTING_SETUP_UNIVERSAL_TARGETS_V56
             *
             * Starting Choice Effects are authored against the same universal
             * runtime-state catalog used everywhere else. The authoring save
             * already validates the concrete target against the current Game.
             * Runtime preparation therefore validates the target ADDRESS
             * shape, not a second feature-specific whitelist.
             *
             * Definition metadata (min/max/type/display rules) is deliberately
             * not a target here. Those constraints remain internal to the
             * common runtime mutation layer.
             */
            $effectScope =
                strtolower(
                    trim(
                        (string)(
                            $effect['target_scope']
                            ?? ''
                        )
                    )
                );

            $effectType =
                strtolower(
                    trim(
                        (string)(
                            $effect['target_type']
                            ?? ''
                        )
                    )
                );

            $effectTargetId =
                trim(
                    (string)(
                        $effect['target_id']
                        ?? ''
                    )
                );

            $validEffect =
                $effectScope !== '' &&
                $effectType !== '' &&
                $effectTargetId !== '' &&
                (
                    $effectScope === 'game' ||
                    $effectScope === 'navigation' ||
                    preg_match(
                        '/^(player|region|location|entity):[0-9]+$/',
                        $effectScope
                    ) === 1 ||
                    /* Legacy pre-V56 Player selectors remain readable. */
                    $effectScope === 'player'
                );

            if (
                $validEffect &&
                $effectScope === 'player'
            ) {
                $selector =
                    strtolower(
                        trim(
                            (string)(
                                $effect['target_selector']
                                ?? ''
                            )
                        )
                    );

                if ($selector === 'all') {
                    $validEffect =
                        $playerSlots > 0;

                } elseif ($selector === 'slot') {
                    $slot =
                        filter_var(
                            $effect['target_slot']
                                ?? null,
                            FILTER_VALIDATE_INT
                        );

                    $validEffect =
                        $slot !== false &&
                        $slot >= 0 &&
                        $slot < $playerSlots;

                    if ($validEffect) {
                        $effect['target_slot'] =
                            (int)$slot;
                    }

                } else {
                    $validEffect = false;
                }
            }

            if (!$validEffect) {
                throw new RuntimeException(
                    'A Starting Choice contains an unsupported effect target.'
                );
            }

            $effects[] =
                $effect;
        }
    }


    return [
        'player_names' =>
            $playerNames,
        'choices' =>
            $selections,
        'effects' =>
            $effects,
    ];
}



==============================================================================
FILE: play/includes/start-screen.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Player Game Start Screen
|--------------------------------------------------------------------------
| WAYFARER_PLAYER_START_SCREEN_V36
|--------------------------------------------------------------------------
|
| Expected:
|   $gameUser
|   $initializationError
|
*/

$startConfig =
    wayfarerRuntimeDecodeConfig(
        $gameUser['game_config']
        ?? null
    );

$startChoices =
    isset($startConfig['setup']['choices']) &&
    is_array($startConfig['setup']['choices'])
        ? array_values(
            $startConfig['setup']['choices']
        )
        : [];

$playerSlots =
    max(
        0,
        (int)(
            $gameUser['player_slots']
            ?? 0
        )
    );

$postedNames =
    isset($_POST['player_names']) &&
    is_array($_POST['player_names'])
        ? array_values(
            $_POST['player_names']
        )
        : [];

$postedChoices =
    isset($_POST['setup_choices']) &&
    is_array($_POST['setup_choices'])
        ? $_POST['setup_choices']
        : [];

$introduction =
    trim(
        (string)(
            $gameUser['game_instructions']
            ?? ''
        )
    );

?>
<section
    class="wayfarer-start-screen"
    data-wayfarer-start-screen
>
    <header class="wayfarer-start-screen-heading">
        <h2>
            <?= htmlspecialchars(
                (string)$gameUser['game_name']
            ) ?>
        </h2>

        <?php if ($introduction !== ''): ?>
            <div class="wayfarer-start-introduction">
                <?= nl2br(
                    htmlspecialchars(
                        $introduction
                    )
                ) ?>
            </div>
        <?php endif; ?>
    </header>

    <?php if ($initializationError !== ''): ?>
        <div
            class="wayfarer-start-error"
            role="alert"
        >
            <?= htmlspecialchars(
                $initializationError
            ) ?>
        </div>
    <?php endif; ?>

    <form
        method="post"
        class="wayfarer-start-form"
    >
        <input
            type="hidden"
            name="action"
            value="initialize"
        >

        <?php if ($playerSlots > 0): ?>
            <section class="wayfarer-start-section">
                <h3>
                    <?= $playerSlots === 1
                        ? 'Name Your Character'
                        : 'Name Your Party' ?>
                </h3>

                <div class="wayfarer-start-names">
                    <?php for (
                        $slot = 0;
                        $slot < $playerSlots;
                        $slot++
                    ): ?>
                        <label>
                            <span>
                                <?= $playerSlots === 1
                                    ? 'Name'
                                    : 'Name ' . ($slot + 1) ?>
                            </span>

                            <input
                                type="text"
                                name="player_names[]"
                                value="<?= htmlspecialchars(
                                    (string)(
                                        $postedNames[$slot]
                                        ?? ''
                                    ),
                                    ENT_QUOTES,
                                    'UTF-8'
                                ) ?>"
                                required
                            >
                        </label>
                    <?php endfor; ?>
                </div>
            </section>
        <?php endif; ?>

        <?php foreach (
            $startChoices
            as $choice
        ): ?>

            <?php
            if (!is_array($choice)) {
                continue;
            }

            $choiceId =
                (string)(
                    $choice['id']
                    ?? ''
                );

            $prompt =
                trim(
                    (string)(
                        $choice['prompt']
                        ?? ''
                    )
                );

            $options =
                isset($choice['options']) &&
                is_array($choice['options'])
                    ? array_values(
                        $choice['options']
                    )
                    : [];

            if (
                $choiceId === '' ||
                $prompt === '' ||
                $options === []
            ) {
                continue;
            }

            $selectedOption =
                (string)(
                    $postedChoices[$choiceId]
                    ?? ''
                );

            $required =
                !empty(
                    $choice['required']
                );
            ?>

            <fieldset class="wayfarer-start-choice">
                <legend>
                    <?= htmlspecialchars(
                        $prompt
                    ) ?>
                </legend>

                <?php if (!$required): ?>
                    <label class="wayfarer-start-option">
                        <input
                            type="radio"
                            name="setup_choices[<?= htmlspecialchars(
                                $choiceId,
                                ENT_QUOTES,
                                'UTF-8'
                            ) ?>]"
                            value=""
                            <?= $selectedOption === ''
                                ? 'checked'
                                : '' ?>
                        >

                        <span class="wayfarer-start-option-copy">
                            <strong>No selection</strong>
                        </span>
                    </label>
                <?php endif; ?>

                <?php foreach (
                    $options
                    as $optionIndex => $option
                ): ?>

                    <?php
                    if (!is_array($option)) {
                        continue;
                    }

                    $optionId =
                        (string)(
                            $option['id']
                            ?? ''
                        );

                    $label =
                        trim(
                            (string)(
                                $option['label']
                                ?? ''
                            )
                        );

                    if (
                        $optionId === '' ||
                        $label === ''
                    ) {
                        continue;
                    }

                    $description =
                        trim(
                            (string)(
                                $option['description']
                                ?? ''
                            )
                        );
                    ?>

                    <label class="wayfarer-start-option">
                        <input
                            type="radio"
                            name="setup_choices[<?= htmlspecialchars(
                                $choiceId,
                                ENT_QUOTES,
                                'UTF-8'
                            ) ?>]"
                            value="<?= htmlspecialchars(
                                $optionId,
                                ENT_QUOTES,
                                'UTF-8'
                            ) ?>"
                            <?= $selectedOption === $optionId
                                ? 'checked'
                                : '' ?>
                            <?= $required &&
                                $optionIndex === 0
                                    ? 'required'
                                    : '' ?>
                        >

                        <span class="wayfarer-start-option-copy">
                            <strong>
                                <?= htmlspecialchars(
                                    $label
                                ) ?>
                            </strong>

                            <?php if ($description !== ''): ?>
                                <span>
                                    <?= nl2br(
                                        htmlspecialchars(
                                            $description
                                        )
                                    ) ?>
                                </span>
                            <?php endif; ?>
                        </span>
                    </label>

                <?php endforeach; ?>
            </fieldset>

        <?php endforeach; ?>

        <div class="wayfarer-start-actions">
            <button
                type="submit"
                class="wayfarer-start-button"
            >
                Begin Game
            </button>
        </div>
    </form>
</section>



==============================================================================
FILE: play/includes/statuses.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Party-member Status runtime
| WAYFARER_STATUSES_RUNTIME_V87
| WAYFARER_STATUS_LIFECYCLE_RUNTIME_V88
| WAYFARER_STATUS_SUBJECT_EFFECTS_RUNTIME_V89
|--------------------------------------------------------------------------
|
| Status definitions are authored once at the Game level. Runtime ownership
| lives on one Player Character or Character Entity. An absent Status record
| is equivalent to inactive.
|
| V88 adds optional timed stages. Each active Status instance owns its own
| stage timer and next_check_tick, so multiple characters may progress through
| the same authored Status independently.
|
*/

function wayfarerRuntimeStatusNormalizeBoolean($value): bool
{
    if (is_bool($value)) {
        return $value;
    }

    if (is_numeric($value)) {
        return (float)$value > 0;
    }

    return in_array(
        strtolower(trim((string)$value)),
        ['1', 'true', 'yes', 'on', 'active'],
        true
    );
}


function wayfarerRuntimeStatusDefinitions(
    PDO $pdo,
    int $gameId,
    bool $activeOnly = true
): array {
    if ($gameId <= 0) {
        return [];
    }

    $sql = "
        SELECT
            id,
            name,
            description,
            config,
            status
        FROM wf_statuses
        WHERE game_id = ?
    ";

    if ($activeOnly) {
        $sql .= " AND status = 'active'";
    }

    $sql .= " ORDER BY name, id";

    $stmt = $pdo->prepare($sql);
    $stmt->execute([$gameId]);

    $definitions = [];

    foreach ($stmt->fetchAll(PDO::FETCH_ASSOC) as $row) {
        $id = (int)($row['id'] ?? 0);
        if ($id <= 0) {
            continue;
        }

        $config = [];
        if (!empty($row['config'])) {
            $decoded = json_decode((string)$row['config'], true);
            if (is_array($decoded)) {
                $config = $decoded;
            }
        }

        $showToPlayer = !array_key_exists('show_to_player', $config) ||
            wayfarerRuntimeStatusNormalizeBoolean($config['show_to_player']);

        $showStageToPlayer = !array_key_exists('show_stage_to_player', $config) ||
            wayfarerRuntimeStatusNormalizeBoolean($config['show_stage_to_player']);

        $showTimeRemaining = array_key_exists('show_time_remaining', $config) &&
            wayfarerRuntimeStatusNormalizeBoolean($config['show_time_remaining']);

        $lifecycle = isset($config['lifecycle']) && is_array($config['lifecycle'])
            ? $config['lifecycle']
            : null;

        $definitions[(string)$id] = [
            'id' => $id,
            'name' => trim((string)($row['name'] ?? ('Status ' . $id))),
            'description' => trim((string)($row['description'] ?? '')),
            'status' => strtolower(trim((string)($row['status'] ?? 'draft'))),
            'show_to_player' => $showToPlayer,
            'show_stage_to_player' => $showStageToPlayer,
            'show_time_remaining' => $showTimeRemaining,
            'lifecycle' => $lifecycle,
        ];
    }

    return $definitions;
}


function wayfarerRuntimeStatusDefinition(
    PDO $pdo,
    int $gameId,
    int $statusId,
    bool $activeOnly = true
): ?array {
    if ($statusId <= 0) {
        return null;
    }

    $definitions = wayfarerRuntimeStatusDefinitions(
        $pdo,
        $gameId,
        $activeOnly
    );

    return $definitions[(string)$statusId] ?? null;
}


function wayfarerRuntimeStatusScopeAddress(
    array $runtimeState,
    string $scope
): ?array {
    $scope = strtolower(trim($scope));

    if (
        preg_match('/^player:([0-9]+)$/', $scope, $match) === 1
    ) {
        $key = (string)((int)$match[1]);
        if (!isset($runtimeState['players'][$key]) ||
            !is_array($runtimeState['players'][$key])) {
            return null;
        }

        return [
            'bucket' => 'players',
            'key' => $key,
        ];
    }

    if (
        preg_match('/^entity:([1-9][0-9]*)$/', $scope, $match) === 1
    ) {
        $key = (string)((int)$match[1]);
        if (!isset($runtimeState['entities'][$key]) ||
            !is_array($runtimeState['entities'][$key])) {
            return null;
        }

        return [
            'bucket' => 'entities',
            'key' => $key,
        ];
    }

    return null;
}


function wayfarerRuntimeStatusState(
    array $runtimeState,
    string $scope,
    int $statusId
): array {
    $address = wayfarerRuntimeStatusScopeAddress(
        $runtimeState,
        $scope
    );

    if ($address === null || $statusId <= 0) {
        return [
            'found_owner' => false,
            'active' => false,
            'started_tick' => null,
            'stage_key' => null,
            'stage_started_tick' => null,
            'duration_ticks' => null,
            'next_check_tick' => null,
        ];
    }

    $stored =
        $runtimeState[$address['bucket']][$address['key']]['statuses'][(string)$statusId]
        ?? null;

    if (!is_array($stored)) {
        return [
            'found_owner' => true,
            'active' => false,
            'started_tick' => null,
            'stage_key' => null,
            'stage_started_tick' => null,
            'duration_ticks' => null,
            'next_check_tick' => null,
        ];
    }

    return [
        'found_owner' => true,
        'active' => !empty($stored['active']),
        'started_tick' => isset($stored['started_tick']) &&
            is_numeric($stored['started_tick'])
                ? (int)$stored['started_tick']
                : null,
        'stage_key' => trim((string)($stored['stage_key'] ?? '')) !== ''
            ? trim((string)$stored['stage_key'])
            : null,
        'stage_started_tick' => isset($stored['stage_started_tick']) &&
            is_numeric($stored['stage_started_tick'])
                ? (int)$stored['stage_started_tick']
                : null,
        'duration_ticks' => isset($stored['duration_ticks']) &&
            is_numeric($stored['duration_ticks'])
                ? (int)$stored['duration_ticks']
                : null,
        'next_check_tick' => isset($stored['next_check_tick']) &&
            is_numeric($stored['next_check_tick'])
                ? (int)$stored['next_check_tick']
                : null,
    ];
}


function wayfarerRuntimeSetStatus(
    array &$runtimeState,
    string $scope,
    int $statusId,
    bool $active
): array {
    $address = wayfarerRuntimeStatusScopeAddress(
        $runtimeState,
        $scope
    );

    if ($address === null || $statusId <= 0) {
        return [
            'applied' => false,
            'before' => null,
            'after' => null,
            'started_tick' => null,
            'error' => 'Status owner was not found in runtime state.',
        ];
    }

    $bucket = $address['bucket'];
    $key = $address['key'];

    if (!isset($runtimeState[$bucket][$key]['statuses']) ||
        !is_array($runtimeState[$bucket][$key]['statuses'])) {
        $runtimeState[$bucket][$key]['statuses'] = [];
    }

    $statusKey = (string)$statusId;
    $existing =
        $runtimeState[$bucket][$key]['statuses'][$statusKey]
        ?? [];

    if (!is_array($existing)) {
        $existing = [];
    }

    $before = !empty($existing['active']);
    $startedTick =
        isset($existing['started_tick']) &&
        is_numeric($existing['started_tick'])
            ? (int)$existing['started_tick']
            : null;

    if ($active && !$before) {
        $startedTick = (int)(
            $runtimeState['runtime']['tick']
            ?? 0
        );

        unset(
            $existing['stage_key'],
            $existing['stage_started_tick'],
            $existing['duration_ticks'],
            $existing['next_check_tick'],
            $existing['stage_effect_ticks'],
            $existing['last_outcome_key'],
            $existing['last_outcome_tick']
        );
    }

    $existing['active'] = $active;
    $existing['started_tick'] = $startedTick;

    $runtimeState[$bucket][$key]['statuses'][$statusKey] = $existing;

    return [
        'applied' => true,
        'before' => $before ? 1 : 0,
        'after' => $active ? 1 : 0,
        'started_tick' => $startedTick,
        'error' => '',
    ];
}


/*
|--------------------------------------------------------------------------
| Timed lifecycle helpers
| WAYFARER_STATUS_LIFECYCLE_RUNTIME_V88
|--------------------------------------------------------------------------
*/

function wayfarerRuntimeStatusLifecycleStages(
    array $definition
): array {
    $lifecycle = isset($definition['lifecycle']) && is_array($definition['lifecycle'])
        ? $definition['lifecycle']
        : [];

    if (
        strtolower(trim((string)($lifecycle['mode'] ?? 'manual'))) !== 'progression' ||
        !isset($lifecycle['stages']) ||
        !is_array($lifecycle['stages'])
    ) {
        return [];
    }

    $stages = [];
    foreach (array_values($lifecycle['stages']) as $stage) {
        if (!is_array($stage)) {
            continue;
        }

        $key = strtolower(trim((string)($stage['key'] ?? '')));
        if ($key === '') {
            continue;
        }

        $stage['key'] = $key;
        $stages[] = $stage;
    }

    return $stages;
}


function wayfarerRuntimeStatusLifecycleStageMap(
    array $definition
): array {
    $map = [];

    foreach (wayfarerRuntimeStatusLifecycleStages($definition) as $stage) {
        $map[(string)$stage['key']] = $stage;
    }

    return $map;
}


function wayfarerRuntimeStatusRollDuration(
    array $stage
): int {
    $duration = isset($stage['duration']) && is_array($stage['duration'])
        ? $stage['duration']
        : [];

    $mode = strtolower(trim((string)($duration['mode'] ?? 'fixed')));

    if ($mode === 'random') {
        $min = max(1, (int)($duration['min'] ?? 1));
        $max = max($min, (int)($duration['max'] ?? $min));
        return random_int($min, $max);
    }

    return max(1, (int)($duration['value'] ?? 1));
}


function wayfarerRuntimeStatusInitializeLifecycle(
    array &$runtimeState,
    string $scope,
    int $statusId,
    array $definition
): array {
    $address = wayfarerRuntimeStatusScopeAddress($runtimeState, $scope);
    $stages = wayfarerRuntimeStatusLifecycleStages($definition);

    if ($address === null || $statusId <= 0 || $stages === []) {
        return [
            'initialized' => false,
            'error' => '',
        ];
    }

    $bucket = $address['bucket'];
    $key = $address['key'];
    $statusKey = (string)$statusId;
    $stored = $runtimeState[$bucket][$key]['statuses'][$statusKey] ?? null;

    if (!is_array($stored) || empty($stored['active'])) {
        return [
            'initialized' => false,
            'error' => '',
        ];
    }

    $stageMap = wayfarerRuntimeStatusLifecycleStageMap($definition);
    $stageKey = strtolower(trim((string)($stored['stage_key'] ?? '')));
    $entered = false;

    if ($stageKey === '' || !isset($stageMap[$stageKey])) {
        $entered = true;
        $stageKey = (string)$stages[0]['key'];
        $stored['stage_key'] = $stageKey;
        $stored['stage_started_tick'] = isset($stored['started_tick']) &&
            is_numeric($stored['started_tick'])
                ? (int)$stored['started_tick']
                : (int)($runtimeState['runtime']['tick'] ?? 0);
        unset(
            $stored['duration_ticks'],
            $stored['next_check_tick'],
            $stored['stage_effect_ticks']
        );
    }

    if (
        !isset($stored['stage_started_tick']) ||
        !is_numeric($stored['stage_started_tick'])
    ) {
        $stored['stage_started_tick'] = (int)(
            $runtimeState['runtime']['tick']
            ?? 0
        );
    }

    if (
        !isset($stored['duration_ticks']) ||
        !is_numeric($stored['duration_ticks']) ||
        (int)$stored['duration_ticks'] < 1
    ) {
        $stored['duration_ticks'] =
            wayfarerRuntimeStatusRollDuration(
                $stageMap[$stageKey]
            );
    }

    if (
        !isset($stored['next_check_tick']) ||
        !is_numeric($stored['next_check_tick'])
    ) {
        $stored['next_check_tick'] =
            (int)$stored['stage_started_tick'] +
            (int)$stored['duration_ticks'];
    }

    $runtimeState[$bucket][$key]['statuses'][$statusKey] = $stored;

    return [
        'initialized' => true,
        'entered' => $entered,
        'stage_key' => $stageKey,
        'stage_started_tick' => (int)$stored['stage_started_tick'],
        'duration_ticks' => (int)$stored['duration_ticks'],
        'next_check_tick' => (int)$stored['next_check_tick'],
        'error' => '',
    ];
}


function wayfarerRuntimeStatusEnterStage(
    array &$runtimeState,
    string $scope,
    int $statusId,
    array $definition,
    string $stageKey
): array {
    $address = wayfarerRuntimeStatusScopeAddress($runtimeState, $scope);
    $stageMap = wayfarerRuntimeStatusLifecycleStageMap($definition);
    $stageKey = strtolower(trim($stageKey));

    if (
        $address === null ||
        $statusId <= 0 ||
        $stageKey === '' ||
        !isset($stageMap[$stageKey])
    ) {
        return [
            'applied' => false,
            'error' => 'Status Stage could not be resolved.',
        ];
    }

    $bucket = $address['bucket'];
    $key = $address['key'];
    $statusKey = (string)$statusId;
    $stored = $runtimeState[$bucket][$key]['statuses'][$statusKey] ?? [];
    if (!is_array($stored)) {
        $stored = [];
    }

    $tick = (int)($runtimeState['runtime']['tick'] ?? 0);
    $duration = wayfarerRuntimeStatusRollDuration($stageMap[$stageKey]);

    $stored['active'] = true;
    if (!isset($stored['started_tick']) || !is_numeric($stored['started_tick'])) {
        $stored['started_tick'] = $tick;
    }
    $stored['stage_key'] = $stageKey;
    $stored['stage_started_tick'] = $tick;
    $stored['duration_ticks'] = $duration;
    $stored['next_check_tick'] = $tick + $duration;
    $stored['stage_effect_ticks'] = [];

    $runtimeState[$bucket][$key]['statuses'][$statusKey] = $stored;

    return [
        'applied' => true,
        'stage_key' => $stageKey,
        'stage_started_tick' => $tick,
        'duration_ticks' => $duration,
        'next_check_tick' => $tick + $duration,
        'error' => '',
    ];
}


function wayfarerRuntimeStatusChooseOutcome(
    array $stage
): ?array {
    $outcomes = isset($stage['outcomes']) && is_array($stage['outcomes'])
        ? array_values($stage['outcomes'])
        : [];

    if ($outcomes === []) {
        return null;
    }

    $roll = random_int(1, 100);
    $cursor = 0;

    foreach ($outcomes as $outcome) {
        if (!is_array($outcome)) {
            continue;
        }

        $chance = max(0, (int)($outcome['chance'] ?? 0));
        $cursor += $chance;

        if ($roll <= $cursor) {
            $outcome['_runtime_roll'] = $roll;
            return $outcome;
        }
    }

    return null;
}


/*
|--------------------------------------------------------------------------
| Status Subject Effects
| WAYFARER_STATUS_SUBJECT_EFFECTS_RUNTIME_V89
|--------------------------------------------------------------------------
*/
function wayfarerRuntimeStatusResolveSubjectTrait(
    array $runtimeState,
    array $traitDefinitions,
    string $scope,
    string $logicalTargetId
): array {
    if (!function_exists('wayfarerRuntimePartyDecodeTraitTargetId') ||
        !function_exists('wayfarerRuntimePartyFindTraitDefinition')) {
        return [
            'found' => false,
            'error' => 'Status Subject Trait resolver is unavailable.',
        ];
    }

    $normalizedName = wayfarerRuntimePartyDecodeTraitTargetId(
        $logicalTargetId
    );

    if ($normalizedName === null) {
        return [
            'found' => false,
            'error' => 'Status Subject Trait target is invalid.',
        ];
    }

    $definitions = [];
    $bucket = '';
    $key = '';

    if (preg_match('/^player:([0-9]+)$/', $scope, $match) === 1) {
        $bucket = 'players';
        $key = (string)((int)$match[1]);
        $definitions = isset($traitDefinitions['player']) &&
            is_array($traitDefinitions['player'])
                ? $traitDefinitions['player']
                : [];
    } elseif (preg_match('/^entity:([1-9][0-9]*)$/', $scope, $match) === 1) {
        $bucket = 'entities';
        $key = (string)((int)$match[1]);
        $definitions = isset($traitDefinitions['entities'][$key]) &&
            is_array($traitDefinitions['entities'][$key])
                ? $traitDefinitions['entities'][$key]
                : [];
    } else {
        return [
            'found' => false,
            'error' => 'Status Subject scope is not a character.',
        ];
    }

    $match = wayfarerRuntimePartyFindTraitDefinition(
        $definitions,
        $normalizedName
    );

    if (!is_array($match)) {
        return [
            'found' => false,
            'error' => 'Status Subject does not expose the selected Trait.',
        ];
    }

    $traitId = trim((string)($match['id'] ?? ''));
    $definition = isset($match['definition']) && is_array($match['definition'])
        ? $match['definition']
        : null;

    if (
        $traitId === '' ||
        !isset($runtimeState[$bucket][$key]['traits']) ||
        !is_array($runtimeState[$bucket][$key]['traits']) ||
        !array_key_exists($traitId, $runtimeState[$bucket][$key]['traits'])
    ) {
        return [
            'found' => false,
            'error' => 'Status Subject runtime Trait was not found.',
        ];
    }

    return [
        'found' => true,
        'trait_id' => $traitId,
        'definition' => $definition,
        'before' => $runtimeState[$bucket][$key]['traits'][$traitId],
        'error' => '',
    ];
}


function wayfarerRuntimeStatusApplySubjectEffect(
    array &$runtimeState,
    array $effect,
    string $scope,
    int $currentRegionId,
    array $traitDefinitions
): array {
    $targetId = trim((string)($effect['target_id'] ?? ''));
    $operation = strtolower(trim((string)($effect['operation'] ?? '')));

    $resolution = wayfarerRuntimeStatusResolveSubjectTrait(
        $runtimeState,
        $traitDefinitions,
        $scope,
        $targetId
    );

    if (empty($resolution['found'])) {
        return [
            'scope' => $scope,
            'trait_name' => (string)($effect['trait_name'] ?? ''),
            'logical_target_id' => $targetId,
            'operation' => $operation,
            'applied' => false,
            'error' => (string)($resolution['error'] ?? 'Status Subject Trait was not found.'),
        ];
    }

    $rolled = function_exists('wayfarerRuntimeRollEffectValue')
        ? wayfarerRuntimeRollEffectValue($effect)
        : [
            'valid' => true,
            'value' => $effect['value'] ?? 0,
            'mode' => 'fixed',
            'error' => '',
        ];

    if (empty($rolled['valid'])) {
        return [
            'scope' => $scope,
            'trait_name' => (string)($effect['trait_name'] ?? ''),
            'logical_target_id' => $targetId,
            'operation' => $operation,
            'applied' => false,
            'error' => (string)($rolled['error'] ?? 'Status Effect value could not be resolved.'),
        ];
    }

    $authoredValue = $rolled['value'] ?? 0;
    $resolvedOperation = $operation;
    $resolvedValue = $authoredValue;
    $definition = isset($resolution['definition']) && is_array($resolution['definition'])
        ? $resolution['definition']
        : null;

    if (
        in_array(
            $operation,
            ['subtract_percent_current', 'subtract_percent_max', 'add_percent_max'],
            true
        )
    ) {
        if (!is_numeric($authoredValue)) {
            return [
                'scope' => $scope,
                'trait_name' => (string)($effect['trait_name'] ?? ''),
                'logical_target_id' => $targetId,
                'operation' => $operation,
                'applied' => false,
                'error' => 'Status percentage Effect requires a numeric percentage.',
            ];
        }

        $percentage = (float)$authoredValue;
        if ($percentage < 0) {
            return [
                'scope' => $scope,
                'trait_name' => (string)($effect['trait_name'] ?? ''),
                'logical_target_id' => $targetId,
                'operation' => $operation,
                'applied' => false,
                'error' => 'Status percentage Effect cannot use a negative percentage.',
            ];
        }

        if ($operation === 'subtract_percent_current') {
            if (!is_numeric($resolution['before'] ?? null)) {
                return [
                    'scope' => $scope,
                    'trait_name' => (string)($effect['trait_name'] ?? ''),
                    'logical_target_id' => $targetId,
                    'operation' => $operation,
                    'applied' => false,
                    'error' => 'Subtract % of Current requires a numeric current Trait value.',
                ];
            }

            $resolvedOperation = 'subtract';
            $resolvedValue = wayfarerNormalizeRuntimeNumber(
                ((float)$resolution['before'] * $percentage) / 100
            );
        } else {
            $maximum = is_array($definition)
                ? ($definition['max'] ?? null)
                : null;

            if (!is_numeric($maximum)) {
                return [
                    'scope' => $scope,
                    'trait_name' => (string)($effect['trait_name'] ?? ''),
                    'logical_target_id' => $targetId,
                    'operation' => $operation,
                    'applied' => false,
                    'error' => 'Percentage of Maximum requires the Status Subject Trait to have a numeric Maximum.',
                ];
            }

            $resolvedOperation = $operation === 'add_percent_max'
                ? 'add'
                : 'subtract';
            $resolvedValue = wayfarerNormalizeRuntimeNumber(
                ((float)$maximum * $percentage) / 100
            );
        }
    }

    $runtimeEffect = [
        'target_scope' => $scope,
        'target_type' => 'trait',
        'target_id' => (string)$resolution['trait_id'],
        'operation' => $resolvedOperation,
        'value' => $resolvedValue,
    ];

    $report = wayfarerApplyRuntimeEffect(
        $runtimeState,
        $runtimeEffect,
        $currentRegionId,
        $traitDefinitions
    );

    $report['status_effect_key'] = (string)($effect['key'] ?? '');
    $report['status_subject_scope'] = $scope;
    $report['trait_name'] = (string)($effect['trait_name'] ?? '');
    $report['logical_target_id'] = $targetId;
    $report['authored_operation'] = $operation;
    $report['authored_value'] = $authoredValue;
    $report['resolved_operation'] = $resolvedOperation;
    $report['resolved_value'] = $resolvedValue;

    return $report;
}


function wayfarerRuntimeStatusApplySubjectEffects(
    array &$runtimeState,
    array $effects,
    string $scope,
    int $currentRegionId,
    array $traitDefinitions
): array {
    $reports = [];

    foreach ($effects as $effect) {
        if (!is_array($effect)) {
            continue;
        }

        $reports[] = wayfarerRuntimeStatusApplySubjectEffect(
            $runtimeState,
            $effect,
            $scope,
            $currentRegionId,
            $traitDefinitions
        );
    }

    return $reports;
}


function wayfarerRuntimeStatusApplyRecurringEffects(
    array &$runtimeState,
    string $scope,
    int $statusId,
    array $stage,
    int $tick,
    int $currentRegionId,
    array $traitDefinitions
): array {
    $effects = isset($stage['tick_effects']) && is_array($stage['tick_effects'])
        ? array_values($stage['tick_effects'])
        : [];

    if ($effects === []) {
        return [];
    }

    $address = wayfarerRuntimeStatusScopeAddress($runtimeState, $scope);
    if ($address === null) {
        return [];
    }

    $statusKey = (string)$statusId;
    $stored =& $runtimeState[$address['bucket']][$address['key']]['statuses'][$statusKey];
    if (!is_array($stored) || empty($stored['active'])) {
        unset($stored);
        return [];
    }

    $stageStartedTick = isset($stored['stage_started_tick']) &&
        is_numeric($stored['stage_started_tick'])
            ? (int)$stored['stage_started_tick']
            : $tick;
    $elapsed = $tick - $stageStartedTick;

    if ($elapsed <= 0) {
        unset($stored);
        return [];
    }

    if (!isset($stored['stage_effect_ticks']) || !is_array($stored['stage_effect_ticks'])) {
        $stored['stage_effect_ticks'] = [];
    }

    $reports = [];

    foreach ($effects as $effect) {
        if (!is_array($effect)) {
            continue;
        }

        $interval = max(1, (int)($effect['interval_ticks'] ?? 1));
        if ($elapsed % $interval !== 0) {
            continue;
        }

        $effectKey = trim((string)($effect['key'] ?? ''));
        if ($effectKey === '') {
            continue;
        }

        if (
            isset($stored['stage_effect_ticks'][$effectKey]) &&
            (int)$stored['stage_effect_ticks'][$effectKey] === $tick
        ) {
            continue;
        }

        $report = wayfarerRuntimeStatusApplySubjectEffect(
            $runtimeState,
            $effect,
            $scope,
            $currentRegionId,
            $traitDefinitions
        );
        $report['interval_ticks'] = $interval;
        $report['elapsed_stage_ticks'] = $elapsed;
        $reports[] = $report;

        $stored['stage_effect_ticks'][$effectKey] = $tick;
    }

    unset($stored);
    return $reports;
}


function wayfarerRuntimeQueueStatusStorylet(
    array &$runtimeState,
    array $event
): void {
    if (!isset($runtimeState['runtime']) || !is_array($runtimeState['runtime'])) {
        $runtimeState['runtime'] = [];
    }

    if (
        !isset($runtimeState['runtime']['pending_status_storylets']) ||
        !is_array($runtimeState['runtime']['pending_status_storylets'])
    ) {
        $runtimeState['runtime']['pending_status_storylets'] = [];
    }

    $runtimeState['runtime']['pending_status_storylets'][] = $event;
}


function wayfarerRuntimePromotePendingStatusStorylet(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): ?array {
    if (
        isset($runtimeState['runtime']['presentation']) &&
        is_array($runtimeState['runtime']['presentation'])
    ) {
        return null;
    }

    if (
        !isset($runtimeState['runtime']['pending_status_storylets']) ||
        !is_array($runtimeState['runtime']['pending_status_storylets']) ||
        $runtimeState['runtime']['pending_status_storylets'] === []
    ) {
        return null;
    }

    while ($runtimeState['runtime']['pending_status_storylets'] !== []) {
        $event = array_shift(
            $runtimeState['runtime']['pending_status_storylets']
        );

        if (!is_array($event)) {
            continue;
        }

        $storyletId = (int)($event['storylet_id'] ?? 0);
        $subjectScope = strtolower(trim((string)($event['subject_scope'] ?? '')));

        if ($storyletId <= 0 || $subjectScope === '') {
            continue;
        }

        try {
            $storylet = wayfarerRuntimeLoadStorylet(
                $pdo,
                $gameId,
                $storyletId
            );

            if (!$storylet) {
                throw new RuntimeException(
                    'Status Outcome Storylet could not be loaded.'
                );
            }

            $subjectResult =
                wayfarerRuntimeStoryletPresetCharacterBinding(
                    $pdo,
                    $gameId,
                    $storylet,
                    $runtimeState,
                    $subjectScope,
                    'subject',
                    'Subject'
                );

            if (($subjectResult['error'] ?? '') !== '') {
                throw new RuntimeException(
                    (string)$subjectResult['error']
                );
            }

            $binding = $subjectResult['binding'] ?? null;
            if (!is_array($binding)) {
                throw new RuntimeException(
                    'Status Outcome Storylet subject could not be prepared.'
                );
            }

            $result =
                wayfarerRuntimeEnterTriggeredStoryletInState(
                    $pdo,
                    $gameId,
                    $storyletId,
                    $runtimeState,
                    [
                        'subject' => $binding,
                    ],
                    'status'
                );

            $runtimeState['runtime']['last_status_storylet'] = [
                'storylet_id' => $storyletId,
                'subject_scope' => $subjectScope,
                'status_id' => (int)($event['status_id'] ?? 0),
                'outcome_key' => (string)($event['outcome_key'] ?? ''),
                'tick' => (int)($runtimeState['runtime']['tick'] ?? 0),
            ];

            if ($runtimeState['runtime']['pending_status_storylets'] === []) {
                unset($runtimeState['runtime']['pending_status_storylets']);
            }

            return $result;

        } catch (Throwable $exception) {
            $runtimeState['runtime']['last_status_storylet_error'] = [
                'storylet_id' => $storyletId,
                'subject_scope' => $subjectScope,
                'message' => $exception->getMessage(),
                'tick' => (int)($runtimeState['runtime']['tick'] ?? 0),
            ];
        }
    }

    unset($runtimeState['runtime']['pending_status_storylets']);
    return null;
}


function wayfarerRuntimeProcessStatusProgression(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): array {
    $definitions = wayfarerRuntimeStatusDefinitions(
        $pdo,
        $gameId,
        true
    );

    if ($definitions === []) {
        return [];
    }

    $tick = (int)($runtimeState['runtime']['tick'] ?? 0);
    $currentRegionId = (int)($runtimeState['navigation']['region_id'] ?? 0);
    $traitDefinitions = function_exists('wayfarerRuntimeLoadTickTraitDefinitions')
        ? wayfarerRuntimeLoadTickTraitDefinitions($pdo, $gameId, [])
        : [];
    $reports = [];

    $owners = [];

    foreach (
        isset($runtimeState['players']) && is_array($runtimeState['players'])
            ? $runtimeState['players']
            : []
        as $playerKey => $playerState
    ) {
        if (is_array($playerState)) {
            $owners[] = 'player:' . (string)$playerKey;
        }
    }

    foreach (
        isset($runtimeState['entities']) && is_array($runtimeState['entities'])
            ? $runtimeState['entities']
            : []
        as $entityKey => $entityState
    ) {
        if (is_array($entityState)) {
            $owners[] = 'entity:' . (string)$entityKey;
        }
    }

    foreach ($owners as $scope) {
        $address = wayfarerRuntimeStatusScopeAddress($runtimeState, $scope);
        if ($address === null) {
            continue;
        }

        $storedStatuses =
            $runtimeState[$address['bucket']][$address['key']]['statuses']
            ?? [];

        if (!is_array($storedStatuses) || $storedStatuses === []) {
            continue;
        }

        foreach (array_keys($storedStatuses) as $statusKey) {
            $statusId = (int)$statusKey;
            $definition = $definitions[(string)$statusId] ?? null;

            if (!is_array($definition)) {
                continue;
            }

            if (wayfarerRuntimeStatusLifecycleStages($definition) === []) {
                continue;
            }

            $init = wayfarerRuntimeStatusInitializeLifecycle(
                $runtimeState,
                $scope,
                $statusId,
                $definition
            );

            if (empty($init['initialized'])) {
                continue;
            }

            $state = wayfarerRuntimeStatusState(
                $runtimeState,
                $scope,
                $statusId
            );

            if (empty($state['active'])) {
                continue;
            }

            $stageMap = wayfarerRuntimeStatusLifecycleStageMap($definition);
            $stageKey = (string)($state['stage_key'] ?? '');
            $stage = $stageMap[$stageKey] ?? null;

            if (!is_array($stage)) {
                continue;
            }

            $entryEffectReports = [];
            if (!empty($init['entered'])) {
                $entryEffectReports = wayfarerRuntimeStatusApplySubjectEffects(
                    $runtimeState,
                    isset($stage['entry_effects']) && is_array($stage['entry_effects'])
                        ? array_values($stage['entry_effects'])
                        : [],
                    $scope,
                    $currentRegionId,
                    $traitDefinitions
                );
            }

            $tickEffectReports = wayfarerRuntimeStatusApplyRecurringEffects(
                $runtimeState,
                $scope,
                $statusId,
                $stage,
                $tick,
                $currentRegionId,
                $traitDefinitions
            );

            if (
                $state['next_check_tick'] === null ||
                (int)$state['next_check_tick'] > $tick
            ) {
                if ($entryEffectReports !== [] || $tickEffectReports !== []) {
                    $reports[] = [
                        'event' => 'stage_effects',
                        'scope' => $scope,
                        'status_id' => $statusId,
                        'status_name' => (string)($definition['name'] ?? ''),
                        'stage_key' => $stageKey,
                        'stage_name' => (string)($stage['name'] ?? $stageKey),
                        'entry_effects' => $entryEffectReports,
                        'tick_effects' => $tickEffectReports,
                        'tick' => $tick,
                    ];
                }
                continue;
            }

            $outcome = wayfarerRuntimeStatusChooseOutcome($stage);
            if (!is_array($outcome)) {
                continue;
            }

            /* Outcome Effects apply before the Result changes the Status Stage. */
            $outcomeEffectReports = wayfarerRuntimeStatusApplySubjectEffects(
                $runtimeState,
                isset($outcome['effects']) && is_array($outcome['effects'])
                    ? array_values($outcome['effects'])
                    : [],
                $scope,
                $currentRegionId,
                $traitDefinitions
            );

            $result = strtolower(trim((string)($outcome['result'] ?? 'inactive')));
            $resultError = '';
            $nextEntryEffectReports = [];

            if ($result === 'inactive') {
                $statusResult = wayfarerRuntimeSetStatus(
                    $runtimeState,
                    $scope,
                    $statusId,
                    false
                );
                $resultError = (string)($statusResult['error'] ?? '');
            } elseif ($result === 'stay') {
                $stageResult = wayfarerRuntimeStatusEnterStage(
                    $runtimeState,
                    $scope,
                    $statusId,
                    $definition,
                    $stageKey
                );
                $resultError = (string)($stageResult['error'] ?? '');

                if ($resultError === '') {
                    $nextEntryEffectReports = wayfarerRuntimeStatusApplySubjectEffects(
                        $runtimeState,
                        isset($stage['entry_effects']) && is_array($stage['entry_effects'])
                            ? array_values($stage['entry_effects'])
                            : [],
                        $scope,
                        $currentRegionId,
                        $traitDefinitions
                    );
                }
            } elseif (strpos($result, 'stage:') === 0) {
                $nextStageKey = substr($result, 6);
                $stageResult = wayfarerRuntimeStatusEnterStage(
                    $runtimeState,
                    $scope,
                    $statusId,
                    $definition,
                    $nextStageKey
                );
                $resultError = (string)($stageResult['error'] ?? '');

                if ($resultError === '' && isset($stageMap[$nextStageKey])) {
                    $nextStage = $stageMap[$nextStageKey];
                    $nextEntryEffectReports = wayfarerRuntimeStatusApplySubjectEffects(
                        $runtimeState,
                        isset($nextStage['entry_effects']) && is_array($nextStage['entry_effects'])
                            ? array_values($nextStage['entry_effects'])
                            : [],
                        $scope,
                        $currentRegionId,
                        $traitDefinitions
                    );
                }
            } else {
                $resultError = 'Status Outcome Result is invalid.';
            }

            if ($resultError !== '') {
                throw new RuntimeException(
                    'Status progression failed for ' .
                    (string)($definition['name'] ?? ('Status ' . $statusId)) .
                    ': ' . $resultError
                );
            }

            $afterAddress = wayfarerRuntimeStatusScopeAddress($runtimeState, $scope);
            if ($afterAddress !== null) {
                $afterStored =&
                    $runtimeState[$afterAddress['bucket']][$afterAddress['key']]['statuses'][(string)$statusId];

                if (is_array($afterStored)) {
                    $afterStored['last_outcome_key'] =
                        (string)($outcome['key'] ?? '');
                    $afterStored['last_outcome_tick'] = $tick;
                }
                unset($afterStored);
            }

            $presentation = strtolower(trim((string)($outcome['presentation'] ?? 'silent')));
            $storyletId = (int)($outcome['storylet_id'] ?? 0);

            if ($presentation === 'storylet' && $storyletId > 0) {
                wayfarerRuntimeQueueStatusStorylet(
                    $runtimeState,
                    [
                        'storylet_id' => $storyletId,
                        'subject_scope' => $scope,
                        'status_id' => $statusId,
                        'status_name' => (string)($definition['name'] ?? ''),
                        'stage_key' => $stageKey,
                        'stage_name' => (string)($stage['name'] ?? $stageKey),
                        'outcome_key' => (string)($outcome['key'] ?? ''),
                        'outcome_label' => (string)($outcome['label'] ?? ''),
                        'tick' => $tick,
                    ]
                );
            }

            $reports[] = [
                'event' => 'outcome',
                'scope' => $scope,
                'status_id' => $statusId,
                'status_name' => (string)($definition['name'] ?? ''),
                'stage_key' => $stageKey,
                'stage_name' => (string)($stage['name'] ?? $stageKey),
                'entry_effects' => $entryEffectReports,
                'tick_effects' => $tickEffectReports,
                'outcome_effects' => $outcomeEffectReports,
                'next_stage_entry_effects' => $nextEntryEffectReports,
                'outcome_key' => (string)($outcome['key'] ?? ''),
                'outcome_label' => (string)($outcome['label'] ?? ''),
                'result' => $result,
                'roll' => (int)($outcome['_runtime_roll'] ?? 0),
                'presentation' => $presentation,
                'storylet_id' => $storyletId,
                'tick' => $tick,
            ];
        }
    }

    if ($reports !== []) {
        if (!isset($runtimeState['runtime']) || !is_array($runtimeState['runtime'])) {
            $runtimeState['runtime'] = [];
        }

        $runtimeState['runtime']['last_status_progression'] = [
            'tick' => $tick,
            'reports' => $reports,
        ];
    }

    return $reports;
}


function wayfarerRuntimeVisibleStatusesForScope(
    PDO $pdo,
    int $gameId,
    array $runtimeState,
    string $scope
): array {
    $address = wayfarerRuntimeStatusScopeAddress(
        $runtimeState,
        $scope
    );

    if ($address === null) {
        return [];
    }

    $definitions = wayfarerRuntimeStatusDefinitions(
        $pdo,
        $gameId,
        true
    );

    if ($definitions === []) {
        return [];
    }

    $storedStatuses =
        $runtimeState[$address['bucket']][$address['key']]['statuses']
        ?? [];

    if (!is_array($storedStatuses)) {
        return [];
    }

    $visible = [];
    $currentTick = (int)($runtimeState['runtime']['tick'] ?? 0);

    foreach ($definitions as $statusKey => $definition) {
        if (empty($definition['show_to_player'])) {
            continue;
        }

        $stored = $storedStatuses[$statusKey] ?? null;
        if (!is_array($stored) || empty($stored['active'])) {
            continue;
        }

        $stageName = '';
        $remainingTicks = null;

        if (wayfarerRuntimeStatusLifecycleStages($definition) !== []) {
            $stageMap = wayfarerRuntimeStatusLifecycleStageMap($definition);
            $stageKey = strtolower(trim((string)($stored['stage_key'] ?? '')));

            if ($stageKey === '') {
                $stages = wayfarerRuntimeStatusLifecycleStages($definition);
                $stageKey = (string)($stages[0]['key'] ?? '');
            }

            if (
                !empty($definition['show_stage_to_player']) &&
                isset($stageMap[$stageKey])
            ) {
                $stageName = trim((string)($stageMap[$stageKey]['name'] ?? $stageKey));
            }

            if (
                !empty($definition['show_time_remaining']) &&
                isset($stored['next_check_tick']) &&
                is_numeric($stored['next_check_tick'])
            ) {
                $remainingTicks = max(
                    0,
                    (int)$stored['next_check_tick'] - $currentTick
                );
            }
        }

        $visible[] = [
            'id' => (int)$definition['id'],
            'name' => (string)$definition['name'],
            'description' => (string)$definition['description'],
            'started_tick' => isset($stored['started_tick']) &&
                is_numeric($stored['started_tick'])
                    ? (int)$stored['started_tick']
                    : null,
            'stage_name' => $stageName,
            'remaining_ticks' => $remainingTicks,
        ];
    }

    return $visible;
}



==============================================================================
FILE: play/includes/storylet-bindings.php
==============================================================================

<?php

/*
|--------------------------------------------------------------------------
| Storylet Bindings — runtime
| WAYFARER_STORYLET_BINDING_RUNTIME_V79
|--------------------------------------------------------------------------
|
| A Storylet Binding is resolved exactly once when that Storylet is entered.
| A party Binding may resolve to either a named Player Character or an authored
| Character Entity. The resolved subject is reused by Effects and narrative
| placeholders for that Storylet occurrence.
|
| V79 selectors:
|   random_party_character
|   random_possessed_item
|
*/

function wayfarerRuntimeStoryletBindingNormalizeKey(
    string $value
): string {
    return strtolower(
        trim($value)
    );
}


function wayfarerRuntimeStoryletBindingNormalizeTraitName(
    string $value
): string {
    $value =
        trim(
            preg_replace(
                '/\s+/u',
                ' ',
                $value
            ) ?? $value
        );

    if (function_exists('mb_strtolower')) {
        return mb_strtolower(
            $value,
            'UTF-8'
        );
    }

    return strtolower($value);
}


function wayfarerRuntimeStoryletBindingNamedTraitId(
    string $traitName
): string {
    return
        'binding_name_' .
        bin2hex(
            wayfarerRuntimeStoryletBindingNormalizeTraitName(
                $traitName
            )
        );
}


function wayfarerRuntimeStoryletBindingDecodeNamedTraitId(
    string $targetId
): ?string {
    $prefix =
        'binding_name_';

    if (
        strpos(
            $targetId,
            $prefix
        ) !== 0
    ) {
        return null;
    }

    $hex =
        substr(
            $targetId,
            strlen($prefix)
        );

    if (
        $hex === '' ||
        strlen($hex) % 2 !== 0 ||
        preg_match(
            '/^[0-9a-f]+$/i',
            $hex
        ) !== 1
    ) {
        return null;
    }

    $decoded =
        hex2bin($hex);

    return $decoded === false
        ? null
        : $decoded;
}


function wayfarerRuntimeStoryletBindingDefinitions(
    array $storylet
): array {
    $config =
        isset($storylet['_runtime_config']) &&
        is_array($storylet['_runtime_config'])
            ? $storylet['_runtime_config']
            : wayfarerRuntimeDecodeConfig(
                $storylet['config']
                    ?? null
            );

    $rows =
        isset($config['bindings']) &&
        is_array($config['bindings'])
            ? array_values(
                $config['bindings']
            )
            : [];

    $bindings = [];

    foreach ($rows as $row) {
        if (!is_array($row)) {
            continue;
        }

        $key =
            wayfarerRuntimeStoryletBindingNormalizeKey(
                (string)(
                    $row['key']
                    ?? ''
                )
            );

        $label =
            trim(
                (string)(
                    $row['label']
                    ?? $key
                )
            );

        $selector =
            strtolower(
                trim(
                    (string)(
                        $row['selector']
                        ?? ''
                    )
                )
            );

        if (
            $key === '' ||
            preg_match(
                '/^[a-z][a-z0-9_]{0,31}$/',
                $key
            ) !== 1 ||
            !in_array(
                $selector,
                [
                    'random_party_character',
                    'random_possessed_item',
                ],
                true
            )
        ) {
            continue;
        }

        $bindings[$key] = [
            'key' => $key,
            'label' =>
                $label !== ''
                    ? $label
                    : $key,
            'selector' => $selector,
        ];
    }

    return $bindings;
}


function wayfarerRuntimeStoryletBindingRequiredTargets(
    array $storylet,
    string $bindingKey
): array {
    $config =
        isset($storylet['_runtime_config']) &&
        is_array($storylet['_runtime_config'])
            ? $storylet['_runtime_config']
            : wayfarerRuntimeDecodeConfig(
                $storylet['config']
                    ?? null
            );

    $effects =
        isset($config['effects']) &&
        is_array($config['effects'])
            ? $config['effects']
            : [];

    $scope =
        'binding:' .
        $bindingKey;

    $required = [];

    foreach ($effects as $effect) {
        if (!is_array($effect)) {
            continue;
        }

        if (
            strtolower(
                trim(
                    (string)(
                        $effect['target_scope']
                        ?? ''
                    )
                )
            ) !== $scope
        ) {
            continue;
        }

        $targetType =
            strtolower(
                trim(
                    (string)(
                        $effect['target_type']
                        ?? ''
                    )
                )
            );

        $targetId =
            trim(
                (string)(
                    $effect['target_id']
                    ?? ''
                )
            );

        if (
            $targetType === '' ||
            $targetId === ''
        ) {
            continue;
        }

        $required[
            $targetType .
            ':' .
            $targetId
        ] = [
            'target_type' =>
                $targetType,
            'target_id' =>
                $targetId,
        ];
    }

    return array_values($required);
}


function wayfarerRuntimeStoryletBindingFindNamedTrait(
    array $config,
    string $normalizedName
): ?array {
    $traits =
        isset($config['traits']) &&
        is_array($config['traits'])
            ? $config['traits']
            : [];

    $match = null;

    foreach ($traits as $trait) {
        if (
            !is_array($trait) ||
            !empty($trait['system']) ||
            (
                array_key_exists(
                    'active',
                    $trait
                ) &&
                !$trait['active']
            )
        ) {
            continue;
        }

        $name =
            wayfarerRuntimeStoryletBindingNormalizeTraitName(
                (string)(
                    $trait['name']
                    ?? ''
                )
            );

        if ($name !== $normalizedName) {
            continue;
        }

        /*
         * Ambiguous duplicate names on one Entity are not safe for a generic
         * binding target.
         */
        if ($match !== null) {
            return null;
        }

        $traitId =
            trim(
                (string)(
                    $trait['id']
                    ?? ''
                )
            );

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

        $match = $trait;
    }

    return $match;
}


function wayfarerRuntimeStoryletBindingEntitySupportsTargets(
    array $entity,
    array $requiredTargets
): array {
    $config =
        wayfarerEntityDecodeConfig(
            $entity['config']
            ?? null
        );

    $targetMap = [];

    foreach ($requiredTargets as $required) {
        if (!is_array($required)) {
            continue;
        }

        $targetType =
            strtolower(
                trim(
                    (string)(
                        $required['target_type']
                        ?? ''
                    )
                )
            );

        $targetId =
            trim(
                (string)(
                    $required['target_id']
                    ?? ''
                )
            );

        if (
            $targetType === 'status' &&
            preg_match('/^[1-9][0-9]*$/', $targetId) === 1
        ) {
            $targetMap[$targetId] = $targetId;
            continue;
        }

        if (
            $targetType !== 'trait' ||
            $targetId === ''
        ) {
            return [
                'supported' => false,
                'target_map' => [],
            ];
        }

        if (
            $targetId === 'sys_item_quantity' ||
            $targetId === 'sys_character_party_member'
        ) {
            $targetMap[$targetId] =
                $targetId;
            continue;
        }

        $namedTrait =
            wayfarerRuntimeStoryletBindingDecodeNamedTraitId(
                $targetId
            );

        if ($namedTrait === null) {
            return [
                'supported' => false,
                'target_map' => [],
            ];
        }

        $trait =
            wayfarerRuntimeStoryletBindingFindNamedTrait(
                $config,
                $namedTrait
            );

        if (!is_array($trait)) {
            return [
                'supported' => false,
                'target_map' => [],
            ];
        }

        $actualTraitId =
            trim(
                (string)(
                    $trait['id']
                    ?? ''
                )
            );

        if ($actualTraitId === '') {
            return [
                'supported' => false,
                'target_map' => [],
            ];
        }

        $targetMap[$targetId] =
            $actualTraitId;
    }

    return [
        'supported' => true,
        'target_map' => $targetMap,
    ];
}


/* WAYFARER_PARTY_BINDINGS_V85 */
function wayfarerRuntimeStoryletBindingFindPlayerTrait(
    array $gameConfig,
    string $normalizedName
): ?array {
    $traits =
        isset($gameConfig['player_traits']) &&
        is_array($gameConfig['player_traits'])
            ? $gameConfig['player_traits']
            : [];

    $match = null;

    foreach ($traits as $trait) {
        if (
            !is_array($trait) ||
            (
                array_key_exists('active', $trait) &&
                !$trait['active']
            )
        ) {
            continue;
        }

        $name =
            wayfarerRuntimeStoryletBindingNormalizeTraitName(
                (string)(
                    $trait['name']
                    ?? ''
                )
            );

        if ($name !== $normalizedName) {
            continue;
        }

        if ($match !== null) {
            return null;
        }

        $traitId =
            trim(
                (string)(
                    $trait['id']
                    ?? ''
                )
            );

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

        $match = $trait;
    }

    return $match;
}


function wayfarerRuntimeStoryletBindingPlayerSupportsTargets(
    array $gameConfig,
    array $playerState,
    array $requiredTargets
): array {
    $targetMap = [];

    $runtimeTraits =
        isset($playerState['traits']) &&
        is_array($playerState['traits'])
            ? $playerState['traits']
            : [];

    foreach ($requiredTargets as $required) {
        if (!is_array($required)) {
            continue;
        }

        $targetType =
            strtolower(
                trim(
                    (string)(
                        $required['target_type']
                        ?? ''
                    )
                )
            );

        $targetId =
            trim(
                (string)(
                    $required['target_id']
                    ?? ''
                )
            );

        if (
            $targetType === 'status' &&
            preg_match('/^[1-9][0-9]*$/', $targetId) === 1
        ) {
            $targetMap[$targetId] = $targetId;
            continue;
        }

        if (
            $targetType !== 'trait' ||
            $targetId === '' ||
            $targetId === 'sys_item_quantity' ||
            $targetId === 'sys_character_party_member'
        ) {
            return [
                'supported' => false,
                'target_map' => [],
            ];
        }

        $namedTrait =
            wayfarerRuntimeStoryletBindingDecodeNamedTraitId(
                $targetId
            );

        if ($namedTrait === null) {
            return [
                'supported' => false,
                'target_map' => [],
            ];
        }

        $trait =
            wayfarerRuntimeStoryletBindingFindPlayerTrait(
                $gameConfig,
                $namedTrait
            );

        if (!is_array($trait)) {
            return [
                'supported' => false,
                'target_map' => [],
            ];
        }

        $actualTraitId =
            trim(
                (string)(
                    $trait['id']
                    ?? ''
                )
            );

        if (
            $actualTraitId === '' ||
            !array_key_exists(
                $actualTraitId,
                $runtimeTraits
            )
        ) {
            return [
                'supported' => false,
                'target_map' => [],
            ];
        }

        $targetMap[$targetId] =
            $actualTraitId;
    }

    return [
        'supported' => true,
        'target_map' => $targetMap,
    ];
}


/* WAYFARER_STATUS_SUBJECT_BINDING_V88 */
function wayfarerRuntimeStoryletPresetCharacterBinding(
    PDO $pdo,
    int $gameId,
    array $storylet,
    array $runtimeState,
    string $runtimeScope,
    string $bindingKey = 'subject',
    string $label = 'Subject'
): array {
    $runtimeScope = strtolower(trim($runtimeScope));
    $bindingKey = wayfarerRuntimeStoryletBindingNormalizeKey($bindingKey);

    if (
        $bindingKey === '' ||
        preg_match('/^[a-z][a-z0-9_]{0,31}$/', $bindingKey) !== 1
    ) {
        return [
            'binding' => null,
            'error' => 'Triggered Storylet subject binding key is invalid.',
        ];
    }

    $requiredTargets =
        wayfarerRuntimeStoryletBindingRequiredTargets(
            $storylet,
            $bindingKey
        );

    if (
        preg_match('/^player:([0-9]+)$/', $runtimeScope, $match) === 1
    ) {
        $slot = (int)$match[1];
        $playerState = $runtimeState['players'][(string)$slot] ?? null;

        if (!is_array($playerState)) {
            return [
                'binding' => null,
                'error' => 'Triggered Storylet Player subject was not found.',
            ];
        }

        $gameConfig = function_exists('wayfarerRuntimeLoadGameConfig')
            ? wayfarerRuntimeLoadGameConfig($pdo, $gameId)
            : [];

        $support =
            wayfarerRuntimeStoryletBindingPlayerSupportsTargets(
                $gameConfig,
                $playerState,
                $requiredTargets
            );

        if (empty($support['supported'])) {
            return [
                'binding' => null,
                'error' =>
                    'Triggered Storylet subject does not expose every Trait/Status required by the subject Binding Effects.',
            ];
        }

        $name = trim((string)($playerState['name'] ?? ''));
        if ($name === '') {
            $name = 'Player ' . ($slot + 1);
        }

        return [
            'binding' => [
                'key' => $bindingKey,
                'label' => $label,
                'selector' => 'status_subject',
                'runtime_scope' => 'player:' . $slot,
                'subject_kind' => 'player',
                'player_slot' => $slot,
                'entity_id' => 0,
                'entity_type' => 'player',
                'name' => $name,
                'target_map' => $support['target_map'] ?? [],
            ],
            'error' => '',
        ];
    }

    if (
        preg_match('/^entity:([1-9][0-9]*)$/', $runtimeScope, $match) === 1
    ) {
        $entityId = (int)$match[1];
        $runtimeEntity = $runtimeState['entities'][(string)$entityId] ?? null;

        if (!is_array($runtimeEntity)) {
            return [
                'binding' => null,
                'error' => 'Triggered Storylet Character subject was not found.',
            ];
        }

        $stmt = $pdo->prepare(
            "
            SELECT
                id,
                name,
                entity_type,
                config
            FROM wf_entities
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

        $stmt->execute([
            $entityId,
            $gameId,
        ]);

        $entity = $stmt->fetch(PDO::FETCH_ASSOC);
        if (!$entity) {
            return [
                'binding' => null,
                'error' => 'Triggered Storylet Character definition was not found.',
            ];
        }

        $support =
            wayfarerRuntimeStoryletBindingEntitySupportsTargets(
                $entity,
                $requiredTargets
            );

        if (empty($support['supported'])) {
            return [
                'binding' => null,
                'error' =>
                    'Triggered Storylet subject does not expose every Trait/Status required by the subject Binding Effects.',
            ];
        }

        return [
            'binding' => [
                'key' => $bindingKey,
                'label' => $label,
                'selector' => 'status_subject',
                'runtime_scope' => 'entity:' . $entityId,
                'subject_kind' => 'entity',
                'player_slot' => null,
                'entity_id' => $entityId,
                'entity_type' => strtolower(trim((string)($entity['entity_type'] ?? 'character'))),
                'name' => trim((string)($entity['name'] ?? ('Character ' . $entityId))),
                'target_map' => $support['target_map'] ?? [],
            ],
            'error' => '',
        ];
    }

    return [
        'binding' => null,
        'error' => 'Triggered Storylet subject scope is invalid.',
    ];
}


function wayfarerRuntimeStoryletBindingCandidates(
    PDO $pdo,
    int $gameId,
    array $storylet,
    array $binding,
    array $runtimeState
): array {
    $selector =
        strtolower(
            trim(
                (string)(
                    $binding['selector']
                    ?? ''
                )
            )
        );

    $bindingKey =
        wayfarerRuntimeStoryletBindingNormalizeKey(
            (string)(
                $binding['key']
                ?? ''
            )
        );

    $requiredTargets =
        wayfarerRuntimeStoryletBindingRequiredTargets(
            $storylet,
            $bindingKey
        );

    $candidates = [];

    /*
     * Named setup Player Characters are party members too. They do not use the
     * Entity Party Membership Trait; their presence in runtime.players is the
     * canonical membership signal for the playthrough.
     */
    if ($selector === 'random_party_character') {
        $gameConfig =
            function_exists('wayfarerRuntimeLoadGameConfig')
                ? wayfarerRuntimeLoadGameConfig(
                    $pdo,
                    $gameId
                )
                : [];

        $players =
            isset($runtimeState['players']) &&
            is_array($runtimeState['players'])
                ? $runtimeState['players']
                : [];

        foreach ($players as $playerKey => $playerState) {
            if (!is_array($playerState)) {
                continue;
            }

            $name =
                trim(
                    (string)(
                        $playerState['name']
                        ?? ''
                    )
                );

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

            $support =
                wayfarerRuntimeStoryletBindingPlayerSupportsTargets(
                    $gameConfig,
                    $playerState,
                    $requiredTargets
                );

            if (empty($support['supported'])) {
                continue;
            }

            $slot =
                (int)(
                    $playerState['slot']
                    ?? $playerKey
                );

            $candidates[] = [
                'runtime_scope' =>
                    'player:' . $slot,
                'subject_kind' =>
                    'player',
                'player_slot' =>
                    $slot,
                'entity_id' =>
                    0,
                'entity_type' =>
                    'player',
                'name' =>
                    $name,
                'target_map' =>
                    $support['target_map'],
            ];
        }
    }

    foreach (
        wayfarerRuntimeLoadActiveEntities(
            $pdo,
            $gameId
        )
        as $entity
    ) {
        if (!is_array($entity)) {
            continue;
        }

        $entityId =
            (int)(
                $entity['id']
                ?? 0
            );

        if ($entityId <= 0) {
            continue;
        }

        $entityType =
            strtolower(
                trim(
                    (string)(
                        $entity['entity_type']
                        ?? ''
                    )
                )
            );

        $entityState =
            $runtimeState['entities'][
                (string)$entityId
            ]
            ?? null;

        if (!is_array($entityState)) {
            continue;
        }

        $traits =
            isset($entityState['traits']) &&
            is_array($entityState['traits'])
                ? $entityState['traits']
                : [];

        if (
            $selector === 'random_party_character'
        ) {
            if (
                $entityType !== 'character' ||
                empty(
                    $traits[
                        'sys_character_party_member'
                    ]
                )
            ) {
                continue;
            }

        } elseif (
            $selector === 'random_possessed_item'
        ) {
            $quantity =
                $traits[
                    'sys_item_quantity'
                ]
                ?? 0;

            if (
                $entityType !== 'item' ||
                !is_numeric($quantity) ||
                (float)$quantity <= 0
            ) {
                continue;
            }

        } else {
            continue;
        }

        $support =
            wayfarerRuntimeStoryletBindingEntitySupportsTargets(
                $entity,
                $requiredTargets
            );

        if (empty($support['supported'])) {
            continue;
        }

        $candidates[] = [
            'runtime_scope' =>
                'entity:' . $entityId,
            'subject_kind' =>
                'entity',
            'player_slot' =>
                null,
            'entity_id' =>
                $entityId,
            'entity_type' =>
                $entityType,
            'name' =>
                trim(
                    (string)(
                        $entity['name']
                        ?? ('Entity ' . $entityId)
                    )
                ),
            'target_map' =>
                $support['target_map'],
        ];
    }

    return $candidates;
}


function wayfarerRuntimeStoryletBindingsAvailable(
    PDO $pdo,
    int $gameId,
    array $storylet,
    array $runtimeState
): bool {
    $definitions =
        wayfarerRuntimeStoryletBindingDefinitions(
            $storylet
        );

    foreach ($definitions as $binding) {
        if (
            wayfarerRuntimeStoryletBindingCandidates(
                $pdo,
                $gameId,
                $storylet,
                $binding,
                $runtimeState
            ) === []
        ) {
            return false;
        }
    }

    return true;
}


function wayfarerRuntimeResolveStoryletBindings(
    PDO $pdo,
    int $gameId,
    array $storylet,
    array $runtimeState,
    array $presetBindings = []
): array {
    $definitions =
        wayfarerRuntimeStoryletBindingDefinitions(
            $storylet
        );

    $resolved = [];

    foreach (
        $definitions
        as $key => $binding
    ) {
        /* WAYFARER_PERSISTENT_STORYLET_BINDINGS_V88 */
        if (
            isset($presetBindings[$key]) &&
            is_array($presetBindings[$key])
        ) {
            $resolved[$key] = $presetBindings[$key];
            continue;
        }

        $candidates =
            wayfarerRuntimeStoryletBindingCandidates(
                $pdo,
                $gameId,
                $storylet,
                $binding,
                $runtimeState
            );

        if ($candidates === []) {
            return [
                'bindings' => [],
                'error' =>
                    'Storylet Binding "' .
                    (
                        $binding['label']
                        ?? $key
                    ) .
                    '" has no eligible runtime target.',
            ];
        }

        $selected =
            $candidates[
                random_int(
                    0,
                    count($candidates) - 1
                )
            ];

        $resolved[$key] = [
            'key' =>
                $key,
            'label' =>
                (string)(
                    $binding['label']
                    ?? $key
                ),
            'selector' =>
                (string)(
                    $binding['selector']
                    ?? ''
                ),
            'runtime_scope' =>
                (string)(
                    $selected['runtime_scope']
                    ?? ''
                ),
            'subject_kind' =>
                (string)(
                    $selected['subject_kind']
                    ?? 'entity'
                ),
            'player_slot' =>
                isset($selected['player_slot'])
                    ? (int)$selected['player_slot']
                    : null,
            'entity_id' =>
                (int)(
                    $selected['entity_id']
                    ?? 0
                ),
            'entity_type' =>
                (string)(
                    $selected['entity_type']
                    ?? ''
                ),
            'name' =>
                (string)$selected['name'],
            'target_map' =>
                is_array(
                    $selected['target_map']
                    ?? null
                )
                    ? $selected['target_map']
                    : [],
        ];
    }

    /*
     * Preset bindings that are not explicitly defined on this Storylet are
     * still carried for narrative interpolation. This is how a Status Outcome
     * can supply the reserved {{subject}} placeholder without forcing every
     * presentation-only Storylet to author a duplicate Binding definition.
     */
    foreach ($presetBindings as $key => $binding) {
        if (
            !isset($resolved[$key]) &&
            is_array($binding)
        ) {
            $resolved[$key] = $binding;
        }
    }

    return [
        'bindings' => $resolved,
        'error' => '',
    ];
}


function wayfarerRuntimeMaterializeStoryletBindingEffect(
    array $effect,
    array $bindings
): array {
    $scope =
        strtolower(
            trim(
                (string)(
                    $effect['target_scope']
                    ?? ''
                )
            )
        );

    if (
        preg_match(
            '/^binding:([a-z][a-z0-9_]{0,31})$/',
            $scope,
            $match
        ) !== 1
    ) {
        return [
            'effect' => $effect,
            'error' => '',
        ];
    }

    $key =
        $match[1];

    $binding =
        $bindings[$key]
        ?? null;

    if (!is_array($binding)) {
        return [
            'effect' => [],
            'error' =>
                'Resolved Storylet Binding "' .
                $key .
                '" is missing.',
        ];
    }

    $runtimeScope =
        strtolower(
            trim(
                (string)(
                    $binding['runtime_scope']
                    ?? ''
                )
            )
        );

    /*
     * Compatibility for V79-V84 saved runtime binding records, which stored
     * only entity_id.
     */
    if ($runtimeScope === '') {
        $entityId =
            (int)(
                $binding['entity_id']
                ?? 0
            );

        if ($entityId > 0) {
            $runtimeScope =
                'entity:' .
                $entityId;
        }
    }

    if (
        preg_match(
            '/^(?:entity:[1-9][0-9]*|player:[0-9]+)$/',
            $runtimeScope
        ) !== 1
    ) {
        return [
            'effect' => [],
            'error' =>
                'Resolved Storylet Binding "' .
                $key .
                '" does not point to a valid Party Member or Entity.',
        ];
    }

    $targetId =
        trim(
            (string)(
                $effect['target_id']
                ?? ''
            )
        );

    $targetType =
        strtolower(
            trim(
                (string)(
                    $effect['target_type']
                    ?? ''
                )
            )
        );

    /* WAYFARER_STATUS_BINDING_RUNTIME_V87 */
    if (
        $targetType === 'status' &&
        preg_match('/^[1-9][0-9]*$/', $targetId) === 1
    ) {
        $materialized = $effect;
        $materialized['target_scope'] = $runtimeScope;
        $materialized['target_id'] = $targetId;

        return [
            'effect' => $materialized,
            'error' => '',
        ];
    }

    $targetMap =
        is_array(
            $binding['target_map']
            ?? null
        )
            ? $binding['target_map']
            : [];

    $entityScope =
        strpos(
            $runtimeScope,
            'entity:'
        ) === 0;

    $actualTargetId =
        $targetMap[$targetId]
        ?? (
            $entityScope &&
            (
                $targetId === 'sys_item_quantity' ||
                $targetId === 'sys_character_party_member'
            )
                ? $targetId
                : ''
        );

    if ($actualTargetId === '') {
        return [
            'effect' => [],
            'error' =>
                'The selected subject for Binding "' .
                $key .
                '" does not expose the required Trait.',
        ];
    }

    $materialized =
        $effect;

    $materialized['target_scope'] =
        $runtimeScope;

    $materialized['target_id'] =
        $actualTargetId;

    if (
        $entityScope &&
        $actualTargetId === 'sys_item_quantity'
    ) {
        $materialized['target_system_key'] =
            'quantity';
    } elseif (
        $entityScope &&
        $actualTargetId ===
        'sys_character_party_member'
    ) {
        $materialized['target_system_key'] =
            'party_member';
    } else {
        unset(
            $materialized['target_system_key']
        );
    }

    return [
        'effect' => $materialized,
        'error' => '',
    ];
}


function wayfarerRuntimeInterpolateStoryletBindings(
    string $text,
    array $bindings
): string {
    if (
        $text === '' ||
        $bindings === []
    ) {
        return $text;
    }

    $replace =
        function (
            array $match
        ) use (
            $bindings
        ): string {
            $key =
                wayfarerRuntimeStoryletBindingNormalizeKey(
                    (string)(
                        $match[1]
                        ?? ''
                    )
                );

            $binding =
                $bindings[$key]
                ?? null;

            if (!is_array($binding)) {
                return $match[0];
            }

            return
                (string)(
                    $binding['name']
                    ?? $match[0]
                );
        };

    /*
     * {{victim.name}} and the shorter {{victim}} both resolve to the bound
     * subject's current name.
     */
    $text =
        preg_replace_callback(
            '/\{\{\s*([a-z][a-z0-9_]*)\.name\s*\}\}/i',
            $replace,
            $text
        ) ?? $text;

    $text =
        preg_replace_callback(
            '/\{\{\s*([a-z][a-z0-9_]*)\s*\}\}/i',
            $replace,
            $text
        ) ?? $text;

    return $text;
}


==============================================================================
FILE: play/includes/storylets.php
==============================================================================

<?php

require_once __DIR__ . '/storylet-bindings.php'; /* WAYFARER_STORYLET_BINDING_RUNTIME_V79 */

/*
|--------------------------------------------------------------------------
| Interactive Storylet Runtime
| WAYFARER_STORYLET_ACTION_RUNTIME_V59
|--------------------------------------------------------------------------
|
| V59 implements the player-selected Storylet path:
|
|   Action Mode -> root Manual Storylet -> Storylet presentation
|               -> eligible child Branch -> child presentation -> ...
|
| Automatic/Chance firing is intentionally not handled here yet.
|
*/


function wayfarerRuntimeLoadStorylet(
    PDO $pdo,
    int $gameId,
    int $storyletId
): ?array {

    if ($gameId <= 0 || $storyletId <= 0) {
        return null;
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                game_id,
                name,
                description,
                parent_storylet_id,
                branch_label,
                branch_sort_order,
                trigger_type,
                max_occurrences,
                status,
                config
            FROM wf_storylets
            WHERE id = ?
              AND game_id = ?
            LIMIT 1
            "
        );

    $stmt->execute([
        $storyletId,
        $gameId,
    ]);

    $storylet =
        $stmt->fetch(
            PDO::FETCH_ASSOC
        );

    if (!$storylet) {
        return null;
    }

    $storylet['_runtime_config'] =
        wayfarerRuntimeDecodeConfig(
            $storylet['config']
                ?? null
        );

    return $storylet;
}


function wayfarerRuntimeStoryletOccurrenceCount(
    array $runtimeState,
    int $storyletId
): int {

    if ($storyletId <= 0) {
        return 0;
    }

    return max(
        0,
        (int)(
            $runtimeState['storylets'][(string)$storyletId]['occurrences']
            ?? 0
        )
    );
}


function wayfarerRuntimeStoryletOccurrenceLimitReached(
    array $storylet,
    array $runtimeState
): bool {

    $maximum =
        $storylet['max_occurrences']
        ?? null;

    if (
        $maximum === null ||
        $maximum === '' ||
        !is_numeric($maximum)
    ) {
        return false;
    }

    $maximum =
        (int)$maximum;

    if ($maximum <= 0) {
        return false;
    }

    return
        wayfarerRuntimeStoryletOccurrenceCount(
            $runtimeState,
            (int)($storylet['id'] ?? 0)
        ) >= $maximum;
}


function wayfarerRuntimeStoryletConditionsPass(
    array $storylet,
    array &$runtimeState
): bool {

    $config =
        isset($storylet['_runtime_config']) &&
        is_array($storylet['_runtime_config'])
            ? $storylet['_runtime_config']
            : wayfarerRuntimeDecodeConfig(
                $storylet['config']
                    ?? null
            );

    $conditions =
        $config['conditions']
        ?? null;

    $regionId =
        (int)(
            $runtimeState['navigation']['region_id']
            ?? 0
        );

    $resolver =
        function (
            string $scope,
            string $targetType,
            string $targetId
        ) use (
            &$runtimeState,
            $regionId
        ): array {

            return
                wayfarerRuntimeResolveConditionTarget(
                    $runtimeState,
                    $regionId,
                    $scope,
                    $targetType,
                    $targetId
                );
        };

    return
        wayfarerConditionsPass(
            $conditions,
            $resolver
        );
}


function wayfarerRuntimeStoryletIsEligible(
    array $storylet,
    array &$runtimeState
): bool {

    if (
        strtolower(
            trim(
                (string)(
                    $storylet['status']
                    ?? ''
                )
            )
        ) !== 'active'
    ) {
        return false;
    }

    if (
        wayfarerRuntimeStoryletOccurrenceLimitReached(
            $storylet,
            $runtimeState
        )
    ) {
        return false;
    }

    return
        wayfarerRuntimeStoryletConditionsPass(
            $storylet,
            $runtimeState
        );
}


function wayfarerRuntimeStoryletPlayerPayload(
    array $storylet,
    array $runtimeState,
    bool $asBranch = false
): array {

    $name =
        trim(
            (string)(
                $storylet['name']
                ?? ''
            )
        );

    $branchLabel =
        trim(
            (string)(
                $storylet['branch_label']
                ?? ''
            )
        );

    $config =
        isset($storylet['_runtime_config']) &&
        is_array($storylet['_runtime_config'])
            ? $storylet['_runtime_config']
            : wayfarerRuntimeDecodeConfig(
                $storylet['config']
                    ?? null
            );

    return [
        'id' =>
            (int)(
                $storylet['id']
                ?? 0
            ),

        'name' =>
            $name,

        'label' =>
            $asBranch && $branchLabel !== ''
                ? $branchLabel
                : $name,

        'description' =>
            trim(
                (string)(
                    $storylet['description']
                    ?? ''
                )
            ),

        'priority' =>
            (int)(
                $config['priority']
                ?? 100
            ),

        'occurrences' =>
            wayfarerRuntimeStoryletOccurrenceCount(
                $runtimeState,
                (int)(
                    $storylet['id']
                    ?? 0
                )
            ),

        'max_occurrences' =>
            $storylet['max_occurrences'] === null ||
            $storylet['max_occurrences'] === ''
                ? null
                : (int)$storylet['max_occurrences'],
    ];
}


function wayfarerRuntimeEligibleRootManualStorylets(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): array {

    if ($gameId <= 0) {
        return [];
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                game_id,
                name,
                description,
                parent_storylet_id,
                branch_label,
                branch_sort_order,
                trigger_type,
                max_occurrences,
                status,
                config
            FROM wf_storylets
            WHERE game_id = ?
              AND status = 'active'
              AND trigger_type = 'manual'
              AND (
                    parent_storylet_id IS NULL
                    OR parent_storylet_id = 0
                  )
            ORDER BY id
            "
        );

    $stmt->execute([
        $gameId
    ]);

    $actions = [];

    foreach (
        $stmt->fetchAll(PDO::FETCH_ASSOC)
        as $storylet
    ) {
        $storylet['_runtime_config'] =
            wayfarerRuntimeDecodeConfig(
                $storylet['config']
                    ?? null
            );

        if (
            !wayfarerRuntimeStoryletIsEligible(
                $storylet,
                $runtimeState
            ) ||
            !wayfarerRuntimeStoryletBindingsAvailable(
                $pdo,
                $gameId,
                $storylet,
                $runtimeState
            )
        ) {
            continue;
        }

        $actions[] =
            wayfarerRuntimeStoryletPlayerPayload(
                $storylet,
                $runtimeState,
                false
            );
    }

    usort(
        $actions,
        function (
            array $a,
            array $b
        ): int {

            $priority =
                ((int)($a['priority'] ?? 100)) <=>
                ((int)($b['priority'] ?? 100));

            if ($priority !== 0) {
                return $priority;
            }

            $label =
                strcasecmp(
                    (string)($a['label'] ?? ''),
                    (string)($b['label'] ?? '')
                );

            if ($label !== 0) {
                return $label;
            }

            return
                ((int)($a['id'] ?? 0)) <=>
                ((int)($b['id'] ?? 0));
        }
    );

    return $actions;
}


function wayfarerRuntimeEligibleStoryletBranches(
    PDO $pdo,
    int $gameId,
    int $parentStoryletId,
    array &$runtimeState
): array {

    if (
        $gameId <= 0 ||
        $parentStoryletId <= 0
    ) {
        return [];
    }

    $stmt =
        $pdo->prepare(
            "
            SELECT
                id,
                game_id,
                name,
                description,
                parent_storylet_id,
                branch_label,
                branch_sort_order,
                trigger_type,
                max_occurrences,
                status,
                config
            FROM wf_storylets
            WHERE game_id = ?
              AND parent_storylet_id = ?
              AND status = 'active'
            ORDER BY branch_sort_order, name, id
            "
        );

    $stmt->execute([
        $gameId,
        $parentStoryletId,
    ]);

    $branches = [];

    foreach (
        $stmt->fetchAll(PDO::FETCH_ASSOC)
        as $storylet
    ) {
        $storylet['_runtime_config'] =
            wayfarerRuntimeDecodeConfig(
                $storylet['config']
                    ?? null
            );

        if (
            !wayfarerRuntimeStoryletIsEligible(
                $storylet,
                $runtimeState
            ) ||
            !wayfarerRuntimeStoryletBindingsAvailable(
                $pdo,
                $gameId,
                $storylet,
                $runtimeState
            )
        ) {
            continue;
        }

        $payload =
            wayfarerRuntimeStoryletPlayerPayload(
                $storylet,
                $runtimeState,
                true
            );

        $payload['branch_sort_order'] =
            (int)(
                $storylet['branch_sort_order']
                ?? 0
            );

        $branches[] =
            $payload;
    }

    return $branches;
}


function wayfarerRuntimeEnsureStoryletTargetState(
    PDO $pdo,
    int $gameId,
    array &$runtimeState
): void {

    wayfarerRuntimeEnsureAllRegionTraitState(
        $pdo,
        $gameId,
        $runtimeState
    );

    wayfarerRuntimeEnsureAllLocationTraitState(
        $pdo,
        $gameId,
        $runtimeState
    );

    wayfarerRuntimeEnsureEntityState(
        $pdo,
        $gameId,
        $runtimeState
    );

    wayfarerRuntimeEnsurePlayerAndGameState(
        $pdo,
        $gameId,
        $runtimeState
    );
}


function wayfarerRuntimeStoryletTraitDefinitions(
    PDO $pdo,
    int $gameId,
    array $runtimeState
): array {

    $regionId =
        (int)(
            $runtimeState['navigation']['region_id']
            ?? 0
        );

    $regionConfig = [];

    if ($regionId > 0) {
        $stmt =
            $pdo->prepare(
                "
                SELECT config
                FROM wf_regions
                WHERE id = ?
                  AND game_id = ?
                LIMIT 1
                "
            );

        $stmt->execute([
            $regionId,
            $gameId,
        ]);

        $raw =
            $stmt->fetchColumn();

        if ($raw !== false) {
            $regionConfig =
                wayfarerRuntimeDecodeTraitConfig(
                    $raw
                );
        }
    }

    return
        wayfarerRuntimeLoadTickTraitDefinitions(
            $pdo,
            $gameId,
            $regionConfig
        );
}


/*
|--------------------------------------------------------------------------
| Storylet-to-root navigation runtime
| WAYFARER_STORYLET_ROOT_CONNECTIONS_V82
|--------------------------------------------------------------------------
*/

function wayfarerRuntimeConsumeStoryletTransition(
    array &$runtimeState
): int {

    $storyletId =
        (int)(
            $runtimeState['runtime']['pending_storylet_transition']
            ?? 0
        );

    if (
        isset($runtimeState['runtime']) &&
        is_array($runtimeState['runtime'])
    ) {
        unset(
            $runtimeState['runtime']['pending_storylet_transition']
        );
    }

    return max(
        0,
        $storyletId
    );
}


function wayfarerRuntimeEnterLinkedRootStorylet(
    PDO $pdo,
    int $gameId,
    int $storyletId,
    array &$runtimeState,
    array $visitedStorylets = [],
    array $inheritedBindings = []
): array {

    $chain = [];
    $nextStoryletId =
        $storyletId;

    while ($nextStoryletId > 0) {

        if (count($chain) >= 16) {
            throw new RuntimeException(
                'Storylet Continue To chain is too deep.'
            );
        }

        if (
            isset(
                $visitedStorylets[
                    (string)$nextStoryletId
                ]
            )
        ) {
            throw new RuntimeException(
                'Storylet Continue To would create a circular Storylet chain.'
            );
        }

        $visitedStorylets[
            (string)$nextStoryletId
        ] = true;

        $linkedStorylet =
            wayfarerRuntimeLoadStorylet(
                $pdo,
                $gameId,
                $nextStoryletId
            );

        if (!$linkedStorylet) {
            throw new RuntimeException(
                'The linked root Storylet could not be found.'
            );
        }

        if (
            !empty(
                $linkedStorylet[
                    'parent_storylet_id'
                ]
            )
        ) {
            throw new RuntimeException(
                'Storylet Continue To may target only a root Storylet.'
            );
        }

        wayfarerRuntimeEnsureStoryletTargetState(
            $pdo,
            $gameId,
            $runtimeState
        );

        if (
            !wayfarerRuntimeStoryletIsEligible(
                $linkedStorylet,
                $runtimeState
            )
        ) {
            throw new RuntimeException(
                'The linked root Storylet is not currently eligible.'
            );
        }

        $linkedConfig =
            $linkedStorylet[
                '_runtime_config'
            ]
            ?? [];

        $tickCost =
            max(
                0,
                (int)(
                    $linkedConfig[
                        'tick_cost'
                    ]
                    ?? 0
                )
            );

        if ($tickCost > 0) {
            throw new RuntimeException(
                'Storylet Tick Cost runtime is not implemented yet. Set Tick Cost to 0 for linked Storylets.'
            );
        }

        /* WAYFARER_PERSISTENT_STORYLET_SUBJECT_V88 */
        $linkedPresetBindings = [];

        if (
            isset($inheritedBindings['subject']) &&
            is_array($inheritedBindings['subject'])
        ) {
            $subjectScope =
                (string)(
                    $inheritedBindings['subject']['runtime_scope']
                    ?? ''
                );

            $subjectRefresh =
                wayfarerRuntimeStoryletPresetCharacterBinding(
                    $pdo,
                    $gameId,
                    $linkedStorylet,
                    $runtimeState,
                    $subjectScope,
                    'subject',
                    (string)(
                        $inheritedBindings['subject']['label']
                        ?? 'Subject'
                    )
                );

            if (($subjectRefresh['error'] ?? '') !== '') {
                throw new RuntimeException(
                    (string)$subjectRefresh['error']
                );
            }

            if (is_array($subjectRefresh['binding'] ?? null)) {
                $linkedPresetBindings['subject'] =
                    $subjectRefresh['binding'];
            }
        }

        $bindingResult =
            wayfarerRuntimeResolveStoryletBindings(
                $pdo,
                $gameId,
                $linkedStorylet,
                $runtimeState,
                $linkedPresetBindings
            );

        if (
            ($bindingResult['error'] ?? '') !==
            ''
        ) {
            throw new RuntimeException(
                (string)$bindingResult['error']
            );
        }

        $resolvedBindings =
            is_array(
                $bindingResult['bindings']
                ?? null
            )
                ? $bindingResult['bindings']
                : [];

        /* WAYFARER_PERSISTENT_STORYLET_SUBJECT_V88 */
        $inheritedBindings =
            isset($resolvedBindings['subject']) &&
            is_array($resolvedBindings['subject'])
                ? [
                    'subject' => $resolvedBindings['subject'],
                ]
                : [];

        $effects =
            wayfarerRuntimeApplyStoryletEffects(
                $pdo,
                $gameId,
                $linkedStorylet,
                $runtimeState,
                $resolvedBindings
            );

        $occurrence =
            wayfarerRuntimeIncrementStoryletOccurrence(
                $runtimeState,
                $nextStoryletId
            );

        $chain[] = [
            'storylet_id' =>
                $nextStoryletId,
            'bindings' =>
                $resolvedBindings,
            'effects' =>
                $effects,
            'occurrence' =>
                $occurrence,
        ];

        $nextTransitionId =
            wayfarerRuntimeConsumeStoryletTransition(
                $runtimeState
            );

        if ($nextTransitionId <= 0) {
            return [
                'storylet' =>
                    $linkedStorylet,
                'bindings' =>
                    $resolvedBindings,
                'effects' =>
                    $effects,
                'occurrence' =>
                    $occurrence,
                'chain' =>
                    $chain,
            ];
        }

        $nextStoryletId =
            $nextTransitionId;
    }

    throw new RuntimeException(
        'Storylet Continue To did not resolve to a valid Storylet.'
    );
}


/*
 * Enter a root Storylet from an internal gameplay event while already inside
 * the caller's locked runtime transaction. Status Outcomes use this path so
 * they can supply the affected character as the persistent "subject" binding.
 * WAYFARER_TRIGGERED_STORYLET_RUNTIME_V88
 */
function wayfarerRuntimeEnterTriggeredStoryletInState(
    PDO $pdo,
    int $gameId,
    int $storyletId,
    array &$runtimeState,
    array $presetBindings = [],
    string $trigger = 'event'
): array {
    if (
        isset($runtimeState['runtime']['presentation']) &&
        is_array($runtimeState['runtime']['presentation'])
    ) {
        throw new RuntimeException(
            'A triggered Storylet cannot open while another presentation is active.'
        );
    }

    $storylet =
        wayfarerRuntimeLoadStorylet(
            $pdo,
            $gameId,
            $storyletId
        );

    if (!$storylet) {
        throw new RuntimeException(
            'Triggered Storylet could not be found.'
        );
    }

    if (!empty($storylet['parent_storylet_id'])) {
        throw new RuntimeException(
            'Triggered Storylets must be root Storylets.'
        );
    }

    if (
        strtolower(trim((string)($storylet['status'] ?? 'draft'))) !== 'active'
    ) {
        throw new RuntimeException(
            'Triggered Storylet is not Active.'
        );
    }

    wayfarerRuntimeEnsureStoryletTargetState(
        $pdo,
        $gameId,
        $runtimeState
    );

    if (
        !wayfarerRuntimeStoryletIsEligible(
            $storylet,
            $runtimeState
        )
    ) {
        throw new RuntimeException(
            'Triggered Storylet is not currently eligible.'
        );
    }

    $config =
        $storylet['_runtime_config']
        ?? [];

    if (
        max(0, (int)($config['tick_cost'] ?? 0)) > 0
    ) {
        throw new RuntimeException(
            'Triggered Storylet Tick Cost runtime is not implemented yet. Set Tick Cost to 0.'
        );
    }

    $bindingResult =
        wayfarerRuntimeResolveStoryletBindings(
            $pdo,
            $gameId,
            $storylet,
            $runtimeState,
            $presetBindings
        );

    if (($bindingResult['error'] ?? '') !== '') {
        throw new RuntimeException(
            (string)$bindingResult['error']
        );
    }

    $resolvedBindings =
        is_array($bindingResult['bindings'] ?? null)
            ? $bindingResult['bindings']
            : [];

    $effects =
        wayfarerRuntimeApplyStoryletEffects(
            $pdo,
            $gameId,
            $storylet,
            $runtimeState,
            $resolvedBindings
        );

    $occurrence =
        wayfarerRuntimeIncrementStoryletOccurrence(
            $runtimeState,
            $storyletId
        );

    $presentationStorylet = $storylet;
    $presentationBindings = $resolvedBindings;
    $presentationOccurrence = $occurrence;
    $presentationTrigger = strtolower(trim($trigger));

    $transitionId =
        wayfarerRuntimeConsumeStoryletTransition(
            $runtimeState
        );

    if ($transitionId > 0) {
        $linkedResult =
            wayfarerRuntimeEnterLinkedRootStorylet(
                $pdo,
                $gameId,
                $transitionId,
                $runtimeState,
                [
                    (string)$storyletId => true,
                ],
                isset($resolvedBindings['subject']) &&
                is_array($resolvedBindings['subject'])
                    ? [
                        'subject' => $resolvedBindings['subject'],
                    ]
                    : []
            );

        $presentationStorylet = $linkedResult['storylet'];
        $presentationBindings = $linkedResult['bindings'];
        $presentationOccurrence = $linkedResult['occurrence'];
        $presentationTrigger = 'transition';
    }

    $presentationStoryletId =
        (int)($presentationStorylet['id'] ?? 0);

    $runtimeState['runtime']['presentation'] = [
        'type' => 'storylet',
        'id' => $presentationStoryletId,
        'phase' => 'presentation',
        'trigger' => $presentationTrigger,
        'tick' => (int)($runtimeState['runtime']['tick'] ?? 0),
        'bindings' => $presentationBindings,
    ];

    $runtimeState['runtime']['last_storylet_entry'] = [
        'storylet_id' => $presentationStoryletId,
        'parent_storylet_id' =>
            (int)($presentationStorylet['parent_storylet_id'] ?? 0),
        'entry_mode' => $presentationTrigger,
        'occurrence' => $presentationOccurrence,
        'bindings' => $presentationBindings,
        'tick' => (int)($runtimeState['runtime']['tick'] ?? 0),
    ];

    return [
        'storylet' => $presentationStorylet,
        'bindings' => $presentationBindings,
        'effects' => $effects,
        'occurrence' => $presentationOccurrence,
        'presentation' => $runtimeState['runtime']['presentation'],
    ];
}


function wayfarerRuntimeApplyStoryletEffects(
    PDO $pdo,
    int $gameId,
    array $storylet,
    array &$runtimeState,
    array $bindings = []
): array {

    $config =
        isset($storylet['_runtime_config']) &&
        is_array($storylet['_runtime_config'])
            ? $storylet['_runtime_config']
            : wayfarerRuntimeDecodeConfig(
                $storylet['config']
                    ?? null
            );

    $effects =
        $config['effects']
        ?? [];

    if (!is_array($effects)) {
        $effects = [];
    }

    $regionId =
        (int)(
            $runtimeState['navigation']['region_id']
            ?? 0
        );

    $traitDefinitions =
        wayfarerRuntimeStoryletTraitDefinitions(
            $pdo,
            $gameId,
            $runtimeState
        );

    wayfarerRuntimeClampApplicableTraitState(
        $runtimeState,
        $traitDefinitions,
        $regionId
    );

    $reports = [];

    foreach ($effects as $effect) {
        if (!is_array($effect)) {
            throw new RuntimeException(
                'Malformed Storylet Effect.'
            );
        }

        $materialized =
            wayfarerRuntimeMaterializeStoryletBindingEffect(
                $effect,
                $bindings
            );

        if (
            ($materialized['error'] ?? '') !==
            ''
        ) {
            throw new RuntimeException(
                'Storylet Binding Effect failed: ' .
                (string)$materialized['error']
            );
        }

        $runtimeEffect =
            $materialized['effect']
            ?? $effect;

        if (
            (string)(
                $runtimeEffect['target_scope']
                ?? ''
            ) === 'storylet' &&
            (string)(
                $runtimeEffect['target_type']
                ?? ''
            ) === 'transition'
        ) {
            $selection =
                wayfarerRuntimeSelectEffectBranch(
                    $runtimeState,
                    $runtimeEffect,
                    $regionId
                );

            if (
                ($selection['error'] ?? '') !==
                ''
            ) {
                throw new RuntimeException(
                    'Storylet Continue To Effect failed: ' .
                    (string)$selection['error']
                );
            }

            $matched =
                !empty(
                    $selection['matched']
                );

            $branch =
                is_array(
                    $selection['branch']
                    ?? null
                )
                    ? $selection['branch']
                    : [];

            $operation =
                strtolower(
                    trim(
                        (string)(
                            $branch['operation']
                            ?? 'none'
                        )
                    )
                );

            $targetStoryletId =
                (int)(
                    $runtimeEffect['target_id']
                    ?? 0
                );

            $applied =
                $matched &&
                $operation === 'continue';

            if ($applied) {
                if ($targetStoryletId <= 0) {
                    throw new RuntimeException(
                        'Storylet Continue To Effect has an invalid destination.'
                    );
                }

                $existingTransition =
                    (int)(
                        $runtimeState['runtime']['pending_storylet_transition']
                        ?? 0
                    );

                if (
                    $existingTransition > 0 &&
                    $existingTransition !==
                        $targetStoryletId
                ) {
                    throw new RuntimeException(
                        'More than one Storylet Continue To Effect matched.'
                    );
                }

                $runtimeState['runtime']['pending_storylet_transition'] =
                    $targetStoryletId;
            }

            $reports[] = [
                'scope' =>
                    'storylet',
                'type' =>
                    'transition',
                'target_id' =>
                    (string)$targetStoryletId,
                'operation' =>
                    $operation,
                'applied' =>
                    $applied,
                'matched' =>
                    $matched,
                'branch_index' =>
                    $selection['branch_index']
                    ?? null,
                'error' =>
                    '',
            ];

            continue;
        }

        $report =
            wayfarerApplyRuntimeOneTimeEffect(
                $runtimeState,
                $runtimeEffect,
                $regionId,
                $traitDefinitions
            );

        if (!empty($report['error'])) {
            throw new RuntimeException(
                'Storylet Effect failed: ' .
                (string)$report['error']
            );
        }

        $reports[] =
            $report;
    }

    /* WAYFARER_STORYLET_EFFECT_FEEDBACK_V70 */
    if (
        !isset($runtimeState['runtime']) ||
        !is_array($runtimeState['runtime'])
    ) {
        $runtimeState['runtime'] = [];
    }

    $runtimeState['runtime']['last_storylet_effects'] = [
        'storylet_id' =>
            (int)(
                $storylet['id']
                ?? 0
            ),

        'tick' =>
            (int)(
                $runtimeState['runtime']['tick']
                ?? 0
            ),

        'reports' =>
            $reports,

        'changes' =>
            wayfarerRuntimeBuildEffectChangeEvents(
                $pdo,
                $gameId,
                $runtimeState,
                $reports
            ),
    ];

    return $reports;
}


function wayfarerRuntimeIncrementStoryletOccurrence(
    array &$runtimeState,
    int $storyletId
): int {

    if (
        !isset($runtimeState['storylets']) ||
        !is_array($runtimeState['storylets'])
    ) {
        $runtimeState['storylets'] = [];
    }

    $key =
        (string)$storyletId;

    if (
        !isset($runtimeState['storylets'][$key]) ||
        !is_array($runtimeState['storylets'][$key])
    ) {
        $runtimeState['storylets'][$key] = [];
    }

    $count =
        wayfarerRuntimeStoryletOccurrenceCount(
            $runtimeState,
            $storyletId
        ) + 1;

    $runtimeState['storylets'][$key]['occurrences'] =
        $count;

    $runtimeState['storylets'][$key]['last_entered_tick'] =
        (int)(
            $runtimeState['runtime']['tick']
            ?? 0
        );

    return $count;
}


function wayfarerRuntimeEnterStorylet(
    PDO $pdo,
    int $gameUserId,
    int $storyletId,
    string $entryMode = 'action',
    int $expectedParentStoryletId = 0
): array {

    $entryMode =
        strtolower(
            trim($entryMode)
        );

    if (
        $entryMode !== 'action' &&
        $entryMode !== 'branch'
    ) {
        throw new RuntimeException(
            'Invalid Storylet entry mode.'
        );
    }

    try {
        $pdo->beginTransaction();

        $stmt =
            $pdo->prepare(
                "
                SELECT
                    id,
                    game_id,
                    state
                FROM wf_game_users
                WHERE id = ?
                LIMIT 1
                FOR UPDATE
                "
            );

        $stmt->execute([
            $gameUserId
        ]);

        $row =
            $stmt->fetch(
                PDO::FETCH_ASSOC
            );

        if (!$row) {
            throw new RuntimeException(
                'Game-user runtime record not found.'
            );
        }

        $gameId =
            (int)$row['game_id'];

        $state =
            wayfarerRuntimeDecodeState(
                $row['state']
            );

        if (
            !isset($state['runtime']) ||
            !is_array($state['runtime'])
        ) {
            $state['runtime'] = [];
        }

        if (
            isset($state['runtime']['ending']) &&
            is_array($state['runtime']['ending'])
        ) {
            throw new RuntimeException(
                'This game has ended.'
            );
        }

        $activePresentation =
            $state['runtime']['presentation']
            ?? null;

        $storylet =
            wayfarerRuntimeLoadStorylet(
                $pdo,
                $gameId,
                $storyletId
            );

        if (!$storylet) {
            throw new RuntimeException(
                'Storylet not found.'
            );
        }

        if ($entryMode === 'action') {
            if (is_array($activePresentation)) {
                throw new RuntimeException(
                    'Continue the current presentation before choosing an Action.'
                );
            }

            if (
                !empty($storylet['parent_storylet_id']) ||
                strtolower(
                    trim(
                        (string)(
                            $storylet['trigger_type']
                            ?? ''
                        )
                    )
                ) !== 'manual'
            ) {
                throw new RuntimeException(
                    'That Storylet is not an available root Manual Action.'
                );
            }
        } else {
            if (
                !is_array($activePresentation) ||
                (string)(
                    $activePresentation['type']
                    ?? ''
                ) !== 'storylet' ||
                (int)(
                    $activePresentation['id']
                    ?? 0
                ) <= 0
            ) {
                throw new RuntimeException(
                    'There is no active Storylet Branch to choose from.'
                );
            }

            $parentStoryletId =
                (int)(
                    $activePresentation['id']
                    ?? 0
                );

            if (
                $expectedParentStoryletId > 0 &&
                $parentStoryletId !==
                    $expectedParentStoryletId
            ) {
                throw new RuntimeException(
                    'The active Storylet changed before the Branch was selected.'
                );
            }

            if (
                (int)(
                    $storylet['parent_storylet_id']
                    ?? 0
                ) !== $parentStoryletId
            ) {
                throw new RuntimeException(
                    'That Storylet is not a Branch of the active Storylet.'
                );
            }
        }

        wayfarerRuntimeEnsureStoryletTargetState(
            $pdo,
            $gameId,
            $state
        );

        if (
            !wayfarerRuntimeStoryletIsEligible(
                $storylet,
                $state
            ) ||
            (
                $entryMode === 'action' &&
                !wayfarerRuntimeStoryletBindingsAvailable(
                    $pdo,
                    $gameId,
                    $storylet,
                    $state
                )
            )
        ) {
            throw new RuntimeException(
                'That Storylet is no longer eligible.'
            );
        }

        $config =
            $storylet['_runtime_config']
            ?? [];

        $tickCost =
            max(
                0,
                (int)(
                    $config['tick_cost']
                    ?? 0
                )
            );

        /*
         * V59 proves interactive Storylets before refactoring the normal tick
         * pipeline into a reusable "consume N ticks" helper. Reject non-zero
         * cost rather than silently ignoring authored time passage.
         */
        if ($tickCost > 0) {
            throw new RuntimeException(
                'Storylet Tick Cost runtime is not implemented yet. Set Tick Cost to 0 for V59.'
            );
        }

        /* WAYFARER_STORYLET_BINDING_RUNTIME_V79 */
        /* WAYFARER_PERSISTENT_STORYLET_SUBJECT_V88 */
        $presetBindings = [];

        if (
            $entryMode === 'branch' &&
            isset($activePresentation['bindings']['subject']) &&
            is_array($activePresentation['bindings']['subject'])
        ) {
            $subjectScope =
                (string)(
                    $activePresentation['bindings']['subject']['runtime_scope']
                    ?? ''
                );

            $subjectRefresh =
                wayfarerRuntimeStoryletPresetCharacterBinding(
                    $pdo,
                    $gameId,
                    $storylet,
                    $state,
                    $subjectScope,
                    'subject',
                    (string)(
                        $activePresentation['bindings']['subject']['label']
                        ?? 'Subject'
                    )
                );

            if (($subjectRefresh['error'] ?? '') !== '') {
                throw new RuntimeException(
                    (string)$subjectRefresh['error']
                );
            }

            if (is_array($subjectRefresh['binding'] ?? null)) {
                $presetBindings['subject'] =
                    $subjectRefresh['binding'];
            }
        }

        $bindingResult =
            wayfarerRuntimeResolveStoryletBindings(
                $pdo,
                $gameId,
                $storylet,
                $state,
                $presetBindings
            );

        if (
            ($bindingResult['error'] ?? '') !==
            ''
        ) {
            throw new RuntimeException(
                (string)$bindingResult['error']
            );
        }

        $resolvedBindings =
            is_array(
                $bindingResult['bindings']
                ?? null
            )
                ? $bindingResult['bindings']
                : [];

        $effects =
            wayfarerRuntimeApplyStoryletEffects(
                $pdo,
                $gameId,
                $storylet,
                $state,
                $resolvedBindings
            );

        $occurrence =
            wayfarerRuntimeIncrementStoryletOccurrence(
                $state,
                $storyletId
            );

        if ($entryMode === 'branch') {
            $state['runtime']['last_presentation'] =
                $activePresentation;
        }

        $presentationStorylet =
            $storylet;

        $presentationBindings =
            $resolvedBindings;

        $presentationOccurrence =
            $occurrence;

        $presentationTrigger =
            $entryMode;

        $transitionId =
            wayfarerRuntimeConsumeStoryletTransition(
                $state
            );

        if ($transitionId > 0) {
            $linkedResult =
                wayfarerRuntimeEnterLinkedRootStorylet(
                    $pdo,
                    $gameId,
                    $transitionId,
                    $state,
                    [
                        (string)$storyletId =>
                            true,
                    ],
                    isset($resolvedBindings['subject']) &&
                    is_array($resolvedBindings['subject'])
                        ? [
                            'subject' => $resolvedBindings['subject'],
                        ]
                        : []
                );

            $presentationStorylet =
                $linkedResult['storylet'];

            $presentationBindings =
                $linkedResult['bindings'];

            $presentationOccurrence =
                $linkedResult['occurrence'];

            $presentationTrigger =
                'transition';

            $state['runtime']['last_storylet_transition'] = [
                'from_storylet_id' =>
                    $storyletId,
                'to_storylet_id' =>
                    (int)(
                        $presentationStorylet['id']
                        ?? 0
                    ),
                'chain' =>
                    $linkedResult['chain'],
                'tick' =>
                    (int)(
                        $state['runtime']['tick']
                        ?? 0
                    ),
            ];
        } else {
            unset(
                $state['runtime']['last_storylet_transition']
            );
        }

        $presentationStoryletId =
            (int)(
                $presentationStorylet['id']
                ?? 0
            );

        $state['runtime']['presentation'] = [
            'type' => 'storylet',
            'id' => $presentationStoryletId,
            'phase' => 'presentation',
            'trigger' => $presentationTrigger,
            'tick' =>
                (int)(
                    $state['runtime']['tick']
                    ?? 0
                ),
            'bindings' =>
                $presentationBindings,
        ];

        $state['runtime']['last_storylet_entry'] = [
            'storylet_id' =>
                $presentationStoryletId,
            'parent_storylet_id' =>
                (int)(
                    $presentationStorylet['parent_storylet_id']
                    ?? 0
                ),
            'entry_mode' =>
                $presentationTrigger,
            'occurrence' =>
                $presentationOccurrence,
            'bindings' =>
                $presentationBindings,
            'tick' =>
                (int)(
                    $state['runtime']['tick']
                    ?? 0
                ),
        ];

        $ending =
            wayfarerRuntimeEvaluateGameEndings(
                $pdo,
                $gameId,
                $state
            );

        $encoded =
            wayfarerRuntimeEncodeState(
                $state
            );

        $update =
            $pdo->prepare(
                "
                UPDATE wf_game_users
                SET state = ?
                WHERE id = ?
                "
            );

        $update->execute([
            $encoded,
            $gameUserId,
        ]);

        $pdo->commit();

        $presentation =
            $state['runtime']['presentation']
            ?? null;

        return [
            'game_user_id' =>
                (int)$row['id'],
            'game_id' =>
                $gameId,
            'state' =>
                $state,
            'context' =>
                wayfarerRuntimePlayerContext(
                    $pdo,
                    $gameId,
                    $state
                ),
            'presentation' =>
                is_array($presentation)
                    ? $presentation
                    : null,
            'ending' =>
                $ending,
            'effects' =>
                $effects,
            'occurrence' =>
                $presentationOccurrence,
            'actions' =>
                $ending === null &&
                !is_array($presentation)
                    ? wayfarerRuntimeEligibleRootManualStorylets(
                        $pdo,
                        $gameId,
                        $state
                    )
                    : [],
        ];

    } catch (Throwable $exception) {
        if ($pdo->inTransaction()) {
            $pdo->rollBack();
        }

        throw $exception;
    }
}



==============================================================================
FILE: play/includes/tick-panel.php
==============================================================================

<?php

/*
 * Minimal development UI for proving manual and automatic tick requests.
 *
 * This file is included near the bottom of play/index.php.
 */

require_once __DIR__ . '/runtime.php';

if (
    !isset($pdo) ||
    !($pdo instanceof PDO)
) {
    require_once __DIR__ . '/../../config/database.php';
}

if (session_status() !== PHP_SESSION_ACTIVE) {
    session_start();
}

if (
    empty($_SESSION['wayfarer_tick_csrf']) ||
    !is_string(
        $_SESSION['wayfarer_tick_csrf']
    )
) {
    $_SESSION['wayfarer_tick_csrf'] =
        bin2hex(
            random_bytes(32)
        );
}

/*
 * WAYFARER_ACTION_SCREEN_V39
 *
 * Author controls inspect the currently loaded playthrough first. The old
 * first-record fallback remains only for standalone development use.
 */
$requestedGameUserId =
    isset($gameUser['game_user_id'])
        ? (int)$gameUser['game_user_id']
        : (
            isset($_GET['game_user_id'])
                ? (int)$_GET['game_user_id']
                : null
        );

$tickPanelError = '';

try {

    $tickGameUserId =
        wayfarerRuntimeResolveGameUserId(
            $pdo,
            $requestedGameUserId
        );

    $tickRuntime =
        wayfarerRuntimeLoad(
            $pdo,
            $tickGameUserId
        );

} catch (Throwable $exception) {

    $tickRuntime = null;

    $tickPanelError =
        $exception->getMessage();
}

?>

<hr>

<section
    id="wayfarer-tick-test"
    aria-labelledby="wayfarer-tick-heading"
>
    <h2 id="wayfarer-tick-heading">
        Tick Runtime Test
    </h2>

    <?php if ($tickPanelError !== ''): ?>

        <p style="color:red;">
            <?= htmlspecialchars(
                $tickPanelError
            ) ?>
        </p>

    <?php else: ?>

        <p>
            Persisted tick:
            <strong id="wayfarer-tick-value">
                <?= (int)$tickRuntime['tick'] ?>
            </strong>
        </p>

        <p>
            Runtime status:
            <strong id="wayfarer-tick-status">
                Paused
            </strong>
        </p>

        <p>
            <button
                type="button"
                id="wayfarer-tick-once"
            >
                Advance One Tick
            </button>

            <button
                type="button"
                id="wayfarer-tick-auto"
            >
                Start Auto
            </button>

            <button
                type="button"
                id="wayfarer-tick-pause"
                disabled
            >
                Pause
            </button>
        </p>

        <p
            id="wayfarer-tick-message"
            aria-live="polite"
        ></p>

        <!-- Runtime bootstrap moved to player scope in v39. -->

    <?php endif; ?>

</section>



==============================================================================
FILE: play/index.php
==============================================================================

<?php

/* WAYFARER_TICK_SESSION_V14 */
if (session_status() !== PHP_SESSION_ACTIVE) {
    session_start();
}


ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

require_once __DIR__ . '/../config/database.php';
require_once __DIR__ . '/includes/runtime.php';
/* WAYFARER_RUNTIME_INITIALIZATION_V31 */


// ================================================================
// DEVELOPMENT TEST CONTEXT
// ================================================================

// Temporary hard-coded values while the runtime is being built.
// Authentication will eventually determine the user.
$gameId = 1;
$userId = 1;


// ================================================================
// LOAD GAME + GAME USER
// ================================================================

$stmt = $pdo->prepare("
    SELECT
        g.id AS game_id,
        g.name AS game_name,
        g.slug AS game_slug,
        g.instructions AS game_instructions,
        g.player_slots AS player_slots,
		g.config AS game_config,
        gu.id AS game_user_id,
        gu.role AS game_user_role,
        gu.state,
        u.username,
        u.display_name
    FROM wf_game_users gu
    INNER JOIN wf_games g
        ON g.id = gu.game_id
    INNER JOIN wf_users u
        ON u.id = gu.user_id
    WHERE gu.game_id = ?
      AND gu.user_id = ?
    LIMIT 1
");

$stmt->execute([
    $gameId,
    $userId
]);

$gameUser = $stmt->fetch();

if (!$gameUser) {
    die('Game user not found.');
}


/*
 * WAYFARER_ROLE_BASED_AUTHOR_MODE_V37
 *
 * Author permission belongs to the user/game relationship, not to the user
 * globally. wf_game_users.role is therefore the canonical source.
 */
$canUseAuthorMode =
    strtolower(
        trim(
            (string)(
                $gameUser['game_user_role']
                ?? ''
            )
        )
    ) === 'author';


// ================================================================
// RUNTIME STATE
// ================================================================

$state = null;

if (!empty($gameUser['state'])) {

    $decodedState = json_decode(
        $gameUser['state'],
        true
    );

    if (is_array($decodedState)) {
        $state = $decodedState;
    }
}

/*
 * WAYFARER_ENTITY_RUNTIME_STATE_PAGE_RECOVERY_V49
 *
 * Existing development playthroughs should gain Entity state immediately on
 * page load. This is additive and does not overwrite current runtime values.
 */
if ($state !== null) {

    $runtimeRecoveryChanged =
        wayfarerRuntimeEnsureEntityState(
            $pdo,
            (int)$gameId,
            $state
        );

    /* WAYFARER_PLAYER_TRAITS_PAGE_RECOVERY_V52 */
    if (
        wayfarerRuntimeEnsurePlayerAndGameState(
            $pdo,
            (int)$gameId,
            $state
        )
    ) {
        $runtimeRecoveryChanged =
            true;
    }

    if ($runtimeRecoveryChanged) {

        $encodedRecoveredState =
            wayfarerRuntimeEncodeState(
                $state
            );

        $entityRecoveryStmt =
            $pdo->prepare(
                "
                UPDATE wf_game_users
                SET state = ?
                WHERE id = ?
                "
            );

        $entityRecoveryStmt->execute([
            $encodedRecoveredState,
            (int)$gameUser['game_user_id'],
        ]);

        /*
         * Keep Author Debug and any later page component on the same snapshot.
         */
        $gameUser['state'] =
            $encodedRecoveredState;
    }
}

// ================================================================
// INITIALIZE GAME
// ================================================================

$initializationError = '';

if (
    $_SERVER['REQUEST_METHOD'] === 'POST' &&
    ($_POST['action'] ?? '') === 'initialize' &&
    $state === null
) {

    try {

        wayfarerRuntimeInitializeGame(
            $pdo,
            (int)$gameUser['game_user_id'],
            [
                'player_names' =>
                    $_POST['player_names']
                    ?? [],
                'choices' =>
                    $_POST['setup_choices']
                    ?? [],
            ]
        );

        /*
         * Reload from persisted state so every play-page component sees the
         * exact same initialized snapshot.
         */
        header('Location: index.php');
        exit;

    } catch (Throwable $exception) {

        $initializationError =
            $exception->getMessage();
    }
}
// ================================================================
// AUTHOR MODE: GAME TRAIT DEFINITIONS
// ================================================================

$gameTraitDefinitions = [];

$gameConfig = [];

if (!empty($gameUser['game_config'])) {

    $decodedConfig = json_decode(
        $gameUser['game_config'],
        true
    );

    if (is_array($decodedConfig)) {
        $gameConfig = $decodedConfig;
    }
}

foreach ($gameConfig['traits'] ?? [] as $trait) {

    if (empty($trait['id'])) {
        continue;
    }

    $gameTraitDefinitions[$trait['id']] = $trait;
}
?>
<!DOCTYPE html>
<html lang="en">

<head>

    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <title>
        <?= htmlspecialchars($gameUser['game_name']) ?>
    </title>

    <!-- WAYFARER_COMBINED_AUTHOR_STATE_REGION_V41 -->
    <link rel="stylesheet" href="assets/play.css?v=70">
</head>

<body class="wayfarer-play-page" data-wayfarer-author-mode="<?= $canUseAuthorMode ? '1' : '0' ?>">

<?php if ($state !== null): ?>
    <!-- WAYFARER_ACTION_SCREEN_V39 -->
    <?php require __DIR__ . '/includes/runtime-bootstrap.php'; ?>
<?php endif; ?>

<h1>
    <?= htmlspecialchars($gameUser['game_name']) ?>
</h1>

<p>
    Player:
    <strong>
        <?= htmlspecialchars(
            $gameUser['display_name']
            ?: $gameUser['username']
        ) ?>
    </strong>
</p>

<hr>

<?php if ($state === null): ?>

    <!-- WAYFARER_PLAYER_START_SCREEN_V36 -->
    <?php require __DIR__ . '/includes/start-screen.php'; ?>

<?php endif; ?>


<hr>


<!-- ============================================================
     PLAYER SCENE
     ============================================================ -->

<?php if ($state !== null): ?>

    <!-- WAYFARER_PLAYER_UI_CLEANUP_V32 -->
    <!-- WAYFARER_PLAYER_SCENE_V17 -->
    <?php require __DIR__ . '/includes/scene.php'; ?>

    <!-- WAYFARER_ACTION_SCREEN_V39 -->
    <?php require __DIR__ . '/includes/action-screen.php'; ?>

    <!-- WAYFARER_LOCATION_ARRIVAL_PRESENTATION_V40 -->
    <?php require __DIR__ . '/includes/presentation-screen.php'; ?>

    <!-- WAYFARER_GAME_ENDING_SCREEN_V45 -->
    <?php require __DIR__ . '/includes/ending-screen.php'; ?>

    <!-- WAYFARER_PLAYER_HUD_V64 -->
    <?php require __DIR__ . '/includes/hud.php'; ?>

<?php endif; ?>


<!-- ============================================================
     AUTHOR MODE
     WAYFARER_ROLE_BASED_AUTHOR_MODE_V37
     ============================================================ -->

<?php if ($canUseAuthorMode): ?>

    <?php require __DIR__ . '/includes/author-mode.php'; ?>

<?php endif; ?>

<!-- WAYFARER_SMOOTH_MANUAL_PAUSE_CACHE_V46_2 -->
<script src="assets/play.js?v=64"></script>



</body>
</html>