Add guild.listing action for guild discovery by new players

Officers can broadcast a guild.listing that includes the creation block.
Fresh clients without checkpoints pick up these listings during the 24h
sync window, fetch the creation block, and hydrate the full guild data
so it appears in the recommended guilds list.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: web3blind

app/js/config.js

@@ -166,7 +166,9 @@ var VizMagicConfig = (function() {
         // Phase 5: Quests & Boss
         QUEST_ACCEPT:   'quest.accept',
         QUEST_COMPLETE: 'quest.complete',
-        BOSS_ATTACK:    'boss.attack'
+        BOSS_ATTACK:    'boss.attack',
+        // Guild discovery
+        GUILD_LISTING:  'guild.listing'
     };
 
     /** Asset formatting helpers */

app/js/engine/state-engine.js

@@ -27,6 +27,7 @@ var StateEngine = (function() {
             social: {
                 knownAccounts: []
             },
+            guildListings: [],  // [{guild_id, created_block, sender, blockNum}]
             // Phase 5: Living World
             worldBoss: null,
             quests: {},       // account → playerQuestState
@@ -285,6 +286,9 @@ var StateEngine = (function() {
             case AT.GUILD_PEACE:
                 events = events.concat(_handleGuildPeace(sender, action.data, blockNum));
                 break;
+            case AT.GUILD_LISTING:
+                events = events.concat(_handleGuildListing(sender, action.data, blockNum));
+                break;
 
             // --- Crafting ---
             case AT.CRAFT:
@@ -739,6 +743,32 @@ var StateEngine = (function() {
         return [{ type: 'guild_peace', warRef: data.war_ref, declarer: sender }];
     }
 
+    function _handleGuildListing(sender, data, blockNum) {
+        if (!data.guild_id || !data.created_block) return [];
+        // Verify sender is a member of the guild (if guild is in state)
+        var guild = worldState.guilds[data.guild_id];
+        if (guild && !guild.members[sender]) return [];
+
+        if (!worldState.guildListings) worldState.guildListings = [];
+        // Deduplicate: keep only the latest listing per guild
+        for (var i = worldState.guildListings.length - 1; i >= 0; i--) {
+            if (worldState.guildListings[i].guild_id === data.guild_id) {
+                worldState.guildListings.splice(i, 1);
+            }
+        }
+        worldState.guildListings.push({
+            guild_id: data.guild_id,
+            created_block: data.created_block | 0,
+            sender: sender,
+            blockNum: blockNum
+        });
+        // Keep max 50 listings
+        while (worldState.guildListings.length > 50) {
+            worldState.guildListings.shift();
+        }
+        return [{ type: 'guild_listing', guildId: data.guild_id, sender: sender, createdBlock: data.created_block }];
+    }
+
     // ==========================================
     // Territory / Siege Action Handlers
     // ==========================================

app/js/i18n/en.js

@@ -411,6 +411,9 @@ var LangEN = {
     guild_invite_send: 'Send Invite',
     guild_invite_sent: 'Invite sent!',
     guild_invite_received: 'You received a guild invite. Opening the guild screen.',
+    guild_listing: 'Promote Guild',
+    guild_listing_sent: 'Guild promoted! It will be visible to other players.',
+    guild_listing_hint: 'Promote your guild once a day so new players can discover it.',
     guild_pending_invites: 'Pending Invites',
     guild_accept_invite: 'Accept Invite',
     guild_invited_by: 'Invited by',

app/js/i18n/ru.js

@@ -411,6 +411,9 @@ var LangRU = {
     guild_invite_send: 'Отправить приглашение',
     guild_invite_sent: 'Приглашение отправлено!',
     guild_invite_received: 'Вас пригласили в гильдию. Открываю раздел гильдии.',
+    guild_listing: 'Продвинуть гильдию',
+    guild_listing_sent: 'Гильдия продвигается! Она будет видна другим игрокам.',
+    guild_listing_hint: 'Продвигайте гильдию раз в сутки, чтобы она была видна новым игрокам.',
     guild_pending_invites: 'Ожидающие приглашения',
     guild_accept_invite: 'Принять приглашение',
     guild_invited_by: 'Пригласил',

app/js/protocols/guild-protocol.js

@@ -181,6 +181,22 @@ var GuildProtocol = (function() {
         };
     }
 
+    /**
+     * Create guild.listing action — advertise guild for discovery
+     * @param {string} guildId
+     * @param {number} createdBlock - block where guild.create was broadcast
+     * @returns {Object}
+     */
+    function createGuildListingAction(guildId, createdBlock) {
+        return {
+            t: AT.GUILD_LISTING,
+            d: {
+                guild_id: guildId,
+                created_block: createdBlock | 0
+            }
+        };
+    }
+
     // --- Broadcast Helpers ---
 
     /**
@@ -244,6 +260,14 @@ var GuildProtocol = (function() {
         broadcastGuildAction(action, callback);
     }
 
+    /**
+     * Broadcast guild listing (advertise)
+     */
+    function broadcastGuildListing(guildId, createdBlock, callback) {
+        var action = createGuildListingAction(guildId, createdBlock);
+        broadcastGuildAction(action, callback);
+    }
+
     /**
      * Broadcast peace
      */
@@ -288,6 +312,7 @@ var GuildProtocol = (function() {
         createSiegeDeclareAction: createSiegeDeclareAction,
         createSiegeCommitAction: createSiegeCommitAction,
         createTerritoryClaimAction: createTerritoryClaimAction,
+        createGuildListingAction: createGuildListingAction,
 
         // Broadcast wrappers
         broadcastGuildAction: broadcastGuildAction,
@@ -300,6 +325,7 @@ var GuildProtocol = (function() {
         broadcastDeclarePeace: broadcastDeclarePeace,
         broadcastDeclareSiege: broadcastDeclareSiege,
         broadcastSiegeCommit: broadcastSiegeCommit,
-        broadcastTerritoryClaim: broadcastTerritoryClaim
+        broadcastTerritoryClaim: broadcastTerritoryClaim,
+        broadcastGuildListing: broadcastGuildListing
     };
 })();

app/js/ui/screens/guild.js

@@ -8,6 +8,7 @@ var GuildScreen = (function() {
 
     var t = Helpers.t;
     var _seenGuildNotifications = {};
+    var _listingFetchInProgress = {};
 
     function render() {
         var container = Helpers.$('screen-guild');
@@ -184,6 +185,10 @@ var GuildScreen = (function() {
 
             html += '<button class="btn btn-secondary guild-btn" id="btn-guild-patronage" aria-label="' + t('guild_patronage') + '">';
             html += '\uD83E\uDD1D ' + t('guild_patronage') + '</button>';
+
+            html += '<button class="btn btn-secondary guild-btn" id="btn-guild-listing" aria-label="' + t('guild_listing') + '">';
+            html += '\uD83D\uDCE3 ' + t('guild_listing') + '</button>';
+            html += '<p class="guild-listing-hint">' + t('guild_listing_hint') + '</p>';
         }
 
         html += '<button class="btn btn-secondary guild-btn" id="btn-guild-treasury" aria-label="' + t('guild_treasury') + '">';
@@ -211,6 +216,8 @@ var GuildScreen = (function() {
      * Render no-guild state: recommended guilds + create button
      */
     function _renderNoGuild(container, state, user) {
+        // Kick off async hydration of guilds from listings
+        _hydrateGuildListings(state);
         var html = '';
         var pendingInvites = _getPendingInvites(state, user);
         html += '<div class="guild-hall" role="region" aria-label="' + t('guild_title') + '">';
@@ -293,6 +300,59 @@ var GuildScreen = (function() {
         return invites;
     }
 
+    /**
+     * Hydrate guilds from listings — fetch creation blocks for unknown guilds.
+     * Runs asynchronously; re-renders guild screen when new data arrives.
+     */
+    function _hydrateGuildListings(state) {
+        var listings = state.guildListings;
+        if (!listings || listings.length === 0) return;
+        for (var i = 0; i < listings.length; i++) {
+            var entry = listings[i];
+            var gid = entry.guild_id;
+            var createdBlock = entry.created_block;
+            if (!gid || !createdBlock) continue;
+            // Skip if guild already in state and not a placeholder
+            if (state.guilds[gid] && !state.guilds[gid].isPlaceholder) continue;
+            // Skip if already fetching
+            if (_listingFetchInProgress[gid]) continue;
+            _listingFetchInProgress[gid] = true;
+            (function(guildId, block) {
+                viz.api.getBlock(block, function(err, blockData) {
+                    delete _listingFetchInProgress[guildId];
+                    if (err || !blockData || !blockData.transactions) return;
+                    // Find guild.create for this guild_id in the block
+                    for (var ti = 0; ti < blockData.transactions.length; ti++) {
+                        var tx = blockData.transactions[ti];
+                        if (!tx.operations) continue;
+                        for (var oi = 0; oi < tx.operations.length; oi++) {
+                            var op = tx.operations[oi];
+                            if (op[0] !== 'custom' || op[1].id !== 'VM') continue;
+                            try {
+                                var parsed = JSON.parse(op[1].json);
+                                if (parsed.t !== 'guild.create') continue;
+                                if (parsed.d && parsed.d.id === guildId) {
+                                    var sender = (op[1].required_regular_auths && op[1].required_regular_auths[0]) || '';
+                                    var currentState = StateEngine.getState();
+                                    var guild = GuildSystem.createGuild(guildId, sender, parsed.d, block);
+                                    if (guild) {
+                                        currentState.guilds[guildId] = guild;
+                                        // Re-render if guild screen is active
+                                        var container = Helpers.$('screen-guild');
+                                        if (container && !container.getAttribute('aria-hidden')) {
+                                            render();
+                                        }
+                                    }
+                                    return;
+                                }
+                            } catch (e) {}
+                        }
+                    }
+                });
+            })(gid, createdBlock);
+        }
+    }
+
     /**
      * Get list of all guilds for display
      */
@@ -382,6 +442,23 @@ var GuildScreen = (function() {
             });
         }
 
+        // Listing (advertise) button
+        var listingBtn = container.querySelector('#btn-guild-listing');
+        if (listingBtn) {
+            listingBtn.addEventListener('click', function() {
+                listingBtn.disabled = true;
+                GuildProtocol.broadcastGuildListing(guild.id, guild.createdBlock || 0, function(err) {
+                    listingBtn.disabled = false;
+                    if (err) {
+                        Toast.error(t('error_network'));
+                    } else {
+                        Toast.success(t('guild_listing_sent'));
+                        SoundManager.play('tap');
+                    }
+                });
+            });
+        }
+
         var settingsBtn = container.querySelector('#btn-guild-settings');
         if (settingsBtn) {
             settingsBtn.addEventListener('click', function() {
@@ -766,7 +843,7 @@ var GuildScreen = (function() {
      * Called once when the screen module loads.
      */
     function init() {
-        var events = ['guild_created', 'guild_joined', 'guild_left', 'guild_promoted', 'guild_invite'];
+        var events = ['guild_created', 'guild_joined', 'guild_left', 'guild_promoted', 'guild_invite', 'guild_listing'];
         for (var i = 0; i < events.length; i++) {
             Helpers.EventBus.on(events[i], function() {
                 // Re-render only if guild screen is currently visible