@zaflun/lumio-agent-skill 0.5.0 → 0.5.3

package/dist/bin/lumio-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   installSkillFiles
-} from "../chunk-QXQNAYHN.js";
+} from "../chunk-TKNV5K6F.js";
 
 // src/bin/lumio-skills.ts
 import { resolve } from "path";

package/dist/{chunk-QXQNAYHN.js → chunk-TKNV5K6F.js}

@@ -14,8 +14,8 @@ Lumio Extensions are sandboxed React apps that run inside a 3-layer iframe sandb
 \`\`\`
 3-Layer Sandbox:
   Host (lumio.vision / browser source)
-    \u2514\u2500\u2500 Supervisor iframe (supervisor.extension.lumio.vision)
-          \u2514\u2500\u2500 Extension Runtime iframe (ext.lumio.vision)
+    \u2514\u2500\u2500 Supervisor iframe (supervisor.ext.lumio.vision)
+          \u2514\u2500\u2500 Extension Runtime iframe (<label>.runtime.ext.lumio.vision)
                 \u2514\u2500\u2500 Web Worker (server function execution)
 \`\`\`
 
@@ -30,7 +30,7 @@ Extension Project:
 \`\`\`
 
 **Runtime flow:**
-1. Extension Runtime iframe loads from \`ext.lumio.vision/ext/{slug}/layer?token=lm_ext_xxx&install_id=uuid\`
+1. Extension Runtime iframe loads on the extension's own origin \`<label>.runtime.ext.lumio.vision\` (\`<label>\` = extension UUID as 32 lowercase hex)
 2. \`Lumio.render(<Component />, { target: "layer" })\` must be called within 10 seconds
 3. The custom React reconciler serializes the tree to \`LumioComponentNode[]\` via postMessage to the Supervisor
 4. The Supervisor validates and forwards the node tree to the Host for rendering
@@ -76,6 +76,10 @@ All three surfaces share storage via \`useExtensionStorage()\` \u2014 changes in
   },
   "visibility": "public",
   "pricing": { "type": "free" },
+  "sounds": [
+    { "file": "alert.mp3", "name": "Alert" },
+    { "file": "chime.wav", "name": "Chime", "default_volume": 0.8 }
+  ],
   "config_schema": [
     { "key": "title", "type": "string", "label": "Widget Title", "default_value": "My Widget", "required": true, "placeholder": "Enter title..." },
     { "key": "fontSize", "type": "number", "label": "Font Size", "default_value": 16, "required": false, "min": 8, "max": 200, "unit": "px" },
@@ -95,6 +99,8 @@ All three surfaces share storage via \`useExtensionStorage()\` \u2014 changes in
 - \`"visibility": "unlisted"\` \u2014 accessible by direct link only
 - Private invite: grant \`free_access\` to specific accounts via dashboard
 
+**Bundled sounds:** Place audio files in \`dist/sounds/\` and declare them in the \`sounds\` array. Supported: MP3, WAV, OGG, WebM, M4A, AAC, FLAC. Default limits: 50 sounds per extension, 10 MB per file, 200 MB total storage (all admin-configurable). Developers can view limits at \`/account/developer/limits\` and request increases via a 4-step wizard. Requests are reviewed by admins in the admin app. Users cannot delete bundled sounds \u2014 uninstalling the extension removes them.
+
 **Revenue split:** Configurable per developer (default 70/30 developer/Lumio).
 
 **Feature gates:** The following Lumio plan features must be enabled for extension functionality:
@@ -196,26 +202,17 @@ export const fetchScores = action({
 });
 \`\`\`
 
-**Extension Actions** via \`useLumioAction()\` (21 total, \`action\` is \`LumioActionType\`):
+**Extension Actions** via \`useLumioAction()\` (dispatched by the Lumio API; \`action\` is \`LumioActionType\`):
 \`\`\`tsx
 // Trigger platform actions (requires matching permission in lumio.config.json)
 const { execute: sendChat } = useLumioAction("chat:send");
-const { execute: banUser } = useLumioAction("chat:ban");
-const { execute: unbanUser } = useLumioAction("chat:unban");
-const { execute: timeoutUser } = useLumioAction("chat:timeout");
+const { execute: deleteChat } = useLumioAction("chat:delete");
 const { execute: setScene } = useLumioAction("obs:set_scene");
-const { execute: startRecording } = useLumioAction("obs:start_recording");
-const { execute: stopRecording } = useLumioAction("obs:stop_recording");
+const { execute: setSourceVisible } = useLumioAction("obs:set_source_visible");
+const { execute: startStream } = useLumioAction("obs:start_stream");
+const { execute: stopStream } = useLumioAction("obs:stop_stream");
 const { execute: emitEvent } = useLumioAction("events:emit");
 const { execute: updateLayer } = useLumioAction("overlay:update_layer");
-const { execute: spotifyPlay } = useLumioAction("spotify:play");
-const { execute: spotifyPause } = useLumioAction("spotify:pause");
-const { execute: spotifySkip } = useLumioAction("spotify:skip");
-const { execute: spotifySeek } = useLumioAction("spotify:seek");
-const { execute: spotifyVolume } = useLumioAction("spotify:volume");
-const { execute: spotifyShuffle } = useLumioAction("spotify:shuffle");
-const { execute: spotifyRepeat } = useLumioAction("spotify:repeat");
-const { execute: spotifyQueueAdd } = useLumioAction("spotify:queue_add");
 \`\`\`
 
 See \`server-functions.md\` for schema definition, storage scoping, and advanced patterns.
@@ -375,22 +372,26 @@ return <Text content={storage.text} />;
 
 ### Live events
 \`\`\`tsx
-// eventType is LumioEventType \u2014 autocomplete shows all 49 valid event strings
+// eventType is LumioEventType \u2014 autocomplete shows all 58 valid event strings
 const event = useLumioEvent("twitch:follower");
 // event updates automatically when a new follower event arrives
 \`\`\`
 
-**All 49 event types** (\`LumioEventType\`):
+**All 58 event types** (\`LumioEventType\`):
+
+Twitch (23): \`twitch:follower\`, \`twitch:subscribe\`, \`twitch:gift_sub\`, \`twitch:resub\`, \`twitch:cheer\`, \`twitch:raid\`, \`twitch:reward\`, \`twitch:hype_train\`, \`twitch:hype_train_end\`, \`twitch:poll\`, \`twitch:poll_end\`, \`twitch:prediction\`, \`twitch:prediction_lock\`, \`twitch:prediction_end\`, \`twitch:goal\`, \`twitch:goal_end\`, \`twitch:ad_break\`, \`twitch:ban\`, \`twitch:unban\`, \`twitch:stream_online\`, \`twitch:stream_offline\`, \`twitch:stream_update\`, \`twitch:chat\`
+
+YouTube (10): \`youtube:subscribe\`, \`youtube:member\`, \`youtube:superchat\`, \`youtube:supersticker\`, \`youtube:gift_membership\`, \`youtube:gift_membership_received\`, \`youtube:poll\`, \`youtube:stream_online\`, \`youtube:stream_offline\`, \`youtube:chat\`
 
-Twitch (22): \`twitch:follower\`, \`twitch:subscriber\`, \`twitch:subscribe\`, \`twitch:gift_sub\`, \`twitch:resub\`, \`twitch:cheer\`, \`twitch:raid\`, \`twitch:redemption\`, \`twitch:ban\`, \`twitch:unban\`, \`twitch:hype_train\`, \`twitch:poll\`, \`twitch:prediction\`, \`twitch:goal\`, \`twitch:ad_break\`, \`twitch:stream_update\`, \`twitch:chat\`
+Kick (11): \`kick:follower\`, \`kick:subscribe\`, \`kick:resub\`, \`kick:gift\`, \`kick:kicks\`, \`kick:reward\`, \`kick:reward_status\`, \`kick:stream_online\`, \`kick:stream_offline\`, \`kick:stream_update\`, \`kick:chat\`
 
-YouTube (7): \`youtube:subscriber\`, \`youtube:superchat\`, \`youtube:supersticker\`, \`youtube:gift_membership\`, \`youtube:gift_membership_received\`, \`youtube:poll\`, \`youtube:chat\`
+Spotify (12): \`spotify:track\`, \`spotify:play\`, \`spotify:pause\`, \`spotify:skip\`, \`spotify:volume\`, \`spotify:queue_add\`, \`spotify:device\`, \`spotify:playlist_add\`, \`spotify:playlist_remove\`, \`spotify:playlist_create\`, \`spotify:playlist_edit\`, \`spotify:playlist_delete\`
 
-Kick (6): \`kick:follower\`, \`kick:subscribe\`, \`kick:gift\`, \`kick:stream_online\`, \`kick:stream_offline\`, \`kick:chat\`
+StreamElements (1): \`streamelements:tip\`
 
-Trovo (3): \`trovo:subscribe\`, \`trovo:spell\`, \`trovo:chat\`
+Cross-platform chat (1, fires for every platform): \`chat:message\`
 
-Spotify (11): \`spotify:track\`, \`spotify:play\`, \`spotify:pause\`, \`spotify:skip\`, \`spotify:volume\`, \`spotify:queue_add\`, \`spotify:device\`, \`spotify:playlist_add\`, \`spotify:playlist_remove\`, \`spotify:playlist_create\`, \`spotify:playlist_delete\`
+Kick events carry canonical top-level fields (\`user_id\`, \`user_login\`, \`user_name\`, \`avatarUrl\`, \`is_anonymous\`) plus the original Kick payload. \`kick:kicks\` has \`kicks\` (amount, like Twitch \`bits\`) and \`message\`; \`kick:reward\` / \`kick:reward_status\` have \`status\`, \`user_input\` and \`reward { id, title, cost, prompt }\`; \`kick:resub\` has \`cumulative_months\`.
 
 ### Server queries
 \`\`\`tsx
@@ -421,7 +422,7 @@ const anim = useAnimation("slide-in", { duration: 300 });
 | \`EGRESS_BLOCKED\` | Fetch to undeclared host | Add host to \`egress.allowHosts\` in config |
 | \`STORAGE_QUOTA\` | Exceeded storage limit | Reduce data or request limit increase |
 | \`EDITOR_ONLY\` | Mutation called from layer/interactive | Remove \`editorOnly\` or restrict to editor |
-| \`SUPERVISOR_BLOCKED\` | Supervisor rejected a postMessage | Check message origin matches ext.lumio.vision |
+| \`SUPERVISOR_BLOCKED\` | Supervisor rejected a postMessage | Check message origin matches the extension's runtime origin (\`<label>.runtime.ext.lumio.vision\`) |
 | \`WORKER_CREATION_FAILED\` | Web Worker could not be created | Verify server functions bundle is valid JS |
 | \`STORAGE_DOM_EXCEPTION\` | localStorage/sessionStorage access | Use \`useExtensionStorage()\` instead (storage blocked) |
 
@@ -1063,46 +1064,41 @@ import { useLumioAction } from "@zaflun/lumio-sdk";
 
 // Send a chat message on the connected platform
 const { execute: sendChat, isLoading, error } = useLumioAction("chat:send");
-sendChat({ message: "Hello from the extension!" });
+sendChat({
+  platform: "twitch",
+  channel_id: "primary",
+  message: "Hello from the extension!"
+});
 
 // Switch OBS scene (requires OBS WebSocket integration)
 const { execute: setScene } = useLumioAction("obs:set_scene");
-setScene({ sceneName: "Main Scene" });
+setScene({ scene_name: "Main Scene" });
 
 // Emit a custom event into the Lumio event bus
 const { execute: emitEvent } = useLumioAction("events:emit");
-emitEvent({ type: "extension:custom", payload: { score: 42 } });
+emitEvent({ event_type: "extension:custom", data: { score: 42 } });
 
 // Update a specific layer in the overlay
 const { execute: updateLayer } = useLumioAction("overlay:update_layer");
-updateLayer({ layerId: "uuid", visible: true });
+updateLayer({
+  overlay_id: "overlay-uuid",
+  layer_id: "layer-uuid",
+  config: { visible: true }
+});
 \`\`\`
 
-**Available actions (21 total, \`action\` is \`LumioActionType\`):**
+**Available dispatched actions (\`action\` is \`LumioActionType\`):**
 
 | Action | Permission required | Description |
 |--------|--------------------|----|
 | \`chat:send\` | \`chat:send\` | Send chat message on connected platform |
 | \`chat:delete\` | \`chat:delete\` | Delete a chat message |
-| \`chat:ban\` | \`chat:ban\` | Ban a user from chat |
-| \`chat:unban\` | \`chat:ban\` | Unban a user from chat |
-| \`chat:timeout\` | \`chat:ban\` | Timeout a user from chat |
-| \`obs:set_scene\` | \`obs:control\` | Switch OBS scene |
-| \`obs:set_source_visible\` | \`obs:control\` | Show or hide an OBS source |
-| \`obs:start_stream\` | \`obs:control\` | Start OBS streaming |
-| \`obs:stop_stream\` | \`obs:control\` | Stop OBS streaming |
-| \`obs:start_recording\` | \`obs:control\` | Start OBS recording |
-| \`obs:stop_recording\` | \`obs:control\` | Stop OBS recording |
-| \`events:emit\` | \`events:write\` | Emit event into Lumio event bus |
-| \`overlay:update_layer\` | \`overlays:edit\` | Update overlay layer properties |
-| \`spotify:play\` | \`spotify:control\` | Resume Spotify playback |
-| \`spotify:pause\` | \`spotify:control\` | Pause Spotify playback |
-| \`spotify:skip\` | \`spotify:control\` | Skip to next track |
-| \`spotify:seek\` | \`spotify:control\` | Seek to position in current track |
-| \`spotify:volume\` | \`spotify:control\` | Set Spotify volume |
-| \`spotify:shuffle\` | \`spotify:control\` | Toggle shuffle mode |
-| \`spotify:repeat\` | \`spotify:control\` | Set repeat mode |
-| \`spotify:queue_add\` | \`spotify:control\` | Add track to Spotify queue |
+| \`obs:set_scene\` | \`obs:set_scene\` | Switch OBS scene |
+| \`obs:set_source_visible\` | \`obs:set_source_visible\` | Show or hide an OBS source |
+| \`obs:start_stream\` | \`obs:start_stream\` | Start OBS streaming |
+| \`obs:stop_stream\` | \`obs:stop_stream\` | Stop OBS streaming |
+| \`events:emit\` | \`events:emit\` | Emit event into Lumio event bus |
+| \`overlay:update_layer\` | \`overlay:update_layer\` | Update overlay layer properties |
 
 Actions are proxied through the Lumio API \u2014 the extension never accesses OAuth tokens or platform credentials directly.
 
@@ -1340,7 +1336,7 @@ The extension must declare the matching permission in \`lumio.config.json\`. For
 | \`chat:delete\` | Delete chat messages | Enhanced |
 | \`chat:ban\` | Ban, unban, and timeout users | Enhanced |
 | \`events:read\` | Subscribe to platform events | Standard |
-| \`events:write\` | Emit custom events | Standard |
+| \`events:emit\` | Emit custom events | Standard |
 `;
 
 // src/content/cli-workflows.ts
@@ -1503,19 +1499,29 @@ Features:
 
 ## lumio build
 
-Bundle the extension as standalone HTML and create source archive.
+Bundle the extension and create source archive.
 
 \`\`\`bash
 lumio build
 
-# Output:
-# Building extension...
-# Bundling editor.tsx -> dist/editor.html (42 KB)
-# Bundling layer.tsx -> dist/layer.html (38 KB)
-# Creating source archive -> dist/source.tar.gz
-# Build complete!
+# Output for widgets:
+#   Built: dist/editor.js
+#   Built: dist/layer.js
+#   Compiled: dist/styles.css (if Tailwind detected)
+#   Archive: dist/source.tar.gz
+#
+# Output for bot modules (server: true):
+#   Bot module \u2014 no UI targets to bundle.
+#   Built: dist/server.js
+#   Archive: dist/source.tar.gz
 \`\`\`
 
+Build steps:
+1. UI targets (\`editor\`, \`layer\`, \`interactive\`, \`designer\`) \u2014 esbuild IIFE bundles
+2. Server handler (\`server: true\`) \u2014 compiles \`server/handler.ts\` to \`dist/server.js\` (ESM)
+3. CSS \u2014 Tailwind v4 auto-detected and compiled, or plain CSS copied
+4. Source archive \u2014 \`dist/source.tar.gz\`
+
 Warns if \`CHANGELOG.md\` is missing.
 
 ## lumio deploy
@@ -1539,6 +1545,11 @@ lumio deploy --breaking -v 2.0.0
 lumio deploy --draft
 \`\`\`
 
+Pre-flight checks before upload:
+- Sound files validated (format, existence in \`dist/sounds/\`, per-file size against limit)
+- Sound count, per-file size, and total storage checked against resolved limits from API
+- Manifest validated against schema
+
 After deploy:
 1. Version status = \`draft\`
 2. Submit for review via dashboard (\`/dashboard/extensions/{slug}/submit\`)
@@ -1707,7 +1718,7 @@ AuthContext::ExtensionToken {
 ### Token Lifecycle
 
 1. User opens extension in dashboard/overlay \u2014 Lumio server generates \`lm_ext_*\` token
-2. Token passed to Extension Runtime iframe: \`ext.lumio.vision/ext/{slug}/layer?token=lm_ext_xxx&install_id=uuid\` where \`slug\` includes the \`short_id\` prefix (e.g. \`k8f2x-my-extension\`); the store URL is \`/store/k8f2x-my-extension\`
+2. Token handed to the extension inside the sandbox; the Extension Runtime iframe runs on the extension's own origin \`<label>.runtime.ext.lumio.vision\` (\`<label>\` = extension UUID as 32 lowercase hex). The extension \`slug\` includes the \`short_id\` prefix (e.g. \`k8f2x-my-extension\`); the store URL is \`/store/k8f2x-my-extension\`
 3. SDK uses token for all API calls (server functions, storage, events)
 4. Token auto-refreshes via postMessage every 12 minutes (before 15-min expiry) \u2014 the Supervisor mediates the refresh
 5. On page reload, a new token is generated
@@ -1784,11 +1795,11 @@ Extensions run inside a 3-layer iframe sandbox. Understanding the layers is impo
 
 \`\`\`
 Host (lumio.vision / browser source)
-  \u2514\u2500\u2500 Supervisor iframe (supervisor.extension.lumio.vision)
+  \u2514\u2500\u2500 Supervisor iframe (supervisor.ext.lumio.vision)
         Purpose: validates postMessage traffic, enforces egress allowlist,
                  mediates token refresh, proxies LumioComponentNode[] to host
-        \u2514\u2500\u2500 Extension Runtime iframe (ext.lumio.vision)
-              Purpose: runs extension code on a separate origin
+        \u2514\u2500\u2500 Extension Runtime iframe (<label>.runtime.ext.lumio.vision)
+              Purpose: runs extension code on its own origin (one per extension)
               Storage: localStorage/sessionStorage BLOCKED (cross-origin isolation)
               \u2514\u2500\u2500 Web Worker
                     Purpose: V8 isolate for server function execution
@@ -1801,8 +1812,9 @@ Host (lumio.vision / browser source)
 - Mediates \`lm_ext_*\` token refresh (12 min interval, before 15 min expiry)
 - Forwards serialized \`LumioComponentNode[]\` to the Host renderer
 
-**Extension Runtime (ext.lumio.vision) origin isolation:**
+**Extension Runtime (<label>.runtime.ext.lumio.vision) origin isolation:**
 - Runs on a separate origin from the Host \u2014 this prevents direct DOM access and localStorage sharing
+- Every extension gets its own origin (\`<label>\` = extension UUID as 32 lowercase hex), so two extensions never share browser state
 - \`localStorage\` and \`sessionStorage\` throw \`DOMException: Access is denied\` \u2014 use \`useExtensionStorage()\` instead
 - \`document.cookie\` is unavailable
 - Cross-origin postMessage to the Host goes through the Supervisor
@@ -2074,7 +2086,7 @@ For beta testing before public launch:
 | Large inline images | Use URL-based images via \`Image\` component |
 | Missing \`Lumio.render()\` | Must be called within 10s of page load |
 | Hardcoded strings | Use \`config_schema\` fields for user-customizable text |
-| Using localStorage directly | Use \`useExtensionStorage()\` (localStorage blocked at ext.lumio.vision) |
+| Using localStorage directly | Use \`useExtensionStorage()\` (localStorage blocked on the Extension Runtime origin) |
 | Raw CSS \`@keyframes\` animations | Use \`useAnimation()\` + \`<Animated>\` SDK presets |
 
 ## Bot Module Security
@@ -2218,7 +2230,7 @@ var troubleshootingContent = `# Troubleshooting
 | \`BUNDLE_TOO_LARGE\` | Bundle exceeds size limit | Built bundle exceeds \`max_bundle_size_mb\` | Reduce bundle size or request limit increase |
 | \`SUPERVISOR_BLOCKED\` | Supervisor rejected postMessage | Message origin or schema invalid | Ensure you are in the correct iframe layer; do not post to Host directly |
 | \`WORKER_CREATION_FAILED\` | Web Worker could not start | Server functions bundle is invalid or too large | Check for syntax errors in server functions; run \`lumio build\` locally |
-| \`STORAGE_DOM_EXCEPTION\` | localStorage/sessionStorage access attempt | Extension Runtime (ext.lumio.vision) blocks storage APIs | Replace \`localStorage.setItem\` with \`useExtensionStorage()\` |
+| \`STORAGE_DOM_EXCEPTION\` | localStorage/sessionStorage access attempt | Extension Runtime (<label>.runtime.ext.lumio.vision) blocks storage APIs | Replace \`localStorage.setItem\` with \`useExtensionStorage()\` |
 | \`SLUG_FORMAT_INVALID\` | Slug does not match short-ID format | Manually edited slug in \`lumio.config.json\` | Use auto-generated slug (\`k8f2x-my-extension\` format) or run \`lumio init\` |
 
 ## Common Issues
@@ -2256,7 +2268,7 @@ The SDK auto-refreshes \`lm_ext_*\` tokens via postMessage. The Supervisor media
 ### Supervisor blocked messages (\`SUPERVISOR_BLOCKED\`)
 The Supervisor validates all postMessage traffic between Extension Runtime and Host. If you see this error:
 1. Do not post messages directly from extension code to \`window.parent.parent\` (Host) \u2014 always use SDK hooks
-2. Verify the extension iframe is loaded inside \`supervisor.extension.lumio.vision\`, not directly in the Host
+2. Verify the extension iframe is loaded inside \`supervisor.ext.lumio.vision\`, not directly in the Host
 3. Check that the message schema matches the \`@zaflun/lumio-protocol\` wire format (SDK handles this automatically)
 
 ### Worker creation failures (\`WORKER_CREATION_FAILED\`)
@@ -2266,7 +2278,7 @@ The V8 isolate Web Worker for server functions failed to start:
 3. Check \`lumio logs\` for the underlying JS error from the Worker initializer
 
 ### Storage DOMException errors (\`STORAGE_DOM_EXCEPTION\`)
-\`localStorage\` and \`sessionStorage\` are blocked on the Extension Runtime origin (\`ext.lumio.vision\`):
+\`localStorage\` and \`sessionStorage\` are blocked on the Extension Runtime origin (\`<label>.runtime.ext.lumio.vision\`):
 1. Replace all \`localStorage.setItem\` / \`localStorage.getItem\` calls with \`useExtensionStorage()\`
 2. Replace all \`sessionStorage\` usage with \`useVisionState()\` for transient values
 3. For server-side persistence, use \`ctx.db\` in server functions

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   ROOT_FILES,
   SKILL_FILES,
   installSkillFiles
-} from "./chunk-QXQNAYHN.js";
+} from "./chunk-TKNV5K6F.js";
 export {
   ROOT_FILES,
   SKILL_FILES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaflun/lumio-agent-skill",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "AI agent skill files for building Lumio Extensions",
   "type": "module",
   "main": "dist/index.js",
@@ -27,10 +27,10 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^26.1.2",
     "tsup": "^8.4.0",
-    "typescript": "^5.8.3",
-    "vitest": "^3.1.4"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   },
   "repository": {
     "type": "git",