docs: add transport migration roadmap

Author: steveseguin

.github/workflows/firefox-sign.yml

@@ -60,7 +60,13 @@ jobs:
         run: npm install --global "web-ext@${WEB_EXT_VERSION}"
 
       - name: Validate Firefox build
-        run: web-ext lint --source-dir "$WEB_EXT_SOURCE_DIR" --self-hosted
+        run: |
+          set -euo pipefail
+          lint_args=()
+          if [[ "$WEB_EXT_CHANNEL" == "unlisted" ]]; then
+            lint_args+=(--self-hosted)
+          fi
+          web-ext lint --source-dir "$WEB_EXT_SOURCE_DIR" "${lint_args[@]}"
 
       - name: Submit add-on to AMO
         id: submit

README.md

@@ -205,6 +205,7 @@ Much more than just an overlay - Social Stream Ninja is a complete chat ecosyste
 - circle.so (and community domains like community.talkinghealthtech.com or members.firstinfam.com)
 - sooplive.com (pop out the chat to use; supports https://play.sooplive.com/*?vtype=chat)
 - flextv.co.kr (open the live channel page with chat visible)
+- sealteamsloth.com (open the pop-out chat: https://sealteamsloth.com/popout-chat/*)
 - on24.com ( Q&A - questions supported)
 - meetme
 - moonbeam.stream (no pop out)

TODO.md

@@ -0,0 +1,70 @@
+# Server Transport Migration Roadmap
+
+## Current state
+
+- [x] Cross-transport dedupe is deployed on beta.
+- [x] The socket-only gate is present but requires links with `v=3.52.0` or newer.
+- [ ] The guarded pages are deployed to production.
+- [ ] Production go-live time is recorded below.
+- [ ] Version `3.52.0` is released.
+
+Production go-live (Day 0): `NOT STARTED`
+
+The 30-day countdown starts only when the guarded pages go live on production. Do not bump the extension to `3.52.0` before the Day 30 readiness review passes.
+
+## Phase 1: Production rollout - Day 0
+
+- [ ] Deploy the guarded page changes to production.
+- [ ] Record the exact production date and time above.
+- [ ] Confirm fresh production copies of representative pages contain the transport gate and dedupe guard.
+- [ ] Run `node scripts/transport-dedupe-regression.test.cjs` against the production commit.
+- [ ] Keep the extension version below `3.52.0`.
+- [ ] Keep additive delivery experimental; do not enable it by default.
+
+## Phase 2: Cache and production soak - Days 1-30
+
+- [ ] Leave the `3.52.0` gate inactive for the full 30 days.
+- [ ] Monitor reports of duplicate or missing messages.
+- [ ] Test additive delivery with existing `v=3.50.5` links; they should remain dual-listen and render once.
+- [ ] Test links without `server2`; they should remain bridge-only.
+- [ ] Test representative chat overlays, emotes, events, hype, games, and the dock.
+- [ ] Do not treat an old saved OBS URL as updated merely because its cached page has refreshed.
+
+## Phase 3: Readiness review - Day 30
+
+All items must pass before releasing `3.52.0`:
+
+- [ ] Thirty full days have passed since the recorded production go-live time.
+- [ ] Production is serving the guarded page code.
+- [ ] The dedupe regression test passes.
+- [ ] Fresh and old saved links both render messages once during additive delivery.
+- [ ] No unresolved duplicate-message or dropped-message regression remains.
+- [ ] The socket-outage tradeoff is accepted: a socket-only overlay cannot receive the P2P fallback while its bridge is disconnected.
+
+## Phase 4: Release `3.52.0`
+
+- [ ] Bump the extension manifest to `3.52.0`.
+- [ ] Release the updated extension.
+- [ ] Confirm newly generated links contain `v=3.52.0` or newer.
+- [ ] Confirm eligible read-only overlays using `server2` stop opening the legacy bridge.
+- [ ] Confirm old saved links remain dual-listen and are protected by dedupe.
+- [ ] Monitor the release before changing the additive-delivery default.
+
+## Phase 5: Make additive delivery the default
+
+Do this no earlier than September 1, 2026, and only after the `3.52.0` release has completed its monitoring period.
+
+- [ ] Change additive delivery from opt-in to the default; the existing date comment does not perform this change automatically.
+- [ ] Update or remove the experimental setting text in the popup.
+- [ ] Retest fresh `3.52.0+` links, old saved links, bridge-only links, and socket outages.
+- [ ] Keep the dedupe guards in place.
+
+## Separate later project: retire the legacy bridge
+
+This is not required for the `3.52.0` or additive-delivery rollout.
+
+- [ ] Keep the dock dual-connected until its commands and private/targeted replies work fully through the server.
+- [ ] Audit every surface marked `legacyBridgeRequired: true`.
+- [ ] Migrate special tools such as hype, credits, events, poll, map, reactions, and tipjar individually.
+- [ ] Change transport capability flags one page at a time after focused testing.
+- [ ] Decide whether and how old saved URLs will ever be moved away from dual-listen mode.

actions.html

@@ -1760,7 +1760,7 @@ <h2>Session ID Required</h2>
                         if (payload.allow === false || payload.allow === 'false' || payload.allow === 'off' || payload.allow === 0 || payload.allow === '0') {
                             allowForce = false;
                         }
-                        TTS.speak(payload.text, allowForce);
+                        TTS.speak(payload.text, allowForce, { voice: payload.voice });
                         console.log("[TTS] Speaking:", payload.text, "(force:", allowForce + ")");
                     } else if (!payload.text) {
                         console.warn("[TTS] No text provided for TTS action");

actions/EventFlowEditor.js

@@ -1955,7 +1955,10 @@ class EventFlowEditor {
                 case 'fromSource': return `Source: ${node.config.source === '*' ? 'Any' : (node.config.source || 'Any')}`;
                 case 'fromChannelName': return `Channel: ${node.config.channelName || 'Any'}`;
                 case 'fromUser': return `User: ${node.config.username || 'Any'}`;
-                case 'userRole': return `Role: ${node.config.role || 'Any'}`;
+                case 'userRole': {
+                    const roleLabels = { tiktokTeamMember: 'TikTok Team Member' };
+                    return `Role: ${roleLabels[node.config.role] || node.config.role || 'Any'}`;
+                }
                 case 'hasDonation': return 'Has donation';
                 case 'channelPointRedemption': {
                     const rewardName = node.config.rewardName || '';
@@ -3176,11 +3179,21 @@ class EventFlowEditor {
 			case 'fromUser':
 				html += `<div class="property-group"><label class="property-label">Username</label><input type="text" class="property-input" id="prop-username" value="${node.config.username || ''}"></div>`;
 				break;
-			case 'userRole':
-				html += `<div class="property-group"><label class="property-label">User Role</label><select class="property-input" id="prop-role">
-						   ${['mod', 'vip', 'admin', 'subscriber', 'member', 'follower'].map(r => `<option value="${r}" ${node.config.role === r ? 'selected' : ''}>${r.charAt(0).toUpperCase() + r.slice(1)}</option>`).join('')}
-						 </select></div>`;
-				break;
+			case 'userRole':
+				const userRoles = [
+					{ value: 'mod', label: 'Moderator' },
+					{ value: 'vip', label: 'VIP' },
+					{ value: 'admin', label: 'Admin' },
+					{ value: 'subscriber', label: 'Subscriber' },
+					{ value: 'member', label: 'Member' },
+					{ value: 'follower', label: 'Follower' },
+					{ value: 'tiktokTeamMember', label: 'TikTok Team Member' }
+				];
+				html += `<div class="property-group"><label class="property-label">User Role</label><select class="property-input" id="prop-role">
+						   ${userRoles.map(role => `<option value="${role.value}" ${node.config.role === role.value ? 'selected' : ''}>${role.label}</option>`).join('')}
+						 </select></div>
+						 <div class="property-help">TikTok Team Member matches Fan Club/team levels and badges supplied with a TikTok message.</div>`;
+				break;
 			case 'hasDonation': // Trigger type
 				html += `<p class="property-help">Fires if the message includes donation information.</p>`;
 				break;
@@ -5209,14 +5222,20 @@ class EventFlowEditor {
 				break;
 
 			// TTS Actions
-			case 'ttsSpeak':
-				html += `
-					<div class="property-group">
-						<label class="property-label">Text to Speak</label>
-						<textarea class="property-input" id="prop-text" rows="3" placeholder="Enter text to speak...">${node.config.text || ''}</textarea>
-						<div class="property-help">The text that will be spoken aloud</div>
-					</div>
-					<div class="property-group">
+			case 'ttsSpeak':
+				html += `
+					<div class="property-group">
+						<label class="property-label">Text to Speak</label>
+						<textarea class="property-input" id="prop-text" rows="3" placeholder="Enter text to speak...">${node.config.text || ''}</textarea>
+						<div class="property-help">The text that will be spoken aloud</div>
+					</div>
+					<div class="property-group">
+						<label class="property-label">Voice Override (optional)</label>
+						<input type="text" class="property-input" id="prop-voice"
+							value="${this.escapeHtml(node.config.voice || '')}" placeholder="Use Flow Actions default voice">
+						<div class="property-help">Enter a voice name or ID supported by the active Flow Actions TTS provider. Leave blank to use its configured default.</div>
+					</div>
+					<div class="property-group">
 						<label class="property-label">
 							<input type="checkbox" class="property-input" id="prop-useMessageText"
 								${node.config.useMessageText ? 'checked' : ''}>

actions/EventFlowSystem.js

@@ -1084,6 +1084,37 @@ class EventFlowSystem {
 	hasChatLikeFields(message) {
 		return !!(message && (message.chatname || message.chatmessage || message.hasDonation || message.contentimg));
 	}
+
+	isTikTokTeamMember(message) {
+		if (!message || String(message.type || '').toLowerCase() !== 'tiktok') return false;
+
+		const meta = message.meta && typeof message.meta === 'object' && !Array.isArray(message.meta)
+			? message.meta
+			: {};
+		const levelCandidates = [
+			meta.memberLevel,
+			meta.teamMemberLevel,
+			meta.fanLevel,
+			message.memberLevel,
+			message.teamMemberLevel,
+			message.fanLevel
+		];
+		if (levelCandidates.some(level => Number(level) > 0)) return true;
+
+		const badges = Array.isArray(message.chatbadges)
+			? message.chatbadges
+			: (message.chatbadges ? [message.chatbadges] : []);
+		return badges.some(badge => {
+			if (typeof badge === 'string') {
+				return /(?:fans?_badge|grade_badge)/i.test(badge);
+			}
+			try {
+				return /(?:fans?_badge|grade_badge)/i.test(JSON.stringify(badge));
+			} catch (e) {
+				return false;
+			}
+		});
+	}
 
     async processMessage(message) {
 
@@ -1579,6 +1610,9 @@ class EventFlowSystem {
                 return match;
 
             case 'userRole':
+                if (config && config.role === 'tiktokTeamMember') {
+                    return this.isTikTokTeamMember(message);
+                }
                 match = message && config && message[config.role] === true; 
               ////console.log(`[EvaluateTrigger - userRole] Config Role: "${config.role}", Message Role Value: ${message[config.role]}, Match: ${match}`);
                 return match;
@@ -3538,6 +3572,7 @@ class EventFlowSystem {
                         overlayNinja: {
                             actionType: 'tts',
                             text: ttsText,
+                            voice: typeof config.voice === 'string' ? config.voice.trim() : '',
                             force: config.force || false
                         }
                     }, 'actions');

actions/event-flow-guide.html

@@ -490,6 +490,8 @@ <h3>Common Q &amp; A</h3>
                     <li><strong>Do I have to use AND for every pair of filters?</strong> No. Many nodes include multiple checks (for example, the basic Message Filter supports keyword + role). Use AND only for advanced combinations or when merging signals from different nodes.</li>
                     <li><strong>How do true/false values reach the NOT node?</strong> Any node with a green output emits <code>true</code> by default. When a condition fails, it emits <code>false</code>. Connect that wire into NOT to invert the result.</li>
                     <li><strong>Can a node emit a payload even if it returns false?</strong> Yes. The payload still travels through the false output; it is up to you to decide where that branch should go.</li>
+					<li><strong>How do I match TikTok Team members?</strong> Choose <em>TikTok Team Member</em> in the User Role node. It recognizes TikTok Fan Club/team levels and badges on the incoming message and does not depend on Main Chat Overlay settings.</li>
+					<li><strong>Can each Speak Text node use a different voice?</strong> Yes. Enter a provider-supported voice name or ID in <em>Voice Override</em>, or leave it blank to use the Flow Actions TTS default.</li>
                 </ul>
             </section>
 

docs/agents/09-api-and-integrations/event-flow-editor.md

@@ -130,6 +130,8 @@ User and source triggers:
 - `userRole`
 - `channelPointRedemption`
 
+`userRole` supports `tiktokTeamMember`, which matches positive TikTok team/fan levels or `fans_badge` / `grade_badge` data on an incoming TikTok message. This check is independent of dock-overlay URL settings.
+
 Timing and random triggers:
 
 - `randomChance`
@@ -214,6 +216,8 @@ TTS actions:
 - `ttsClear`
 - `ttsVolume`
 
+`ttsSpeak.config.voice` is an optional per-utterance voice name or provider voice ID. Empty or missing values use the configured Flow Actions TTS voice. The override is preserved while premium-provider speech waits in the queue and does not mutate the configured default.
+
 MIDI actions:
 
 - `midiSendNote`

docs/event-reference.html

@@ -112,6 +112,7 @@ <h3>Platforms and Sources</h3>
                                 <li><a href="#streamplace">Streamplace</a></li>
                                 <li><a href="#worldswave">WorldsWave</a></li>
                                 <li><a href="#flextv">FLEX TV</a></li>
+                                <li><a href="#sealteamsloth">Seal Team Sloth</a></li>
                                 <li><a href="#meetme-dom">MeetMe</a></li>
                                 <li><a href="#velora">Velora</a></li>
                                 <li><a href="#parti">Parti</a></li>
@@ -1540,6 +1541,36 @@ <h3>FLEX TV</h3>
                     </table>
                 </article>
 
+                <article class="platform-card" id="sealteamsloth">
+                    <h3>Seal Team Sloth</h3>
+                    <p class="source-note">Implementation: <code>sources/sealteamsloth.js</code></p>
+                    <ul class="requirements">
+                        <li>Reads the rendered pop-out chat on <code>https://sealteamsloth.com/popout-chat/*</code> pages.</li>
+                        <li>Viewer counts require <strong>Show viewer count</strong> or hype mode.</li>
+                    </ul>
+                    <table class="event-table">
+                        <thead>
+                            <tr>
+                                <th>Event</th>
+                                <th>When it Fires</th>
+                                <th>Payload Notes</th>
+                            </tr>
+                        </thead>
+                        <tbody>
+                            <tr>
+                                <td><code>message</code></td>
+                                <td>A new rendered Seal Team Sloth chat row appears.</td>
+                                <td>Standard chat payload with <code>type: "sealteamsloth"</code>, sender name, avatar, and message content.</td>
+                            </tr>
+                            <tr>
+                                <td class="status-event"><code>viewer_update</code></td>
+                                <td>The visible live viewer total changes while viewer-count capture or hype mode is enabled.</td>
+                                <td><code>meta</code> is the integer viewer count; compact values such as <code>1.2K</code> are normalized.</td>
+                            </tr>
+                        </tbody>
+                    </table>
+                </article>
+
                 <article class="platform-card" id="meetme-dom">
                     <h3>MeetMe - DOM and WebSocket Capture</h3>
                     <p class="source-note">Implementation: <code>sources/meetme.js</code></p>

tipjar.html

@@ -2494,8 +2494,8 @@ <h3 style="color: white; margin-bottom: 15px; text-align: center;">🏆 Top Dono
         if (!useServerOnlyTransport()) {
             const iframe = document.createElement("iframe");
             const filename = "tipjar";
-            iframe.src = "https://vdo.socialstream.ninja/?ln&salt=vdo.ninja&notmobile&notmobile&password=" +
-                (password || "false") + "&solo&view=" + roomID + "&novideo&noaudio&label=" +
+            iframe.src = "https://vdo.socialstream.ninja/?ln&salt=vdo.ninja&notmobile&notmobile&password=" +
+                encodeURIComponent(password || "false") + "&solo&view=" + roomID + "&novideo&noaudio&label=" +
                 filename + "&cleanoutput&room=" + roomID;
             iframe.style.width = "0px";
             iframe.style.height = "0px";