@lumiastream/lumia-types 3.8.1 → 3.8.3

package/dist/custom-code/custom-actions.md

@@ -20,16 +20,53 @@ Let's get started:
 
 #### Before we begin, let's dissect this.
 
-`base`: will be the base of actions that can be used with Custom Code. The different bases are:
-`delay, lumia, overlay, api, websocket, commandRunner, inputEvent, obs, slobs, twitch, twitter, streamerbot, midi, osc, artnet, mqtt, serial, broadlink, spotify, vlc, voicemod`
+`base`: will be the base of actions that can be used with Custom Code. There are two groups of bases.
 
-`type`: Every base has different action types. For instance, the base `lumia` has: `chatbot, tts, setStreamMode, toggleStreamMode` and much more.
-To find the list of types that each base has below. Check in the side bar to quickly get to the base you're interested in.
+**System bases** (built into Lumia):
+`delay, lumia, overlay, api, commandRunner, inputEvents`
+
+> Note: `lumia` and `overlay` also accept the aliases `lumiaActions` and `overlayActions`, and the input base is `inputEvents` (plural).
+
+**Integration bases** — every connected integration is also a valid base. These include (and more are added over time):
+`twitch, youtube, facebook, tiktok, kick, discord, obs, slobs, meld, spotify, youtubemusic, nowplaying, vlc, voicemod, streamerbot, vtubestudio, midi, osc, artnet, mqtt, serial, websocket, broadlink, hue, lifx, nanoleaf, govee, wled, wiz, tplink, tuya, yeelight, elgato, streamdeck, touchportal, loupedeck, homeassistant, switchbot` plus any installed plugin (use the plugin's id as the base).
+
+`type`: Every base has different action types. For instance, the base `lumia` has `chatbot, tts, setStreamMode, toggleStreamMode` and many more. The full type lists for the system bases are below; integration and plugin types vary per integration — the easiest way to discover the exact `base`, `type`, and `value` for an integration action is to configure that action once in Lumia's normal Action editor.
 
 `value`: can sometimes be an object and sometimes a string, it all depends on the `base` and `type`
 
 `variables`: allows you to send in different variables for each action. But do note that the variables that are already on the command/alert will also be spread on to this variables object. Variables are not required
 
-There are more fields that are sometimes used in actions. We will try to list out as many common examples down below along with the schema for them
+There are more fields that are sometimes used in actions. `delay` (a number in milliseconds) can be added to any action to wait before running it.
+
+### Passing an array of actions
+
+```js
+async function() {
+    // Runs the TTS, then sends a chatbot message
+    await actions([
+        { base: "lumia", type: "tts", value: { message: "Hello {{username}}" } },
+        { base: "lumia", type: "chatbot", value: { message: "Welcome {{username}}" } }
+    ]);
+    done();
+}
+```
+
+### System base type reference
+
+These are the built-in `type` values for each system base.
+
+**`base: "lumia"`** — `callCommand, callRandomCommand, chatbot, tts, setStreamMode, toggleStreamMode, setFuzeAudioSensitivity, playAudio, writeToFile, setConnection, updateVariable, updateCounter, appendToVariable, unappendFromVariable, saveLocal, addToUserlevel, removeFromUserlevel, addToRestrictionsList, removeFromRestrictionsList, setFolder, setAlert, setAlertVariation, setCommand, setChatbotCommand, setTwitchPointsCommand, setTwitchExtensionCommand, setKickPointsCommand, setChatMatchCommand, setTwitchPointValue, setLoyaltyPointValue, setUserLoyaltyPoint, setTwitchExtensionBitsValue, setAutomation, setVoicecommands, sendToDiscordWebhook, sendToDiscordWithMediaWebhook, sendToWebhook, sendToPrinter, raffleEntry, raffleRemoveEntry, raffleGetWinner, raffleStart, raffleStop, raffleEnd, viewerQueueEntry, viewerQueueLeave, tournamentEntry, tournamentRemoveEntry, tournamentUpdatePoints, tournamentStart, tournamentEnd, viewerQueuePlayPause, viewerQueueEndQueue, viewerQueuePickPlayer, backToDefault, replayLastEventListEvent, runLastQueueItem, resumeQueue, pauseQueue, removeCurrentQueueItem, clearQueue, clearCooldowns, resetSession, cleanAll, refreshSettings, addSongRequest, skipSongRequest, clearSongRequestQueue, delay`
+
+**`base: "overlay"`** — `alertTrigger, alertEvent, setOverlayVisibility, setLayerVisibility, setLayerPosition, setLayerSize, setTextContent, setImageContent, setVideoContent, setAudioContent, setLayerVolume, playPauseMedia, setContent, sendShoutout, sendCustomOverlayContent, sendGameTrigger, sendGameUpdate, takeScreenshot, spinwheelReset, spinwheelAddItem, spinwheelRemoveItem, sendHfx, hudOverlayChange, hudToggle, hudVolumeSet, hudOpacitySet, timerIncrement, pollTrigger, pollStart, pollResetVotes, pollSetTimer, pollAddItem, pollRemoveItem, delay`
+
+**`base: "api"`** — `get, put, post, patch, delete, delay`
+
+**`base: "commandRunner"`** — `app/file, shell command, delay`
+
+**`base: "inputEvents"`** — `keyboard, mouse, delay`
+
+**`base: "delay"`** — no `type`; pass the millisecond delay directly as the value, e.g. `{ base: "delay", value: 1000 }`.
+
+> Tip: most of the `lumia` and `overlay` actions already have dedicated helper functions (`tts`, `chatbot`, `overlaySetTextContent`, etc.) in `helper-functions.md`. Reach for `actions()` mainly when you need an integration action that does not have a helper yet.
 
-#### More documentation coming soon
+This documentation can get extremely broad for every integration, so if you get stuck please visit our [**Discord**](https://discord.gg/R8rCaKb) to ask us any questions.

package/dist/custom-code/examples/create-counter.md

@@ -10,15 +10,12 @@ e.g. the code below will trigger a command named **'money-12'** when the **count
 ```js
 async function() {
 
-    // You can get your variable's value that you just set here
-    let redeemCount = await getVariable('redeemCount');
-
-    if (!redeemCount) {
-        // If variable does not exist it will create it
-        redeemCount = await setVariable({ name: 'redeemCount', value: 10 });
-    }
+    // Variables come back as strings, so wrap with Number(). Defaults to 0 the first time the variable doesn't exist yet
+    let redeemCount = Number(await getVariable('redeemCount')) || 0;
 
     redeemCount++;
+
+    // setVariable creates the variable if it doesn't exist, or updates it
     await setVariable({ name: 'redeemCount', value: redeemCount });
 
     if (redeemCount === 12) {

package/dist/custom-code/examples/random-twitch-clip.md

@@ -9,6 +9,9 @@ You can call requests from integrations that we support that have an access toke
 
 ```js
 async function() {
+	// Declared outside the try so it's still in scope when we call done()
+	let randomClip;
+
 	try {
 		const twitchToken = await getToken('twitch');
 		const twitchClientId = await getClientId('twitch');
@@ -20,14 +23,20 @@ async function() {
 				'Client-ID': twitchClientId
 			}
 		});
-		const clips = (await clipsRes.json())?.data;
-		const randomClip = clips[Math.floor(Math.random() * clips.length)];
-		chatbot({ message: `${randomClip.title}: ${randomClip.url}` });
+		const clips = (await clipsRes.json())?.data ?? [];
+		if (clips.length) {
+			randomClip = clips[Math.floor(Math.random() * clips.length)];
+			chatbot({ message: `${randomClip.title}: ${randomClip.url}` });
+		}
 	} catch (err) {
 		showToast({ message: 'error: ' + err.message });
 	}
 
-	done({ variables: { user_clip_title: randomClip.title, user_clip: randomClip.url } });
+	if (randomClip) {
+		done({ variables: { user_clip_title: randomClip.title, user_clip: randomClip.url } });
+	} else {
+		done();
+	}
 }
 ```
 

package/dist/custom-code/examples/track-subscribers.md

@@ -11,7 +11,7 @@ This can be very useful if other apps are reading and writing to a text file. An
 ```js
 async function() {
 	// You have the ability to overwrite the whole file by setting append to false, or appending to the file in case you would like to keep a log of things
-	await writeFile({ path: 'C:	\\Users\\Lumia\\Desktop\\lastSubscriber.txt', message: '{{username}}\n', append: true });
+	await writeFile({ path: 'C:\\Users\\Lumia\\Desktop\\lastSubscriber.txt', message: '{{username}}\n', append: true });
 
 	// You can get your variable's value that you just set here
 	const lastSubscribers = await readFile('C:\\Users\\Lumia\\Desktop\\lastSubscriber.txt');

package/dist/custom-code/gpt-instructions.md

@@ -1,29 +1,50 @@
 # Lumia Stream Custom Code GPT Instructions
 
-Use this with the Custom Code docs:
-- `what-is-custom-javascript.md`
-- `important-notes.md`
-- `helper-functions.md`
-- `custom-actions.md`
-- `examples/*.md`
-
-## Required Output Rules
-
-1. Always generate JavaScript (not TypeScript).
-2. Prefer returning a full Lumia Custom Code wrapper:
-
-```js
-async function() {
-  // logic
-
-  // Make sure you call done() to avoid memory leaks
-  done();
-}
-```
-
-3. Always call `done()` exactly once before finishing the function, unless the user explicitly asks for a partial snippet.
-4. Do not output markdown fences or prose when the caller expects code-only output.
-5. Use helper functions documented in `helper-functions.md` instead of inventing undocumented APIs.
-6. Keep examples compatible with Lumia variable syntax (e.g. `{{username}}`).
-7. When accessing numeric variables, parse values safely before math/comparisons.
-8. If a capability is not documented, state that clearly and provide a safe alternative.
+You generate **Lumia Stream Custom Code**: JavaScript snippets that a streamer pastes into the "Custom Javascript" tab of a Command or Alert. Use this together with the Custom Code docs:
+
+- `what-is-custom-javascript.md` — what the feature is
+- `important-notes.md` — variables, runtime environment, gotchas
+- `helper-functions.md` — every available helper function (the API surface)
+- `custom-actions.md` — the `actions([...])` escape hatch and base/type lists
+- `examples/*.md` — worked examples
+
+## Runtime model (read this first)
+
+- Code runs in a sandboxed browser **Web Worker**, not Node.js. `fetch`, `Promise`, `async/await`, `JSON`, `Math`, `Date`, `setTimeout` are available. There is **no** `require`, `import`, `fs`, `process`, or `Buffer`.
+- Helper functions are injected as **globals** — never import or redefine them. Most return a Promise, so `await` them.
+- Lumia **rejects any code that does not contain a `done(` call.** Always call `done()` exactly once, as the last thing the code does.
+- `{{variable}}` tokens are string-replaced **before** the code runs. They are not wrapped in quotes automatically, so wrap them yourself when you need a string: `tts({ message: "{{username}}" })`. When you need the raw value (object/number), read it instead with `await getVariable('name')`.
+
+## Required output rules
+
+1. Always generate **JavaScript** (not TypeScript). No type annotations.
+2. Wrap the logic in the standard Lumia Custom Code shell, unless the user explicitly asks for a partial snippet:
+
+   ```js
+   async function() {
+     // logic
+
+     // Always call done() to close the worker and avoid memory leaks
+     done();
+   }
+   ```
+
+3. Call `done()` **exactly once** before finishing. Use `done({ shouldStop: true })` to also stop the rest of the command, `done({ actionsToStop: ['tts','chatbot'] })` to stop specific parts, and `done({ variables: { key: 'value' } })` to pass variables to later actions.
+4. Only use helpers documented in `helper-functions.md`. Do **not** invent undocumented APIs. The complete set of globals is:
+
+   `done, log, addLog, showToast, delay, getVariable, getAllVariables, setVariable, deleteVariable, getStore, getStoreItem, removeStoreItem, setStore, resetStore, getLights, sendColor, hexToRgb, getCommands, getAllCommands, getApiOptions, getToken, getClientId, callAlert, callCommand, callChatbotCommand, callTwitchPoint, callTwitchExtension, callKickPoint, readFile, writeFile, tts, chatbot, playAudio, playSound, sendRawObsJson, execShellCommand, actions, overlayAlertTrigger, overlaySetVisibility, overlaySetLayerVisibility, overlaySetLayerPosition, overlaySetLayerSize, overlaySetTextContent, overlaySetImageContent, overlaySetVideoContent, overlaySetAudioContent, overlaySetVolume, overlayPlayPauseMedia, overlaySendHfx, overlayTimer, overlayShoutout, overlaySendCustomContent`
+
+   Plus standard browser globals including `fetch` and `console.log`. For anything an integration supports that has no dedicated helper (Spotify, OBS raw, Streamer.bot, etc.), use `actions([...])` as documented in `custom-actions.md`.
+5. Do not output markdown fences or prose when the caller expects code-only output.
+6. Keep `{{...}}` variable tokens intact and unescaped (write `{{username}}`, never `\{\{username\}\}`).
+7. When using numeric variables, parse them safely before math or comparisons: `const n = Number(await getVariable('count')) || 0;`. `getVariable` returns strings.
+8. For `callAlert`, the `name` must be a valid alert key from the list in `helper-functions.md` (e.g. `twitch-subscriber`, `kick-follower`, `kofi-donation`). Do not guess keys that aren't on that list.
+9. If a capability is not documented, say so clearly and offer a documented alternative rather than fabricating an API.
+
+## Quality checklist before returning code
+
+- Wrapped in `async function() { ... }` and calls `done()` once.
+- Every helper that returns a Promise is `await`ed.
+- Any variable referenced in `done()`/later code is declared in an outer scope (not trapped inside a `try` block).
+- API calls are wrapped in `try/catch` and still reach `done()` on failure.
+- Numeric variables parsed with `Number(...)`; string variables quoted when interpolated as `{{token}}`.

package/dist/custom-code/helper-functions.md

@@ -13,7 +13,7 @@ If you would like to modify/add variables that other actions could use, you can
 
 You can also choose to only stop some actions rather than stopping the whole command by using actionsToStop.
 The different actionsToStop keys relate to the action. The keys are:
-`devices, tts, chatbot, hfx, lumia, overlay, voicemod, streamerbot, obs, slobs, midi, osc, mqtt, serial, broadlink, websocket, twitter, twitch, spotify, vlc, artnet, api, commandRunner, inputEvent`
+`devices, tts, chatbot, hfx, lumia, overlay, api, commandRunner, inputEvent, actions, voicemod, streamerbot, obs, slobs, midi, osc, mqtt, serial, broadlink, websocket, twitter, twitch, spotify, vlc, artnet`
 
 ```js
 // Basic done
@@ -161,6 +161,17 @@ async function() {
 }
 ```
 
+### Remove Persisted Store Item
+
+`removeStoreItem(name: string)`: Removes a single item from the custom code store by its name. The rest of the store is left untouched
+
+```js
+async function() {
+    await removeStoreItem('users');
+    done();
+}
+```
+
 ### Set Persisted Store Item
 
 `setStore({ name: string; value: any })`: Sets an item in the store. You can use any data type as your value
@@ -219,6 +230,18 @@ async function() {
 }
 ```
 
+### Hex To RGB
+
+`hexToRgb(value: string)`: Helper that converts a hex color string into an `{ r, g, b }` object. Useful when an integration expects an rgb object instead of a hex string
+
+```js
+async function() {
+    const rgb = await hexToRgb('#FF4076');
+    // rgb is { r: 255, g: 64, b: 118 }
+    done();
+}
+```
+
 ### Get API Options
 
 `getApiOptions()`: Contains information like commands, types, connections, and more
@@ -229,14 +252,81 @@ async function() {
 }
 ```
 
+### Get Commands
+
+`getCommands({ formatted?: boolean; onlyOn?: boolean; onlyUser?: boolean })`: Returns the list of chat command names. Pass `onlyOn: true` to only include commands that are enabled and shown in the commands list, `onlyUser: true` to only include commands the current user has access to (based on their user levels), and `formatted: true` to get a single comma separated string instead of an array
+
+```js
+async function() {
+    // Array of command names the chatter is allowed to use, only the ones that are turned on
+    const commands = await getCommands({ onlyOn: true, onlyUser: true });
+    // Or get a ready to print string for a !commands message
+    const list = await getCommands({ formatted: true, onlyOn: true });
+    chatbot({ message: `Commands: ${list}` });
+    done();
+}
+```
+
+### Get All Commands
+
+`getAllCommands({ onlyOn?: boolean })`: Returns an object containing the names of every command type: `commands`, `chatbotCommands`, `twitchPointsCommands`, `twitchExtensionsCommands`, `kickPointsCommands`, `chatMatch`, and `folders`. Pass `onlyOn: true` to only include enabled entries
+
+```js
+async function() {
+    const all = await getAllCommands({ onlyOn: true });
+    log(all.chatbotCommands);
+    done();
+}
+```
+
 ### Call Alert
 
 `callAlert({ name: string; variation?: string; variableValues?: {[key: string]: string|number } })`: Call an alert based on your conditions. You can also call a variation given it's name. When calling an alert/command from custom code the variableValues will be inherited from the parent, but you can also override variable values by passing it in to the call function.
 
-The valid alert keys are:
+The `name` must be one of the valid alert keys (the `LumiaAlertValues` list). This is the full current list, grouped by platform:
 
 ```
-lumia-redemption, twitch-streamLive, twitch-streamOffline, twitch-follower, twitch-subscriber, twitch-giftSubscription, twitch-host, twitch-raid, twitch-bits, twitch-redemption, twitch-hypetrainStarted, twitch-hypetrainProgressed, twitch-hypetrainLevelProgressed, twitch-hypetrainEnded, twitch-pollStarted, twitch-pollProgressed, twitch-pollEnded, twitch-predictionStarted, twitch-predictionProgressed, twitch-predictionLocked, twitch-predictionEnded, twitch-goalStarted, twitch-goalProgressed, twitch-goalEnded, twitch-categoryChanged, twitch-clip, youtube-member, youtube-subscriber, youtube-superchat, youtube-supersticker, facebook-follower, facebook-reaction, facebook-star, facebook-support, facebook-subscriptionGift, facebook-share, facebook-fan, tiktok-follower, tiktok-like, tiktok-gift, tiktok-share, tiktok-streamEnd, streamlabs-donation, streamlabs-charity, streamlabs-merch, streamlabs-redemption, streamlabs-primegift, streamelements-donation,  extralife-donation, donordrive-donation, tiltify-campaignDonation, tipeeestream-donation, treatstream-treat, patreon-pledge, obs-switchProfile, obs-switchScene, obs-sceneItemVisibility, obs-sceneItemHidden, obs-switchTransition, obs-transitionBegin, obs-transitionEnd, obs-streamStarting, obs-streamStopping, obs-recordingStarting, obs-recordingStopping, slobs-switchSceneCollection, slobs-switchScene, slobs-sceneItemVisibility, slobs-sceneItemHidden, spotify-switchSong, spotify-songPlayed, spotify-songPaused, vlc-switchSong, vlc-songPlayed, vlc-songPaused, pulse-heartrate, pulse-calories, twitter-follower, twitter-like, twitter-retweet, woocommerce-order, kofi-donation, kofi-subscription, kofi-commission, kofi-shopOrder, streamerbot-action
+// Lumia Stream
+lumiastream-donation, lumiastream-lumiaOpened, lumiastream-lumiaClosed, lumiastream-streammodeOn, lumiastream-streammodeOff, lumiastream-raffleStart, lumiastream-raffleStop, lumiastream-raffleWinner, lumiastream-tournamentStart, lumiastream-tournamentEnd, lumiastream-tournamentWinner, lumiastream-spinwheelWinner, lumiastream-pollStarted, lumiastream-pollProgressed, lumiastream-pollEnded, lumiastream-viewerqueueStarted, lumiastream-viewerqueueEnded, lumiastream-viewerAchievement, lumiastream-variableChanged, lumiastream-rouletteWinner, lumiastream-slotsWinner
+
+// Twitch
+twitch-extension, twitch-points, twitch-streamLive, twitch-streamOffline, twitch-firstChatter, twitch-entrance, twitch-follower, twitch-sessionFollowers, twitch-subscriber, twitch-sessionSubs, twitch-giftSubscription, twitch-sessionGiftSubscriptions, twitch-raid, twitch-raidOut, twitch-bits, twitch-bitsCombo, twitch-sessionBits, twitch-redemption, twitch-hypetrainStarted, twitch-hypetrainProgressed, twitch-hypetrainLevelProgressed, twitch-hypetrainEnded, twitch-pollStarted, twitch-pollProgressed, twitch-pollEnded, twitch-predictionStarted, twitch-predictionProgressed, twitch-predictionLocked, twitch-predictionEnded, twitch-goalStarted, twitch-goalProgressed, twitch-goalEnded, twitch-charityDonation, twitch-charityCampaignStarted, twitch-charityCampaignProgressed, twitch-charityCampaignStopped, twitch-categoryChanged, twitch-clip, twitch-channelJoin, twitch-channelLeave, twitch-banned, twitch-timeout, twitch-timeoutOver, twitch-shoutoutReceive, twitch-warned, twitch-suspiciousUserMessage, twitch-suspiciousUserUpdated, twitch-shieldModeStarted, twitch-shieldModeEnded, twitch-adStarted, twitch-adStopped, twitch-watchStreak, twitch-powerups
+
+// YouTube
+youtube-streamLive, youtube-streamOffline, youtube-firstChatter, youtube-entrance, youtube-subscriber, youtube-sessionSubs, youtube-member, youtube-sessionMembers, youtube-giftMembers, youtube-sessionGiftMembers, youtube-superchat, youtube-sessionSuperchats, youtube-supersticker, youtube-sessionSuperstickers, youtube-gifts, youtube-sessionGifts, youtube-like, youtube-viewers
+
+// Facebook
+facebook-streamLive, facebook-streamOffline, facebook-firstChatter, facebook-entrance, facebook-follower, facebook-reaction, facebook-star, facebook-support, facebook-subscriptionGift, facebook-share, facebook-fan
+
+// TikTok
+tiktok-firstChatter, tiktok-entrance, tiktok-follower, tiktok-like, tiktok-totalLikes, tiktok-gift, tiktok-superFan, tiktok-superFanBox, tiktok-treasureChest, tiktok-question, tiktok-poll, tiktok-shopPurchase, tiktok-pinMessage, tiktok-battleStart, tiktok-battleProgress, tiktok-battleEnd, tiktok-share, tiktok-streamEnd, tiktok-newVideo
+
+// Kick
+kick-points, kick-firstChatter, kick-entrance, kick-follower, kick-sessionFollowers, kick-subscriber, kick-sessionSubs, kick-subscriptionGift, kick-sessionGiftSubscriptions, kick-kicks, kick-sessionKicks, kick-host, kick-banned, kick-unbanned
+
+// Discord
+discord-firstChatter, discord-entrance
+
+// Donations & monetization
+streamlabs-donation, streamlabs-charity, streamlabs-merch, streamlabs-redemption, streamlabs-primegift, streamelements-donation, extralife-donation, donordrive-donation, tiltify-campaignDonation, throne-giftPurchase, throne-contributionPurchase, throne-giftCrowdfunded, tipeeestream-donation, treatstream-treat, patreon-campaignPledge, kofi-donation, kofi-subscription, kofi-commission, kofi-shopOrder, fourthwall-shopOrder, fourthwall-donation, fourthwall-subscription, fourthwall-subscriptionChanged, fourthwall-subscriptionExpired, fourthwall-giftpurchase, fourthwall-giveawayStarted, fourthwall-giveawayEnded, fourthwall-thankyouSent, fourthwall-newsletterSubscribed, woocommerce-order
+
+// OBS Studio
+obs-switchProfile, obs-switchScene, obs-sceneItemVisibility, obs-sceneItemHidden, obs-switchTransition, obs-transitionBegin, obs-transitionEnd, obs-streamStarting, obs-streamStopping, obs-recordingStarting, obs-recordingStopping, obs-mediaInputPlaybackStarted, obs-mediaInputPlaybackEnded, obs-virtualcamStateChanged, obs-screenshotSaved, obs-replayBufferSaved, obs-verticalBacktrackSaved, obs-vendorEvent
+
+// Streamlabs Desktop (SLOBS)
+slobs-switchSceneCollection, slobs-switchScene, slobs-sceneItemVisibility, slobs-sceneItemHidden
+
+// Meld Studio
+meld-streamStarting, meld-streamStopping, meld-recordingStarting, meld-recordingStopping, meld-switchScene, meld-switchVerticalScene
+
+// Music players
+spotify-switchSong, spotify-songPlayed, spotify-songPaused, youtubemusic-switchSong, youtubemusic-songPlayed, youtubemusic-songPaused, nowplaying-switchSong, nowplaying-songPlayed, nowplaying-songPaused, vlc-switchSong, vlc-songPlayed, vlc-songPaused
+
+// VTube Studio
+vtubestudio-hotkeyTriggered, vtubestudio-modelLoaded, vtubestudio-animationStart, vtubestudio-animationEnd, vtubestudio-itemAdded, vtubestudio-itemRemoved, vtubestudio-backgroundChanged
+
+// Other
+pulse-heartrate, pulse-calories, twitter-follower, twitter-like, twitter-retweet, streamerbot-action, crowdcontrol-effect
 ```
 
 ```js
@@ -257,6 +347,17 @@ async function() {
 }
 ```
 
+### Call Chatbot Command
+
+`callChatbotCommand({ name: string; variableValues?: {[key: string]: string|number } })`: Call a chatbot command based on your conditions. When calling an alert/command from custom code the variableValues will be inherited from the parent, but you can also override variable values by passing it in to the call function.
+
+```js
+async function() {
+	// This will call chatbot command called 'welcome' and change the variable named "message" to the value "you are awesome"
+    callChatbotCommand({ name: 'welcome', variableValues: {'message': 'you are awesome' } })
+}
+```
+
 ### Call Twitch Point Command
 
 `callTwitchPoint({ name: string; variableValues?: {[key: string]: string|number } })`: Call a twitch point command based on your conditions. When calling an alert/command from custom code the variableValues will be inherited from the parent, but you can also override variable values by passing it in to the call function.
@@ -279,6 +380,17 @@ async function() {
 }
 ```
 
+### Call Kick Point Command
+
+`callKickPoint({ name: string; variableValues?: {[key: string]: string|number } })`: Call a kick point command based on your conditions. When calling an alert/command from custom code the variableValues will be inherited from the parent, but you can also override variable values by passing it in to the call function.
+
+```js
+async function() {
+	// This will call Kick Point called 'point' and change the variable named "message" to the value "you are awesome"
+    callKickPoint({ name: 'point', variableValues: {'message': "you are awesome" } });
+}
+```
+
 ### Read File
 
 `readFile(path: string)`: Read from a file on your local computer to get the contents of it to be displayed in your code. This is useful for other Apps that write and read to files so you can combine the usage of them in Lumia. To keep things consistent, try to use an absolute file path
@@ -297,7 +409,7 @@ async function() {
 ```js
 async function() {
 	// This will create a new file in the 'C:\Documents\Lumiastream\' named helper.txt and add the text "text inside this file" inside that file
-	await writeFile({ path: 'C:\\Documents\\Lumiastream\\helper.txt', value: 'text inside this file', append: true });
+	await writeFile({ path: 'C:\\Documents\\Lumiastream\\helper.txt', message: 'text inside this file', append: true });
 }
 ```
 
@@ -328,7 +440,7 @@ async function() {
 
 ### Play Audio
 
-`playAudio({ path: string | string[]; volume?: number; waitForAudioToStop?: boolean })`: You can play an audio file from either a URL or from a local path on your computer inside of your code. You can even wait for the audio to stop playing before the code continues by setting an await before while also setting waitForAudioToStop to true. You can also allow Lumia Stream to randomly play an audio file from a selection by passing an array of strings to path
+`playAudio({ path: string | string[]; volume?: number; waitForAudioToStop?: boolean })`: You can play an audio file from either a URL or from a local path on your computer inside of your code. You can even wait for the audio to stop playing before the code continues by setting an await before while also setting waitForAudioToStop to true. You can also allow Lumia Stream to randomly play an audio file from a selection by passing an array of strings to path. `playSound` is an alias of `playAudio` and takes the exact same parameters
 
 ```js
 async function() {
@@ -434,6 +546,16 @@ async function() {
 }
 ```
 
+### Overlay Set Layer Size (Width and Height)
+
+`overlaySetLayerSize({ layer: string, content: string })`: You can set the width and height of an overlay layer using this function. `content` is a string with the width and height separated by a comma. Like position, the overlay can interpolate so the resize can animate smoothly.
+
+```js
+async function() {
+    overlaySetLayerSize({ layer: "My layer", content: "640,360" });
+}
+```
+
 ### Overlay Set Text Content
 
 `overlaySetTextContent({ layer: string, content: string })`: You can set the text content of a text layer using this function. `content` is just a string that will correspond to the text that you want to set it to.
@@ -446,7 +568,7 @@ async function() {
 
 ### Overlay Set Image Content
 
-`overlaySetImageContent({ layer: string, content: string })`: You can set the image content of an image layer using this function. `content` is just a string that will correspond to the image name or url that you want to set it to. If you use a name it will try to find the name of an asset that you have in your overlay library. So if you have an asset named `lumia_logo.gif` you can set the content to the exact name with or without the file extension. This can be useful to allow chat to change the media using a \{\{message\}\} variable. After the content is changed it will automatically make the layer visibile and start playing
+`overlaySetImageContent({ layer: string, content: string })`: You can set the image content of an image layer using this function. `content` is just a string that will correspond to the image name or url that you want to set it to. If you use a name it will try to find the name of an asset that you have in your overlay library. So if you have an asset named `lumia_logo.gif` you can set the content to the exact name with or without the file extension. This can be useful to allow chat to change the media using a `{{message}}` variable. After the content is changed it will automatically make the layer visibile and start playing
 
 ```js
 async function() {
@@ -460,7 +582,7 @@ async function() {
 
 ### Overlay Set Video Content
 
-`overlaySetVideoContent({ layer: string, content: string })`: You can set the video content of an video layer using this function. `content` is just a string that will correspond to the video name or url that you want to set it to. If you use a name it will try to find the name of an asset that you have in your overlay library. So if you have an asset named `lumia_video.webm` you can set the content to the exact name with or without the file extension. This can be useful to allow chat to change the media using a \{\{message\}\} variable. After the content is changed it will automatically make the layer visibile and start playing
+`overlaySetVideoContent({ layer: string, content: string })`: You can set the video content of an video layer using this function. `content` is just a string that will correspond to the video name or url that you want to set it to. If you use a name it will try to find the name of an asset that you have in your overlay library. So if you have an asset named `lumia_video.webm` you can set the content to the exact name with or without the file extension. This can be useful to allow chat to change the media using a `{{message}}` variable. After the content is changed it will automatically make the layer visibile and start playing
 
 ```js
 async function() {
@@ -474,7 +596,7 @@ async function() {
 
 ### Overlay Set Audio Content
 
-`overlaySetAudioContent({ layer: string, content: string })`: You can set the audio content of an audio layer using this function. `content` is just a string that will correspond to the audio name or url that you want to set it to. If you use a name it will try to find the name of an asset that you have in your overlay library. So if you have an asset named `lumia_land.mp3` you can set the content to the exact name with or without the file extension. This can be useful to allow chat to change the media using a \{\{message\}\} variable. After the content is changed it will automatically make the layer visibile and start playing
+`overlaySetAudioContent({ layer: string, content: string })`: You can set the audio content of an audio layer using this function. `content` is just a string that will correspond to the audio name or url that you want to set it to. If you use a name it will try to find the name of an asset that you have in your overlay library. So if you have an asset named `lumia_land.mp3` you can set the content to the exact name with or without the file extension. This can be useful to allow chat to change the media using a `{{message}}` variable. After the content is changed it will automatically make the layer visibile and start playing
 
 ```js
 async function() {
@@ -529,7 +651,7 @@ async function() {
 
 ### Overlay Shoutout
 
-`overlayShoutout({ layer: string, clipType: "clipFromTarget" | "clipFromSender" | "clipFromStreamer", clipRandom: boolean, clipLimit: number, clipMaxTime: string })`: You can send a shoutout directly to a shoutout layer using this function. `clipType` has three types. `clipFromTarget` will take a clip from the user who was tagged in the \{\{message\}\} variable. So you can use @lumiastream in the message and it will take a clip from that channel. `clipFromSender` will take a clip from the person who triggered the command. This normally corresponds to the \{\{user\}\} variable. `clipFromStreamer` will take a clip from your channel and send it over. You can decide to take a random clip by setting `clipRandom` to true. Or if you would like to take the first clip that matched the `clipMaxTime` given in milliseconds then you can set `clipRandom` to false. `clipLimit` will determing how many of the newest clips should be brought in to determine which clip should be selected. After a clip is selected it will start running immediately
+`overlayShoutout({ layer: string, clipType: "clipFromTarget" | "clipFromSender" | "clipFromStreamer", clipRandom: boolean, clipLimit: number, clipMaxTime: string })`: You can send a shoutout directly to a shoutout layer using this function. `clipType` has three types. `clipFromTarget` will take a clip from the user who was tagged in the `{{message}}` variable. So you can use @lumiastream in the message and it will take a clip from that channel. `clipFromSender` will take a clip from the person who triggered the command. This normally corresponds to the `{{user}}` variable. `clipFromStreamer` will take a clip from your channel and send it over. You can decide to take a random clip by setting `clipRandom` to true. Or if you would like to take the first clip that matched the `clipMaxTime` given in milliseconds then you can set `clipRandom` to false. `clipLimit` will determing how many of the newest clips should be brought in to determine which clip should be selected. After a clip is selected it will start running immediately
 
 ```js
 async function() {

package/dist/custom-code/important-notes.md

@@ -13,6 +13,15 @@ title: Important notes
   The different options are: `isSelf, mod, vip, tier3, tier2, tier1, subscriber, follower`.
   In your code you should use `const levels = await getVariable('userLevelsRaw');` and then you can check a level with `if (levels.subscriber) {}` since these are all booleans
 
+## Runtime environment
+
+Your code runs inside a sandboxed browser Web Worker, not Node.js. That means:
+
+- **`fetch` is available** — you can call any HTTP/REST API directly (see the Random Twitch Clip example). `Promise`, `async/await`, `JSON`, `Math`, `Date`, `setTimeout`, etc. all work.
+- **Node.js APIs are NOT available** — there is no `require`, `import`, `fs`, `process`, `Buffer`, or `__dirname`. To read/write local files use the `readFile` / `writeFile` helpers, and to run a shell command use `execShellCommand`.
+- **You must call `done()`.** Lumia will refuse to run any code that does not contain a `done(` call, and the worker stays alive (leaking memory) until `done()` is reached, so always call it exactly once as the last thing your code does.
+- All the helper functions in `helper-functions.md` are injected as globals — you do not import them. Most return a Promise, so `await` them.
+
 ## Origin and queue type variables
 
 We expose `{{originType}}` and `{{queueType}}` so custom code can tell where an activity came from and what kind of queued activity is running.

package/dist/custom-overlays/custom-overlays-alerts.d.ts

@@ -1,5 +1,12 @@
 /// <reference path="./custom-overlays.d.ts" />
 
+/*
+ * Only the most common alerts are modeled here as concrete types (a curated
+ * subset of the ~220 `LumiaAlertValues`). Any alert not in `LumiaAlert` below
+ * still arrives — just as the generic `AlertEvent` from `custom-overlays.d.ts`.
+ * Read `data.alert`, `data.dynamic`, and `data.extraSettings` directly for those.
+ */
+
 import { LumiaAlertValues } from './custom-overlays';
 
 /* -------------------------------------------------------------------------- */

package/dist/custom-overlays/custom-overlays.d.ts

@@ -360,9 +360,18 @@ export interface ChatEvent {
 export interface AlertEvent {
 	/** Type of alert from LumiaAlertValues enum */
 	alert: LumiaAlertValues;
-	/** Dynamic value associated with the alert (e.g., donation amount, sub months) */
-	dynamic: { value: number | string };
-	/** Additional metadata about the alert */
+	/**
+	 * Event-specific mutable values. `value` is the common amount (bits, raid
+	 * viewers, sub tier, donation amount, …) but most alerts add their own fields —
+	 * e.g. subs carry `isGift`, `giftAmount`, `isResub`, `subMonths`. For the exact
+	 * per-alert shape see `AlertDynamic<T>` in `custom-overlays-alerts.d.ts`.
+	 */
+	dynamic: { value?: number | string; [key: string]: unknown };
+	/**
+	 * Additional metadata about the alert. The fields below are common to most
+	 * alerts; alert-specific fields are merged in too — see `AlertExtra<T>` in
+	 * `custom-overlays-alerts.d.ts`.
+	 */
 	extraSettings: {
 		/** Username of the person triggering the alert */
 		username: string;
@@ -384,6 +393,8 @@ export interface AlertEvent {
 		timingType: string;
 		/** Alert display duration in milliseconds */
 		duration: number;
+		/** Alert-specific extra fields (e.g. subPlan, gifter, recipients, message). */
+		[key: string]: unknown;
 	};
 	/** Whether this alert was triggered from Lumia itself */
 	fromLumia: boolean;
@@ -476,6 +487,19 @@ export type OverlayEventHandler = (data: OverlayEvent) => void;
  * Available globally as `window.Overlay` in custom overlays.
  */
 export interface Overlay {
+	/**
+	 * Current values from the Data tab (defaults seeded from Configs `value`s,
+	 * then overridden by what the user set). Read Config/Data values from here,
+	 * e.g. `Overlay.data.fontSize`. There is no bare top-level `data` variable.
+	 */
+	data: Record<string, any>;
+
+	/**
+	 * This overlay's `codeId` (letters, numbers, hyphens, underscores; max 25 chars).
+	 * Scopes `saveStorage`/`getStorage` and targets `overlaycontent` messages.
+	 */
+	codeId: string;
+
 	/**
 	 * Register an event listener for chat messages
 	 * @param event - Event type "chat"
@@ -521,6 +545,19 @@ export interface Overlay {
 	 */
 	on(event: 'overlaycontent', handler: (data: CustomOverlayContentEvent) => void): void;
 
+	/**
+	 * Register a handler for Configs `actionbutton` clicks. Not a platform event —
+	 * it's Configs-driven, needs no `events` declaration, and is independent of the
+	 * `OverlayListener` subscriptions. `key` is the field's JSON key; `value` is its
+	 * optional `value`.
+	 * @param event - Event type "configAction"
+	 * @example
+	 * window.Overlay.on('configAction', ({ key }) => {
+	 *   if (key === 'resetGame') resetGame();
+	 * });
+	 */
+	on(event: 'configAction', handler: (data: { key: string; value?: unknown }) => void): void;
+
 	/**
 	 * Execute a Lumia Stream command
 	 * @param command - Name of the command to execute
@@ -2260,3 +2297,23 @@ export declare enum SystemVariables {
 }
 
 // <auto-generated-end name="SystemVariables" />
+
+// -----------------------------------------------------------------------------
+//  Globals available inside a custom overlay's JS tab
+// -----------------------------------------------------------------------------
+
+declare global {
+	/** The Overlay API. Available unprefixed as `Overlay` or as `window.Overlay`. */
+	const Overlay: Overlay;
+
+	interface Window {
+		Overlay: Overlay;
+	}
+
+	/**
+	 * Show a toast notification in Lumia.
+	 * @param message - Text to display
+	 * @param type - Toast style (defaults to "info")
+	 */
+	function toast(message: string, type?: 'info' | 'success' | 'warning' | 'error'): void;
+}

package/dist/custom-overlays/gpt-instructions-extended.md

@@ -0,0 +1,204 @@
+# Lumia Custom Overlays GPT — Extended Reference
+
+This is the companion knowledge file to `gpt-instructions.md`. The system prompt is capped at 8000 characters so long-form reference material lives here. When a rule here conflicts with `gpt-instructions.md`, the system prompt wins.
+
+---
+
+## SystemVariables Quick Reference
+
+Curated short list. For anything not here, check `custom-overlays.d.ts` before suggesting a name. If a name is not in the enum, it does not exist — fall back to Config/Data or a custom variable.
+
+### Followers (lifetime / session count)
+
+- Twitch: `{{twitch_total_follower_count}}` / `{{twitch_session_follower_count}}`
+- Kick: `{{kick_total_follower_count}}` / `{{kick_session_follower_count}}`
+- YouTube: `{{youtube_total_subscriber_count}}` (YouTube calls followers "subscribers")
+
+### Subscribers / members (lifetime / session count)
+
+- Twitch: `{{twitch_total_subscriber_count}}` / `{{twitch_session_subscribers_count}}`
+- Kick: `{{kick_total_subscriber_count}}` / `{{kick_session_subscriber_count}}`
+- YouTube: `{{youtube_session_subscriber_count}}`
+
+### Donations (cross-platform aggregate)
+
+- Lifetime: `{{total_donation_amount}}`, `{{total_donation_amount_currency}}`, `{{total_donation_amount_currency_symbol}}`
+- Session: `{{session_donation_amount}}`, `{{session_donation_count}}`
+- Top donor: `{{session_top_donator}}`, `{{session_top_donator_amount}}`
+
+### Bits (Twitch only)
+
+- Lifetime / session count: `{{twitch_total_bits_count}}` / `{{twitch_session_bits_count}}`
+- Last bit: `{{twitch_last_bit}}`, `{{twitch_last_bit_amount}}`
+
+### Last-event names (great for "recent X" overlays)
+
+- `{{twitch_last_follower}}`, `{{twitch_last_subscriber}}`, `{{twitch_last_gifter}}`, `{{twitch_last_gifter_amount}}`, `{{twitch_last_raider}}`, `{{twitch_last_raid_amount}}`, `{{twitch_last_chatter}}`
+
+### Stream state
+
+- Live state: `{{twitch_live}}`, `{{kick_live}}`, `{{youtube_live}}`
+- Uptime: `{{twitch_uptime}}`, `{{youtube_uptime}}`
+- Viewers: `{{twitch_current_viewer_count}}`, `{{kick_current_viewer_count}}`, `{{youtube_current_viewer_count}}`
+
+### Channel info
+
+- Twitch: `{{twitch_username}}`, `{{twitch_avatar}}`, `{{twitch_channel_title}}`, `{{twitch_category}}`
+- Kick: `{{kick_username}}`, `{{kick_avatar}}`, `{{kick_channel_title}}`, `{{kick_category}}`
+
+### Function-style SystemVariables (useful in Config `input` with `enableVariables: true`)
+
+- Math / logic: `{{math=...}}`, `{{round=...}}`, `{{compare=...}}`, `{{if=...}}`, `{{between=...}}`, `{{min=...}}`, `{{max=...}}`, `{{coalesce=...}}`
+- Random: `{{random=min,max}}`, `{{random_input=a,b,c}}`, `{{selection=first,second}}`
+- Strings / dates: `{{regex_extract=...}}`, `{{replace=...}}`, `{{format_date=...}}`, `{{time_since=...}}`
+
+Rules: SystemVariables are read-only from overlays. Never `setVariable` on a SystemVariable key. Do not create Config/Data keys that duplicate SystemVariable concepts.
+
+---
+
+## Alert Values (`data.alert`)
+
+Always match with exact string equality — never `includes`, never substring matching.
+
+### Twitch
+
+- `twitch-follower`, `twitch-subscriber`, `twitch-giftSubscription`, `twitch-raid`, `twitch-raidOut`
+- `twitch-bits`, `twitch-bitsCombo`, `twitch-points`, `twitch-redemption`, `twitch-extension`
+- `twitch-channelJoin`, `twitch-channelLeave`, `twitch-firstChatter`, `twitch-entrance`, `twitch-clip`
+- `twitch-streamLive`, `twitch-streamOffline`, `twitch-categoryChanged`
+- `twitch-hypetrainStarted`, `twitch-hypetrainProgressed`, `twitch-hypetrainLevelProgressed`, `twitch-hypetrainEnded`
+- `twitch-pollStarted`, `twitch-pollProgressed`, `twitch-pollEnded`
+- `twitch-predictionStarted`, `twitch-predictionProgressed`, `twitch-predictionLocked`, `twitch-predictionEnded`
+- `twitch-goalStarted`, `twitch-goalProgressed`, `twitch-goalEnded`
+- `twitch-charityDonation`, `twitch-charityCampaignStarted`, `twitch-charityCampaignProgressed`, `twitch-charityCampaignStopped`
+- `twitch-banned`, `twitch-timeout`, `twitch-timeoutOver`, `twitch-shoutoutReceive`
+- `twitch-adStarted`, `twitch-adStopped`, `twitch-watchStreak`, `twitch-powerups`
+
+### Kick
+
+- `kick-follower`, `kick-subscriber`, `kick-giftSubscription`, `kick-points`, `kick-raid`, `kick-hosted`
+- `kick-streamLive`, `kick-streamOffline`, `kick-firstChatter`, `kick-entrance`
+- `kick-banned`, `kick-unbanned`
+
+### YouTube
+
+- `youtube-subscriber`, `youtube-member`, `youtube-giftMembers`, `youtube-superchat`, `youtube-superstickers`
+- `youtube-streamLive`, `youtube-streamOffline`, `youtube-firstChatter`, `youtube-entrance`
+
+### Donations (all cross-platform)
+
+- `streamlabs-donation`, `streamelements-donation`, `extralife-donation`, `donordrive-donation`
+- `tiltify-campaignDonation`, `kofi-donation`, `kofi-subscription`, `kofi-shopOrder`
+- `fourthwall-donation`, `fourthwall-orderPlaced`, `fourthwall-giftPurchase`, `fourthwall-subscriptionPurchased`
+- `patreon-pledge`, `lumiastream-donation`
+
+For the canonical full enum see `custom-overlays-alerts.d.ts`.
+
+---
+
+## `Overlay.chatbot` Platform Values
+
+`platform` is optional. Omit to send to every connected chat. When set, use exactly one of:
+
+- `"twitch"`, `"youtube"`, `"kick"`, `"tiktok"`, `"facebook"`, `"trovo"`
+
+Never invent other values. Never capitalize.
+
+---
+
+## OBS Events
+
+When the overlay runs inside OBS with Lumia connected, OBS events are forwarded to `window` as real DOM `CustomEvent`s. Lumia auto-detects which events the overlay uses from string literals in `addEventListener` calls — so always use a direct string literal.
+
+### Supported event names
+
+- `obsRecordingStarted`, `obsRecordingStopped`, `obsRecordingPaused`, `obsRecordingUnpaused`
+- `obsStreamingStarted`, `obsStreamingStopped`
+- `obsReplaybufferStarted`, `obsReplaybufferStopped`
+- `obsVirtualcamStarted`, `obsVirtualcamStopped`
+- `obsSceneChanged`
+- `obsTransitionBegin`, `obsTransitionEnd`
+- `obsSourceVisibleChanged`, `obsSourceActiveChanged`
+
+### Usage
+
+```js
+window.addEventListener("obsSceneChanged", (e) => {
+  const sceneName = e.detail?.name;
+  // react to scene change
+});
+```
+
+Notes:
+
+- `e.detail` is correct here because these are real `CustomEvent` objects. Lumia's own overlay events (`chat`, `alert`, `hfx`, `virtuallight`, `overlaycontent`) still use the raw-payload `Overlay.on` API — don't confuse the two.
+- OBS events only fire when the overlay runs inside OBS with Lumia running. Handle the case where they never fire.
+
+---
+
+## Free CDN Assets (no API key, hotlink-safe)
+
+Safe to recommend to normal users. Stable URLs, permissive licenses, no signup required.
+
+### Images
+
+- **Lorem Picsum** — random photos, CC0.
+  - Pattern: `https://picsum.photos/{width}/{height}?random={seed}`
+  - Example: `https://picsum.photos/800/600?random=12`
+- **DiceBear** — deterministic avatars. Great for chat-avatar fallbacks.
+  - Pattern: `https://api.dicebear.com/9.x/{style}/svg?seed={anything}`
+  - Styles: `bottts`, `pixel-art`, `lorelei`, `thumbs`, `shapes`, `adventurer`, `avataaars`, `fun-emoji`, `identicon`, `initials`, `micah`, `miniavs`, `notionists`, `open-peeps`, `personas`.
+  - Example: `https://api.dicebear.com/9.x/bottts/svg?seed=lumia`
+
+### Icons and logos
+
+- **Simple Icons** — brand logos for 3000+ companies.
+  - Pattern: `https://cdn.simpleicons.org/{slug}/{color?}`
+  - Example: `https://cdn.simpleicons.org/twitch/9146FF`
+- **Twemoji** — Twitter's open emoji set (MIT).
+  - Pattern: `https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/72x72/{codepoint}.png`
+  - Example (🔥 = 1f525): `https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/72x72/1f525.png`
+- **OpenMoji** — CC BY-SA open emoji.
+  - Pattern: `https://openmoji.org/data/color/svg/{CODEPOINT}.svg`
+
+### Pokemon sprites (used by the Pokemon example)
+
+- `https://img.pokemondb.net/sprites/home/{normal|shiny}/{slug}.png`
+
+### Do NOT recommend
+
+Services requiring an API key or signup (Unsplash API, Pexels, Pixabay, Giphy, Tenor, Freesound) — normal users won't do the setup.
+
+---
+
+## Lumia-Hosted Asset Library (existing placeholders)
+
+Already hosted on Lumia's CDN — safe to use as fallbacks when the user hasn't supplied an asset:
+
+- Generic image: `https://storage.lumiastream.com/placeholderLogo.png`
+- Empty avatar: `https://storage.lumiastream.com/placeholderUserIcon.png`
+- Game art: `https://storage.lumiastream.com/overlays/2/bed3ba31-f516-476d-975a-3498f5b5f33e.png`
+- Spin SFX: `https://storage.lumiastream.com/overlays/lumia/audio/Wheel_of_Fortune.mp3`
+- Win SFX: `https://storage.lumiastream.com/overlays/lumia/audio/crowdClap.mp3`
+- Lose SFX: `https://storage.lumiastream.com/overlays/lumia/audio/youLose.mp3`
+
+---
+
+## Lumia-Hosted Asset Library — NOT YET AVAILABLE (do not suggest)
+
+⚠️ There is **no** general `https://storage.lumiastream.com/overlays/lumia/assets/...` asset library yet — those URLs do **not** resolve. Never invent, guess, or hand a user any `.../overlays/lumia/assets/...` path. An expanded CC0 SFX/image library is planned for that location, but until it ships, only point users at the two safe sources:
+
+- The confirmed Lumia-hosted placeholders in the **Lumia-Hosted Asset Library (existing placeholders)** section above.
+- The keyless free-CDN patterns in the **Free CDN Assets** section above.
+
+If a user needs a sound or image you can't source from those, have them upload their own through a Config `soundupload` / `imageupload` / `videoupload` field instead of pointing at a URL that may not exist.
+
+---
+
+## Style Crib Sheet
+
+- Numbers from Config/Data: `const n = Number(Overlay.data?.key) || defaultValue;`
+- Guard against missing chat fields: `const msg = (data.message || "").trim();`
+- Check moderator status: `const isMod = data.userLevels?.mod || data.userLevels?.isSelf;`
+- Get a Config value as string via token replacement: `const color = "{{accentColor}}";`
+- Lumia wraps the JS tab in `(async () => { ... })()`, so top-level `await` works.

package/dist/custom-overlays.d.ts

@@ -360,9 +360,18 @@ export interface ChatEvent {
 export interface AlertEvent {
 	/** Type of alert from LumiaAlertValues enum */
 	alert: LumiaAlertValues;
-	/** Dynamic value associated with the alert (e.g., donation amount, sub months) */
-	dynamic: { value: number | string };
-	/** Additional metadata about the alert */
+	/**
+	 * Event-specific mutable values. `value` is the common amount (bits, raid
+	 * viewers, sub tier, donation amount, …) but most alerts add their own fields —
+	 * e.g. subs carry `isGift`, `giftAmount`, `isResub`, `subMonths`. For the exact
+	 * per-alert shape see `AlertDynamic<T>` in `custom-overlays-alerts.d.ts`.
+	 */
+	dynamic: { value?: number | string; [key: string]: unknown };
+	/**
+	 * Additional metadata about the alert. The fields below are common to most
+	 * alerts; alert-specific fields are merged in too — see `AlertExtra<T>` in
+	 * `custom-overlays-alerts.d.ts`.
+	 */
 	extraSettings: {
 		/** Username of the person triggering the alert */
 		username: string;
@@ -384,6 +393,8 @@ export interface AlertEvent {
 		timingType: string;
 		/** Alert display duration in milliseconds */
 		duration: number;
+		/** Alert-specific extra fields (e.g. subPlan, gifter, recipients, message). */
+		[key: string]: unknown;
 	};
 	/** Whether this alert was triggered from Lumia itself */
 	fromLumia: boolean;
@@ -476,6 +487,19 @@ export type OverlayEventHandler = (data: OverlayEvent) => void;
  * Available globally as `window.Overlay` in custom overlays.
  */
 export interface Overlay {
+	/**
+	 * Current values from the Data tab (defaults seeded from Configs `value`s,
+	 * then overridden by what the user set). Read Config/Data values from here,
+	 * e.g. `Overlay.data.fontSize`. There is no bare top-level `data` variable.
+	 */
+	data: Record<string, any>;
+
+	/**
+	 * This overlay's `codeId` (letters, numbers, hyphens, underscores; max 25 chars).
+	 * Scopes `saveStorage`/`getStorage` and targets `overlaycontent` messages.
+	 */
+	codeId: string;
+
 	/**
 	 * Register an event listener for chat messages
 	 * @param event - Event type "chat"
@@ -521,6 +545,19 @@ export interface Overlay {
 	 */
 	on(event: 'overlaycontent', handler: (data: CustomOverlayContentEvent) => void): void;
 
+	/**
+	 * Register a handler for Configs `actionbutton` clicks. Not a platform event —
+	 * it's Configs-driven, needs no `events` declaration, and is independent of the
+	 * `OverlayListener` subscriptions. `key` is the field's JSON key; `value` is its
+	 * optional `value`.
+	 * @param event - Event type "configAction"
+	 * @example
+	 * window.Overlay.on('configAction', ({ key }) => {
+	 *   if (key === 'resetGame') resetGame();
+	 * });
+	 */
+	on(event: 'configAction', handler: (data: { key: string; value?: unknown }) => void): void;
+
 	/**
 	 * Execute a Lumia Stream command
 	 * @param command - Name of the command to execute
@@ -2260,3 +2297,23 @@ export declare enum SystemVariables {
 }
 
 // <auto-generated-end name="SystemVariables" />
+
+// -----------------------------------------------------------------------------
+//  Globals available inside a custom overlay's JS tab
+// -----------------------------------------------------------------------------
+
+declare global {
+	/** The Overlay API. Available unprefixed as `Overlay` or as `window.Overlay`. */
+	const Overlay: Overlay;
+
+	interface Window {
+		Overlay: Overlay;
+	}
+
+	/**
+	 * Show a toast notification in Lumia.
+	 * @param message - Text to display
+	 * @param type - Toast style (defaults to "info")
+	 */
+	function toast(message: string, type?: 'info' | 'success' | 'warning' | 'error'): void;
+}

package/dist/esm/variableExamples.js

@@ -309,14 +309,6 @@ export const VARIABLE_EXAMPLES = {
         { label: 'Post each line of a URL', snippet: 'filesay=https://example.com/list.txt' },
         { label: 'Post each line of a local file', snippet: 'filesay=C:/path/list.txt' },
     ],
-    set_alerts_paused: [
-        { label: 'Pause alerts', snippet: 'set_alerts_paused=true' },
-        { label: 'Resume alerts', snippet: 'set_alerts_paused=false' },
-    ],
-    set_sfx_muted: [
-        { label: 'Mute sound effects', snippet: 'set_sfx_muted=true' },
-        { label: 'Unmute sound effects', snippet: 'set_sfx_muted=false' },
-    ],
     loyalty_top: [
         { label: 'Top 3 users', snippet: 'loyalty_top=3' },
         { label: 'Top 5 users', snippet: 'loyalty_top=5' },

package/dist/variableExamples.js

@@ -312,14 +312,6 @@ exports.VARIABLE_EXAMPLES = {
         { label: 'Post each line of a URL', snippet: 'filesay=https://example.com/list.txt' },
         { label: 'Post each line of a local file', snippet: 'filesay=C:/path/list.txt' },
     ],
-    set_alerts_paused: [
-        { label: 'Pause alerts', snippet: 'set_alerts_paused=true' },
-        { label: 'Resume alerts', snippet: 'set_alerts_paused=false' },
-    ],
-    set_sfx_muted: [
-        { label: 'Mute sound effects', snippet: 'set_sfx_muted=true' },
-        { label: 'Unmute sound effects', snippet: 'set_sfx_muted=false' },
-    ],
     loyalty_top: [
         { label: 'Top 3 users', snippet: 'loyalty_top=3' },
         { label: 'Top 5 users', snippet: 'loyalty_top=5' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumiastream/lumia-types",
-  "version": "3.8.1",
+  "version": "3.8.3",
   "description": "",
   "main": "./dist/index.js",
   "module": "./dist/esm/index.js",