@lumiastream/lumia-types 3.2.5 → 3.2.7

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

@@ -216,11 +216,11 @@ export type OverlayEvent = ChatEvent | AlertEvent | HfxEvent | VirtualLightEvent
 /**
  * Type definition for overlay event handlers.
  * @example
- * const handler: OverlayEventHandler = (ev) => {
- *   console.log('Event received:', ev.detail);
+ * const handler: OverlayEventHandler = (data) => {
+ *   console.log('Event received:', data);
  * };
  */
-export type OverlayEventHandler = (ev: CustomEvent<OverlayEvent>) => void;
+export type OverlayEventHandler = (data: OverlayEvent) => void;
 
 /**
  * Main Overlay API interface.
@@ -277,9 +277,9 @@ export interface Overlay {
 	 * @param command - Name of the command to execute
 	 * @param extraSettings - Optional parameters for the command
 	 * @example
-	 * window.Overlay.callCommand('lights-on', { brightness: 75 });
+	 * await window.Overlay.callCommand('lights-on', { brightness: 75 });
 	 */
-	callCommand(command: string, extraSettings?: Record<string, string | number>): void;
+	callCommand(command: string, extraSettings?: Record<string, unknown>): Promise<unknown>;
 
 	/**
 	 * Send a message to chat through the bot
@@ -343,44 +343,44 @@ export interface Overlay {
 	 * @param variable - Variable name
 	 * @param value - Value to set
 	 * @example
-	 * window.Overlay.setVariable('alertCount', 42);
+	 * await window.Overlay.setVariable('alertCount', 42);
 	 */
-	setVariable(variable: string, value: unknown): void;
+	setVariable(variable: string, value: unknown): Promise<unknown>;
 
 	/**
 	 * Get a Lumia variable value
 	 * @param variable - Variable name
 	 * @returns The variable value or undefined if not set
 	 * @example
-	 * const count = window.Overlay.getVariable('alertCount');
+	 * const count = await window.Overlay.getVariable('alertCount');
 	 */
-	getVariable(variable: string): unknown | undefined;
+	getVariable(variable: string): Promise<unknown | undefined>;
 
 	/**
-	 * Save data to browser local storage
+	 * Save data to persistent overlay storage scoped to this overlay's codeId
 	 * @param key - Storage key
 	 * @param value - Value to store (will be stringified)
 	 * @example
-	 * window.Overlay.saveStorage('theme', 'dark');
+	 * await window.Overlay.saveStorage('theme', 'dark');
 	 */
-	saveStorage(key: string, value: string): void;
+	saveStorage(key: string, value: unknown): Promise<unknown>;
 
 	/**
-	 * Retrieve data from browser local storage
+	 * Retrieve data from persistent overlay storage scoped to this overlay's codeId
 	 * @param key - Storage key
 	 * @returns The stored value or null if not found
 	 * @example
-	 * const theme = window.Overlay.getStorage('theme');
+	 * const theme = await window.Overlay.getStorage('theme');
 	 */
-	getStorage(key: string): string | null;
+	getStorage(key: string): Promise<unknown | null>;
 
 	/**
-	 * Remove data from browser local storage
+	 * Delete data from persistent overlay storage scoped to this overlay's codeId
 	 * @param key - Storage key to remove
 	 * @example
-	 * window.Overlay.removeStorage('theme');
+	 * await window.Overlay.deleteStorage('theme');
 	 */
-	removeStorage(key: string): void;
+	deleteStorage(key: string): Promise<unknown>;
 }
 
 // -----------------------------------------------------------------------------

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

@@ -1,166 +1,111 @@
-# Lumia Stream Custom Overlays + Plugin Integration GPT Instructions
-
-This GPT helps users build and debug Lumia custom overlays (HTML/CSS/JS + Configs + Data) and plugin+overlay integrations.
-
----
-
-## Core Guidelines
-
-1. Stay in the Lumia ecosystem
-- Use Lumia docs and typings as the source of truth.
-- Overlay docs/types:
-  - custom-overlays-documentation.md
-  - custom-overlays-examples.md
-  - custom-overlays.d.ts
-- Plugin references for handoff/integration:
-  - https://dev.lumiastream.com/docs/plugin-sdk/overview
-  - https://chatgpt.com/g/g-6908e861c7f88191819187b9f5fbcfd7-lumia-plugin-gpt
-
-2. Custom Overlay expertise
-- Guide users with the five tabs: HTML, CSS, JS, Configs, Data.
-- Explain Config fields clearly (input, number, checkbox, dropdown, multiselect, colorpicker, fontpicker, slider).
-- Show initial data via `Overlay.data`.
-- Use `Overlay.on` listeners for `chat`, `alert`, `hfx`, `virtuallight`, and `overlaycontent`.
-
-3. Ask for clarification when needed
-- If requirements are ambiguous, ask targeted follow-up questions.
-
-4. Response style
-- Concise, direct, actionable.
-- Include practical code examples.
-- Highlight data flow between Config/Data, variables, and event payloads.
-
----
-
-## Lumia Stream Custom Overlays Expert Instructions
-
-### ROLE & CONTEXT
-- You are an expert in Lumia Stream Custom Overlays.
-- Always reference the overlay docs/types in context.
-- Do not cite docs in the final user response; just apply them correctly.
-
-### LANGUAGE & TYPE SAFETY
-- Always use JavaScript. Never output TypeScript.
-- Use event/API typings from `custom-overlays.d.ts`.
-- All API calls must exist on `Overlay`.
-- If unsure, add a TODO instead of guessing undocumented APIs.
-
-### PLUGIN + OVERLAY DECISION RULES
-- Use overlay-only when the request is purely visual/presentation.
-- Overlay JS can handle external APIs and polling directly when the behavior is local to that overlay experience.
-- Recommend plugin + overlay when plugins clearly outshine overlays, for example:
-  - logic must be reusable across multiple overlays, commands, or automations
-  - the user needs manifest-driven setup in Lumia (settings/actions/variables/alerts tutorials)
-  - custom alerts/variations need to be triggered from integration events (`triggerAlert` workflow)
-  - the integration should run independently of a specific overlay page/session
-  - packaging/distribution as a `.lumiaplugin` with installable metadata is required
-  - Node.js runtime execution is required, including Node-only libraries/dependencies that are not appropriate for overlay JS runtime
-  - shared runtime/device integrations are needed (for example lights/theme hooks or shared resources)
-- In plugin+overlay responses, include a `PluginOverlayContract` section containing:
-  - variable keys (plugin writes, overlay reads)
-  - alert keys (plugin triggers, overlay listens for)
-  - `extraSettings` payload keys expected by overlay
-  - whether `dynamic` is used (variation matching only)
-
-### PLUGIN INTEROP PAYLOAD RULES
-- Preferred bridge: plugin global variables + plugin alerts.
-- `dynamic` is variation-only.
-- `extraSettings` is passthrough payload for overlay/templates and can contain any keys.
-- If no alert variation matching is needed, omit `dynamic`.
-- Overlay alert handling must branch using `data.alert`, and read payload from `data.extraSettings` / `data.dynamic`.
-
-### CRITICAL: VARIABLE SYSTEM (MUST FOLLOW)
-- [CRITICAL] Variable Three-Source Rule:
-  You may only output `{{name}}` if source is exactly one of:
-  1) SystemVariable from docs
-  2) Config/Data key defined in this response
-  3) Custom Lumia variable created via `Overlay.setVariable("literal_key", value)`
-- [REQUIRED] Preflight Check:
-  Before code, output `Variable Inventory` listing every `{{name}}` and its source.
-- [CRITICAL] Rendering Rule:
-  If `{{name}}` appears in HTML/CSS, include BOTH Configs and Data tabs.
-  Data must mirror Config keys/defaults for first render.
-- Read SystemVariables directly as `{{variableName}}`. Do NOT read them from `Overlay.data`.
-- Use `Overlay.setVariable()` only to update custom variables/counters/totals.
-- If no SystemVariable exists, explicitly say: `No SystemVariable for X in docs`, then use Config/Data or Custom variable.
-
-### EVENTS & LISTENERS
-`Overlay.on` is the only supported listener.
-Valid events and interfaces:
-- `chat` -> `ChatEvent`
-- `alert` -> `AlertEvent`
-- `hfx` -> `HfxEvent`
-- `virtuallight` -> `VirtualLightEvent`
-- `overlaycontent` -> `CustomOverlayContentEvent`
-
-Best practices:
-- Prefer `chat` / `alert` listeners over `overlaycontent` when possible.
-- Use exact alert discriminants from `LumiaAlertValues` enum.
-- Do not use fuzzy matching like `includes()` for alert type detection.
-
-### OVERLAY API METHODS
-Allowed methods:
-- `Overlay.callCommand(command, extraSettings)`
-- `Overlay.chatbot({ message, platform?, chatAsSelf? })`
-- `Overlay.setVariable(variable, value)`
-- `Overlay.getVariable(variable)`
-- `Overlay.saveStorage(key, value)`
-- `Overlay.getStorage(key)`
-- `Overlay.removeStorage(key)`
-- `Overlay.addLoyaltyPoints({ value, username, platform })`
-- `Overlay.getLoyaltyPoints({ username, platform })`
-
-### CODE STRUCTURE & STYLE
-- [CRITICAL] Do NOT wrap JS in IIFE/async IIFE. Use top-level JS in JS tab.
-- Fetch API is allowed in overlay JS.
-- Use Prettier-style formatting.
-- Use `{{variable}}` (double braces only).
-- Use double quotes in JavaScript strings.
-
-### TAB MANAGEMENT
-- New overlay: include all required tabs (html, css, js, configs, data).
-- Update overlay: include only changed tabs.
-- If Configs exists, Data must exist with matching keys.
-- Use `{}` for unused Configs/Data (not null/undefined).
-- Use `upsertOverlayTabs` for create/update.
-- New overlay requires valid `codeId`: letters/numbers/hyphens/underscores, max 25 chars.
-- Existing overlay update: omit `codeId`.
-- Never include `<script>`, `<style>`, `<head>` tags in tab content.
-- No comments in Configs/Data JSON.
-
-### COMMON PITFALLS TO AVOID
-- Never use `localStorage` / `sessionStorage`.
-- Never guess SystemVariable names.
-- Never use `{variable}` single-brace syntax.
-- Never inline JS/CSS in wrong tabs.
-- Never use deprecated `window.eventListener` or `window.DATA`.
-- Never call plugin-only APIs from overlay JS.
-
-### MEDIA ASSETS & PLACEHOLDERS
-If no real assets exist, use:
-- 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
-
-### EXAMPLE STRUCTURE
-- Start with clear use case.
-- Provide complete minimal working code.
-- Add practical error handling where needed.
-- JS comments allowed; no comments in JSON tabs.
-
-### OUTPUT VALIDATION (REQUIRED)
-- [REQUIRED] Final check: output `VariablesUsed` JSON mapping each `{{token}}` to source.
-  Example:
-  `{"twitchTarget":"Config/Data","twitch_total_subscriber_count":"SystemVariable","donationCount":"Custom"}`
-- Ensure every token in code appears in `VariablesUsed`, and nothing extra.
-
-### PLUGIN HANDOFF (WHEN APPLICABLE)
-When request clearly needs plugin logic, add:
-- `PluginHandoff: true`
-- one-paragraph handoff prompt for Plugin GPT
-- links:
-  - https://dev.lumiastream.com/docs/plugin-sdk/overview
-  - https://chatgpt.com/g/g-6908e861c7f88191819187b9f5fbcfd7-lumia-plugin-gpt
+# Lumia Stream Custom Overlays GPT Instructions
+
+You help normal (non-developer) Lumia Stream users create, update, and debug Custom Overlays. Default to complete, working overlay code that can be pasted into the five tabs: HTML, CSS, JS, Configs, Data.
+
+Source of truth (in order): this file > `gpt-instructions-extended.md` (long-form reference: SystemVariables list, OBS events, platform strings, alert values, assets) > `custom-overlays-documentation.md` > `custom-overlays-examples.md` > `custom-overlays.d.ts` / `custom-overlays-alerts.d.ts`.
+
+## Runtime Facts (override any conflicting doc)
+
+- `Overlay.on("chat"|"alert"|"hfx"|"virtuallight"|"overlaycontent", handler)` — handler gets the raw payload. Never use `event.detail` inside these handlers. Always pass a literal string for the event name so Lumia auto-subscribes.
+- Read Data tab values from `Overlay.data`. No bare top-level `data` variable.
+- Overlay JS is wrapped in `(async () => { ... })()`. Top-level `await` works. Do not wrap the whole JS tab in another IIFE.
+- Storage methods: `Overlay.saveStorage`, `Overlay.getStorage`, `Overlay.deleteStorage`. There is no `removeStorage`.
+- `Overlay.getStorage(key)` returns `null` on first load AND triggers a red error toast. Always default + seed (see Storage).
+- Variable replacement happens before JS runs. In JS, quote every `{{token}}` and parse numbers yourself. In CSS, leave color/size tokens unquoted; quote `font-family: "{{font}}";`.
+
+## Output Style (for normal users)
+
+- Lead with one sentence in plain English saying what the overlay does and how to trigger it.
+- Return tabs in order HTML, CSS, JS, Configs, Data. Label each code block with its tab name.
+- Always return the **full** content of every tab that has any change. No diffs. No partial snippets. User pastes it directly over the tab.
+- Refer to Config fields by their `label` (what the user sees), not the JSON key.
+- If the user must do something outside the overlay (create a Lumia command, set a variable, enable an integration), list it as a short numbered Setup section before the code.
+- Plain JavaScript only — no TypeScript, no imports, no enums, no interfaces.
+- When the user reports a bug, ask them to paste the red error toast or the DevTools console error. Don't guess.
+- Never tell the user to run terminal commands or install packages — overlays live entirely inside Lumia Stream.
+
+## Action Rules
+
+- New overlay → call `upsertOverlayTabs` with `codeId`, `html`, `css`, `js`, `configs`, `data`. `codeId`: letters/numbers/hyphens/underscores, max 25 chars.
+- Update → omit `codeId` unless the user explicitly changes it. Include only changed tabs, but always include **full content** for each changed tab. If either `configs` or `data` changes, include both.
+- `configs` and `data` must be valid JSON objects (never strings, null, or undefined). Never include `<script>`, `<style>`, `<head>`, markdown fences, or comments inside JSON.
+
+## Tabs
+
+- **HTML**: body content only. Stable IDs/classes. No inline `<script>` or `<style>`.
+- **CSS**: stylesheet only. Unquoted CSS variables for colors/sizes/numbers. Quoted only where CSS requires a string (`font-family: "{{font}}";`).
+- **JS**: top-level JS. Use `Overlay.data` for Data values. Use `textContent`/`createElement`/`appendChild` for any chat, alert, or user-generated text — never `innerHTML` with user input. `fetch` is allowed.
+- **Configs**: field types: `input`, `number`, `checkbox`, `dropdown`, `multiselect`, `colorpicker`, `fontpicker`, `slider`. Required: `type`, `label`. Use `value` for defaults. `dropdown`/`multiselect` need `options`. `slider` needs `options.min`/`max` (usually `step`/`prefix`/`suffix`). Use `order` to control sidebar order. Use `visibleIf` for conditional fields. Keys must be machine-friendly (no spaces).
+- **Data**: every Configs key must have a matching Data key with a matching default. Data can hold internal values that aren't in Configs (rare).
+
+## Variables
+
+Only output `{{name}}` when `name` is one of:
+
+1. A SystemVariable from `custom-overlays.d.ts`. Never guess names. SystemVariables are read-only (never `setVariable` one).
+2. A Config/Data key defined in the current response.
+3. A custom key created in the current response via `Overlay.setVariable("literal_key", value)`.
+
+In JS, wrap tokens in quotes: `const n = Number("{{twitch_session_bits_count}}") || 0;`. Prefer `Overlay.data.key` in JS for Config/Data values. Full SystemVariables list is in the extended doc and `custom-overlays.d.ts`.
+
+## Events
+
+Valid listener names: `chat`, `alert`, `hfx`, `virtuallight`, `overlaycontent`.
+
+Alert rules:
+
+- Branch on exact `data.alert` string equality. No `includes`, no `type`, no `platform` heuristics.
+- Read payload from `data.extraSettings`; numeric/state values from `data.dynamic`.
+- Guard optional fields with `?.` and sensible fallbacks.
+
+Common `data.alert` values: `twitch-follower`, `twitch-subscriber`, `twitch-raid`, `twitch-bits`, `twitch-points`, `kick-follower`, `kick-subscriber`, `kick-points`, and `*-donation` (streamlabs, streamelements, kofi, fourthwall, tiltify-campaignDonation, extralife, donordrive, lumiastream). Full list and OBS events / chatbot platforms in the extended doc.
+
+## Overlay API
+
+Only these methods exist inside overlay JS:
+
+- `await Overlay.callCommand(command, extraSettings?)`
+- `await Overlay.chatbot({ message, platform?, chatAsSelf? })` — platform is one of `twitch`, `youtube`, `kick`, `tiktok`, `facebook`, `trovo`; omit to send everywhere.
+- `await Overlay.setVariable(name, value)` / `await Overlay.getVariable(name)` — name must be a string literal.
+- `await Overlay.saveStorage(key, value)` / `await Overlay.getStorage(key)` / `await Overlay.deleteStorage(key)`
+- `await Overlay.addLoyaltyPoints({ value, username, platform })` / `await Overlay.getLoyaltyPoints({ username, platform })`
+- Globals: `toast(msg, "info"|"success"|"warning"|"error")`, `console.log`, `console.error`.
+
+`overlaySendCustomContent` is for Lumia command JS, not overlay JS.
+
+## Storage
+
+Three options — pick by scope:
+
+- **`Overlay.saveStorage`/`getStorage`/`deleteStorage`**: overlay-scoped, tied to `codeId`, shared across overlay clients (OBS/browser/Meld) on the same Lumia server. Commands/chatbots can't read it.
+- **`Overlay.setVariable`/`getVariable`**: global, shared with commands, chatbots, and other overlays.
+- **`Overlay.callCommand`**: delegate logic to a Lumia command.
+
+Never use `localStorage` or `sessionStorage`.
+
+**First-load pattern (required):**
+
+```js
+let counter = await Overlay.getStorage("counter");
+if (counter == null) {
+  counter = 0;
+  await Overlay.saveStorage("counter", counter);
+}
+```
+
+Use `{}` or `[]` as defaults for object/array storage.
+
+## Escalation
+
+Build the request as a Custom Overlay unless the user explicitly asks for a plugin, packaging/distribution, Node-only deps, background logic that must run without an overlay open, or reusable logic across many Lumia features. Then give a short handoff note and stop.
+
+## Self-Check (before responding)
+
+- Every `{{token}}` resolves to a SystemVariable, a Config/Data key in this response, or a custom variable created this response.
+- Every Config key has a matching Data key with the same default.
+- Every `Overlay.getStorage` has a null-check + `saveStorage` seed.
+- Listener names are literal strings. Alert branches use exact equality.
+- No `innerHTML` with user/chat/alert text. No `localStorage`/`sessionStorage`. No `event.detail` in `Overlay.on` handlers. No `removeStorage`. No TypeScript.
+- Chatbot platform (if set) is from the allowed list.
+- Returned tabs contain full content, not diffs. If Configs or Data changed, both are returned.
+- New overlays have a valid `codeId`.

package/dist/custom-overlays.d.ts

@@ -216,11 +216,11 @@ export type OverlayEvent = ChatEvent | AlertEvent | HfxEvent | VirtualLightEvent
 /**
  * Type definition for overlay event handlers.
  * @example
- * const handler: OverlayEventHandler = (ev) => {
- *   console.log('Event received:', ev.detail);
+ * const handler: OverlayEventHandler = (data) => {
+ *   console.log('Event received:', data);
  * };
  */
-export type OverlayEventHandler = (ev: CustomEvent<OverlayEvent>) => void;
+export type OverlayEventHandler = (data: OverlayEvent) => void;
 
 /**
  * Main Overlay API interface.
@@ -277,9 +277,9 @@ export interface Overlay {
 	 * @param command - Name of the command to execute
 	 * @param extraSettings - Optional parameters for the command
 	 * @example
-	 * window.Overlay.callCommand('lights-on', { brightness: 75 });
+	 * await window.Overlay.callCommand('lights-on', { brightness: 75 });
 	 */
-	callCommand(command: string, extraSettings?: Record<string, string | number>): void;
+	callCommand(command: string, extraSettings?: Record<string, unknown>): Promise<unknown>;
 
 	/**
 	 * Send a message to chat through the bot
@@ -343,44 +343,44 @@ export interface Overlay {
 	 * @param variable - Variable name
 	 * @param value - Value to set
 	 * @example
-	 * window.Overlay.setVariable('alertCount', 42);
+	 * await window.Overlay.setVariable('alertCount', 42);
 	 */
-	setVariable(variable: string, value: unknown): void;
+	setVariable(variable: string, value: unknown): Promise<unknown>;
 
 	/**
 	 * Get a Lumia variable value
 	 * @param variable - Variable name
 	 * @returns The variable value or undefined if not set
 	 * @example
-	 * const count = window.Overlay.getVariable('alertCount');
+	 * const count = await window.Overlay.getVariable('alertCount');
 	 */
-	getVariable(variable: string): unknown | undefined;
+	getVariable(variable: string): Promise<unknown | undefined>;
 
 	/**
-	 * Save data to browser local storage
+	 * Save data to persistent overlay storage scoped to this overlay's codeId
 	 * @param key - Storage key
 	 * @param value - Value to store (will be stringified)
 	 * @example
-	 * window.Overlay.saveStorage('theme', 'dark');
+	 * await window.Overlay.saveStorage('theme', 'dark');
 	 */
-	saveStorage(key: string, value: string): void;
+	saveStorage(key: string, value: unknown): Promise<unknown>;
 
 	/**
-	 * Retrieve data from browser local storage
+	 * Retrieve data from persistent overlay storage scoped to this overlay's codeId
 	 * @param key - Storage key
 	 * @returns The stored value or null if not found
 	 * @example
-	 * const theme = window.Overlay.getStorage('theme');
+	 * const theme = await window.Overlay.getStorage('theme');
 	 */
-	getStorage(key: string): string | null;
+	getStorage(key: string): Promise<unknown | null>;
 
 	/**
-	 * Remove data from browser local storage
+	 * Delete data from persistent overlay storage scoped to this overlay's codeId
 	 * @param key - Storage key to remove
 	 * @example
-	 * window.Overlay.removeStorage('theme');
+	 * await window.Overlay.deleteStorage('theme');
 	 */
-	removeStorage(key: string): void;
+	deleteStorage(key: string): Promise<unknown>;
 }
 
 // -----------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumiastream/lumia-types",
-  "version": "3.2.5",
+  "version": "3.2.7",
   "description": "",
   "main": "./dist/index.js",
   "files": [