@zaflun/lumio-agent-skill 0.4.0 → 0.5.0

package/dist/bin/lumio-skills.js

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

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

@@ -77,7 +77,8 @@ All three surfaces share storage via \`useExtensionStorage()\` \u2014 changes in
   "visibility": "public",
   "pricing": { "type": "free" },
   "config_schema": [
-    { "key": "title", "type": "string", "label": "Widget Title", "default_value": "My Widget", "required": true },
+    { "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" },
     { "key": "showBorder", "type": "boolean", "label": "Show Border", "default_value": true, "required": false }
   ]
 }
@@ -136,11 +137,11 @@ lumio deploy
 
 ## Components
 
-15 SDK components (all accept \`style: VisionStyle\`):
+17 SDK components (all accept \`style: VisionStyle\`):
 
 **Layout:** \`Box\`, \`VStack\`, \`HStack\`, \`CompactView\`, \`List\`
-**Display:** \`Text\` (variant: heading/muted/default), \`Image\` (objectFit), \`Animated\`
-**Input:** \`Button\` (variant: default/destructive), \`Toggle\`, \`TextField\`, \`TextArea\`, \`NumberField\`, \`Dropdown\`, \`Slider\`
+**Display:** \`Text\` (variant: heading/muted/default), \`Image\` (objectFit), \`Animated\`, \`IconDisplay\`
+**Input:** \`Button\` (variant: default/destructive), \`Toggle\`, \`TextField\`, \`TextArea\`, \`NumberField\`, \`Dropdown\`, \`Slider\`, \`IconPicker\`
 
 **VisionStyle** is a typed CSS subset (allowed: flexbox, grid, \`position: relative\` / \`absolute\`, sizing, spacing, colors, border, typography, transitions; blocked: \`fixed\`, \`sticky\`, CSS expressions).
 
@@ -150,7 +151,7 @@ See \`components.md\` for full props and examples.
 
 ## Hooks
 
-11 SDK hooks:
+12 SDK hooks:
 
 | Hook | Returns | Purpose |
 |------|---------|---------|
@@ -165,6 +166,7 @@ See \`components.md\` for full props and examples.
 | \`useQuery(fn, params?)\` | \`{ data, isLoading, error, refetch }\` | Call server query |
 | \`useMutation(fn)\` | \`{ mutate, mutateAsync, data, isLoading, error }\` | Call server mutation/action |
 | \`useAnimation(preset, options?)\` | \`animationProps\` | SDK animation presets for \`Animated\` component |
+| \`useIconPicker(options?)\` | \`{ isOpen, selected, open, close, select, clear, sources }\` | Headless state for custom icon picker UIs |
 
 **Important:** \`setStorage\` must always spread: \`setStorage({ ...storage, key: value })\`
 
@@ -429,7 +431,59 @@ See \`troubleshooting.md\` for the full error reference.
 // src/content/components.ts
 var componentsContent = `# Lumio SDK Components
 
-All 15 components available in \`@zaflun/lumio-sdk\`. Every component accepts an optional \`style: VisionStyle\` prop.
+All 31 components available in \`@zaflun/lumio-sdk\`. Every component accepts an optional \`style: VisionStyle\` prop.
+
+## Editor Components
+
+14 components for building settings UIs in \`editor.tsx\` and \`designer.tsx\`. They serialize via the Reconciler and render as \`@lumio/ui\` components on the host \u2014 matching the dashboard design system.
+
+\`\`\`tsx
+import {
+  EditorInput, EditorTextarea, EditorSelect, EditorCheckbox,
+  EditorSlider, EditorColorPicker, EditorGroup, EditorLabel,
+  EditorDivider, EditorInfo, EditorFontRow, EditorButton,
+  EditorFontPicker, EditorChannelRow, useEditorAction,
+} from "@zaflun/lumio-sdk";
+
+// Text/number input with label, placeholder, min/max, unit
+<EditorInput label="Font Size" type="number" value="16" onChange={setSize} min={8} max={200} unit="px" />
+
+// Select dropdown
+<EditorSelect label="Theme" value={theme} onChange={setTheme} options={[{ value: "dark", label: "Dark" }]} />
+
+// Checkbox toggle
+<EditorCheckbox label="Show Badges" checked={show} onChange={setShow} />
+
+// Slider with range
+<EditorSlider label="Opacity" value={100} onChange={setOpacity} min={0} max={100} unit="%" />
+
+// Color picker (HSV canvas + hex input)
+<EditorColorPicker label="Background" value="#000000" onChange={setColor} />
+
+// Compact font row: [B] [size px] [color]
+<EditorFontRow bold={isBold} onBoldChange={setBold} fontSize={16} onFontSizeChange={setSize} fontColor="#fff" onFontColorChange={setColor} />
+
+// Full-width button (primary/default/destructive)
+<EditorButton label="Open Designer" variant="primary" onClick={openDesigner} />
+
+// Collapsible section
+<EditorGroup label="Advanced"><EditorCheckbox ... /></EditorGroup>
+
+// Font picker with weight dropdown (opens NavigationStack page)
+<EditorFontPicker label="Font Family" value="Lexend" onChange={setFont} weight="400" onWeightChange={setWeight} />
+
+// Channel row: platform + name + color + delete in one line
+<EditorChannelRow platform="twitch" onPlatformChange={setPlatform} channel="username" onChannelChange={setChannel} color="#9146FF" onColorChange={setColor} onRemove={remove} />
+
+// Dispatch UI actions (e.g. open designer)
+const { dispatch } = useEditorAction();
+<EditorButton label="Open Designer" variant="primary" onClick={() => dispatch("open-designer")} />
+
+// Section label, divider, info text
+<EditorLabel text="Settings" />
+<EditorDivider />
+<EditorInfo content="Configure your widget here." />
+\`\`\`
 
 > **Note:** There is no direct DOM access from extension code. The custom React reconciler serializes component trees to \`LumioComponentNode[]\` via postMessage \u2014 you must use SDK components exclusively.
 
@@ -750,6 +804,69 @@ const exitAnim = useAnimation("fade-out", { duration: 200 });
 - Keep animation durations short on the layer surface (< 500ms) to avoid frame drops
 - Avoid animating layout-affecting properties (\`width\`, \`height\`) on the layer; prefer \`opacity\` and \`transform\`
 
+## Picker Components
+
+### IconPicker
+
+Universal icon/emoji/emote picker with 4 tabs: Lucide icons (1960), Unicode emojis (1584), platform emotes (via API), and file upload. **Editor-only** \u2014 use \`IconDisplay\` to render the selected icon on the layer surface.
+
+\`\`\`tsx
+import { IconPicker, IconDisplay } from "@zaflun/lumio-sdk";
+import type { IconValue } from "@zaflun/lumio-sdk";
+
+// In editor.tsx \u2014 let the user pick an icon
+const [storage, setStorage] = useExtensionStorage();
+
+<IconPicker
+  value={storage.icon ?? null}
+  onChange={(icon) => setStorage({ ...storage, icon })}
+  sources={["lucide", "emoji", "emote", "upload"]}
+  size="md"
+  placeholder="Choose an icon..."
+/>
+
+// In layer.tsx \u2014 render the selected icon
+<IconDisplay icon={storage.icon ?? null} size={32} />
+\`\`\`
+
+**IconPickerProps:**
+- \`value: IconValue | null\` \u2014 currently selected icon
+- \`onChange: (icon: IconValue | null) => void\` \u2014 selection callback
+- \`sources?: IconSource[]\` \u2014 tabs to show (default: all four: \`["lucide", "emoji", "emote", "upload"]\`)
+- \`size?: "sm" | "md" | "lg"\` \u2014 picker trigger button size
+- \`placeholder?: string\` \u2014 placeholder text when no icon selected
+
+**IconDisplayProps:**
+- \`icon: IconValue | null\` \u2014 icon to render (null renders nothing)
+- \`size?: number\` \u2014 pixel size
+- \`className?: string\`
+
+**IconValue type:**
+\`\`\`typescript
+type IconSource = "lucide" | "emoji" | "emote" | "upload";
+
+interface IconValue {
+  type: IconSource;  // which tab/source the icon came from
+  value: string;     // icon name (lucide), Unicode char (emoji), CDN URL (emote), upload URL (upload)
+  label?: string;    // human-readable label
+  platform?: string; // platform identifier for emotes (e.g. "twitch", "7tv")
+}
+\`\`\`
+
+**\`useIconPicker()\` hook** \u2014 headless state management for custom picker UIs:
+\`\`\`tsx
+import { useIconPicker } from "@zaflun/lumio-sdk";
+
+const { isOpen, selected, open, close, select, clear, sources } = useIconPicker({
+  sources: ["lucide", "emoji"],
+  onSelect: (icon) => console.log("Selected:", icon),
+});
+\`\`\`
+
+Returns: \`{ isOpen, selected, open, close, select, clear, sources }\`
+
+**Upload tab** requires the extension to declare \`egress.allowHosts\` including the Lumio API. Uploaded files are stored per-extension with quota tracking via the \`extension_uploads\` table.
+
 ## VisionStyle
 
 Typed CSS subset accepted by all components. Sanitized by the host \u2014 only safe properties are allowed.
@@ -989,6 +1106,88 @@ updateLayer({ layerId: "uuid", visible: true });
 
 Actions are proxied through the Lumio API \u2014 the extension never accesses OAuth tokens or platform credentials directly.
 
+## Automation Node Handlers
+
+Extensions with category \`automation_node\` export a single handler in \`server/handler.ts\`. The handler type depends on the \`node_type\` declared in \`lumio.config.json\`.
+
+### \`defineAutomationAction(handler)\`
+
+Action nodes execute when triggered by an upstream node in the automation workflow. They receive input data from the previous node and can perform side effects (HTTP calls, DB writes).
+
+\`\`\`typescript
+import { defineAutomationAction } from "@zaflun/lumio-sdk/server";
+
+export default defineAutomationAction({
+  handler: async (ctx) => {
+    const webhookUrl = ctx.nodeConfig.webhook_url;
+    const res = await ctx.fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(ctx.inputData),
+    });
+    return { status: res.status, body: await res.json() };
+  },
+});
+\`\`\`
+
+### \`defineAutomationTrigger({ onWebhook?, onPoll? })\`
+
+Trigger nodes start automation workflows. They support two modes: webhook (receives external HTTP calls) and poll (periodic checks for new data).
+
+\`\`\`typescript
+import { defineAutomationTrigger } from "@zaflun/lumio-sdk/server";
+
+export default defineAutomationTrigger({
+  onWebhook: async (ctx, request) => {
+    const body = await request.json();
+    if (body.event === "order.created") {
+      return { trigger: true, outputData: { orderId: body.id, total: body.total } };
+    }
+    return { trigger: false };
+  },
+  onPoll: async (ctx) => {
+    const lastCheck = await ctx.cache.get("last_check") ?? "1970-01-01T00:00:00Z";
+    const res = await ctx.fetch(
+      \`https://api.example.com/events?since=\${lastCheck}\`,
+      { headers: { "Authorization": \`Bearer \${ctx.secrets.get("API_KEY")}\` } }
+    );
+    const events = await res.json();
+    await ctx.cache.set("last_check", new Date().toISOString());
+    return events.map((e: any) => ({ trigger: true, outputData: e }));
+  },
+});
+\`\`\`
+
+### \`defineAutomationLogic(handler)\`
+
+Logic nodes evaluate conditions and route the workflow to different branches. They return a branch key that determines which downstream path executes.
+
+\`\`\`typescript
+import { defineAutomationLogic } from "@zaflun/lumio-sdk/server";
+
+export default defineAutomationLogic({
+  handler: async (ctx) => {
+    const amount = ctx.inputData.total;
+    if (amount >= 100) return { branch: "high_value" };
+    if (amount >= 25) return { branch: "medium_value" };
+    return { branch: "low_value" };
+  },
+});
+\`\`\`
+
+### Automation Handler Context (\`ctx\`)
+
+| Property | Available in | Description |
+|----------|-------------|-------------|
+| \`ctx.nodeConfig\` | All | Node configuration from the user's config panel |
+| \`ctx.inputData\` | Action, Logic | Data from the upstream node |
+| \`ctx.fetch(url, options?)\` | All | HTTP request (egress allowlist enforced) |
+| \`ctx.cache.get(key)\` / \`ctx.cache.set(key, value, ttl?)\` | All | Per-installation KV cache (Redis, 1h default TTL) |
+| \`ctx.secrets.get(key)\` | All | Server-side secret |
+| \`ctx.db\` | All | Extension DB schema access |
+| \`ctx.auth\` | All | \`{ accountId }\` \u2014 account identity |
+| \`ctx.defer()\` | Action | Mark execution as async (returns 202, completes in background) |
+
 ## Bot Module Handlers
 
 Extensions with category \`bot_module\` export handler wrappers that register triggers. Each wrapper defines when the handler fires and what context it receives.
@@ -1087,6 +1286,37 @@ export const toxicFilter = moderate({
 });
 \`\`\`
 
+### \`defineModerate(handler)\`
+
+Convenience wrapper for system-style moderation handlers. The handler receives a unified context with the chat message and returns a moderation action.
+
+\`\`\`typescript
+import { defineModerate } from "@zaflun/lumio-sdk/server";
+
+export default defineModerate(async (ctx) => {
+  if (ctx.message.text.includes("spam")) {
+    return { action: "delete" };
+  }
+  return { action: "allow" };
+});
+\`\`\`
+
+### \`defineTimer(handler)\`
+
+Convenience wrapper for timer-based handlers (e.g., timed messages). Fires on a recurring interval configured in the extension's install config.
+
+\`\`\`typescript
+import { defineTimer } from "@zaflun/lumio-sdk/server";
+
+export default defineTimer(async (ctx) => {
+  const messages = (ctx.installConfig.messages as string || "").split("\\n").filter(Boolean);
+  if (messages.length === 0) return null;
+  const idx = parseInt(await ctx.cache.get("idx") || "0", 10);
+  await ctx.cache.set("idx", String((idx + 1) % messages.length));
+  return { reply: messages[idx] };
+});
+\`\`\`
+
 ### Handler Return Actions
 
 All bot module handlers return an action object:
@@ -1170,15 +1400,14 @@ lumio init my-widget
 # ? Category: widget
 # ? Targets: editor, layer
 # ? Server functions: yes
-# ? Template: Widget (editor + layer + storage)
+# ? How should the editor UI be built? config_schema only / editor.tsx only / Both
 # ? Owner: My Stream (personal) / Awesome Team  <- team selection if applicable
 #
 # Creating extension on Lumio...
 # Extension-ID: 88b2478a-39c7-468e-bebd-14e52fd97ac0
 # Slug: k8f2x-my-widget
 #
-# Writing lumio.config.json...
-# Writing src/editor.tsx...
+# Writing lumio.config.json (with config_schema)...
 # Writing src/layer.tsx...
 # Writing server/schema.ts...
 # Writing server/functions.ts...
@@ -1186,6 +1415,32 @@ lumio init my-widget
 # Done! Run \`lumio dev\` to start developing.
 \`\`\`
 
+### Automation Node Example
+
+\`\`\`bash
+lumio init my-webhook-action
+
+# Interactive prompts:
+# ? Extension name: My Webhook Action
+# ? Description: Posts data to a webhook
+# ? Category: automation_node
+# ? Node type: action
+# ? Server functions: yes (required for automation nodes)
+# ? Owner: My Stream (personal) / Awesome Team
+#
+# Creating extension on Lumio...
+# Extension-ID: a1b2c3d4-...
+# Slug: x9k1z-my-webhook-action
+#
+# Writing lumio.config.json...
+# Writing src/editor.tsx...
+# Writing server/handler.ts...
+#
+# Done! Run \`lumio dev\` to start developing.
+\`\`\`
+
+Automation nodes always generate \`server/handler.ts\` (not \`server/functions.ts\`) and \`src/editor.tsx\` for the config panel. The \`node_type\` can be \`action\`, \`trigger\`, or \`logic\`.
+
 ### Templates
 
 | Template | Targets | Server | Description |
@@ -1195,6 +1450,9 @@ lumio init my-widget
 | Full-Stack | editor + layer | Yes | Complete extension with server functions |
 | Interactive Game | editor + layer + interactive | Yes | Viewer interaction game |
 | Bot Module | server-only | Yes | Chat command module |
+| Automation Action | server + editor | Yes | Automation workflow action node |
+| Automation Trigger | server + editor | Yes | Automation workflow trigger node |
+| Automation Logic | server + editor | Yes | Automation workflow logic/branching node |
 | Integration | server | Yes | External API integration |
 | Theme | editor | No | Style variables only |
 
@@ -1215,11 +1473,33 @@ lumio dev
 # Press 'q' to quit.
 \`\`\`
 
+### Automation Node Development
+
+For automation node extensions, the dev server auto-detects \`category: "automation_node"\` and launches the automation simulator:
+
+\`\`\`bash
+lumio dev
+# or explicitly:
+lumio dev --automation-node
+
+# Output:
+# Lumio Dev Server running at http://localhost:5173
+# Config Panel: http://localhost:5173/editor
+#
+# Automation Simulator ready. Commands:
+#   /execute [JSON]     \u2014 Run the action handler with input data
+#   /webhook [JSON]     \u2014 Simulate an incoming webhook (trigger nodes)
+#   /poll               \u2014 Trigger a poll cycle (trigger nodes)
+#   /config [JSON]      \u2014 Update node config
+#   /quit               \u2014 Stop the dev server
+\`\`\`
+
 Features:
 - Hot reload on file changes
 - Mock event system (simulated chat, follows, subs)
 - Sandbox environment matching production constraints
 - Server function execution with local DB
+- Automation simulator with /execute, /webhook, /poll, /config commands
 
 ## lumio build
 
@@ -1697,22 +1977,46 @@ Lumio.render(<Overlay />, { target: "layer" });
 
 ## Config Schema
 
-Use \`config_schema\` in \`lumio.config.json\` for user-customizable settings. The Lumio dashboard renders these as a form in the Widget Gallery install flow \u2014 the user fills them in without needing to open the editor surface.
+Use \`config_schema\` in \`lumio.config.json\` for user-customizable settings. The widget editor auto-generates form fields from the schema \u2014 no custom \`editor.tsx\` needed for simple settings. For advanced UIs, use \`editor.tsx\` alongside (or instead of) config_schema.
+
+**Three valid combos:**
+- **config_schema only** \u2014 auto-generated editor form, \`targets: ["layer"]\`
+- **editor.tsx only** \u2014 fully custom React editor UI, \`targets: ["layer", "editor"]\`
+- **Both** \u2014 schema fields render first, editor.tsx renders below for advanced controls
+
+**Supported field types:** \`string\`, \`number\`, \`boolean\`, \`color\`, \`select\`, \`textarea\`, \`slider\`, \`font\`, \`icon\`, \`image\`, \`sound\`, \`multiselect\`, \`group\`, \`divider\`, \`info\`, \`channel\`, \`designer\`, \`presets\`
 
 \`\`\`json
 {
   "config_schema": [
-    { "key": "title", "type": "string", "label": "Widget Title", "default_value": "My Widget", "required": true },
-    { "key": "maxItems", "type": "number", "label": "Max Items", "default_value": 10, "required": false },
+    { "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" },
+    { "key": "volume", "type": "slider", "label": "Volume", "default_value": 50, "required": false, "min": 0, "max": 100, "unit": "%" },
+    { "key": "theme", "type": "select", "label": "Color Theme", "options": ["dark", "light"], "default_value": "dark", "required": false },
+    { "key": "primaryColor", "type": "color", "label": "Primary Color", "default_value": "#43F7CD", "required": false },
     { "key": "showBorder", "type": "boolean", "label": "Show Border", "default_value": true, "required": false },
+    { "key": "targetDate", "type": "string", "label": "Target Date", "default_value": "", "required": false, "visible_when": { "key": "mode", "equals": "countdown" } },
     {
-      "key": "theme",
-      "type": "select",
-      "label": "Color Theme",
-      "options": ["dark", "light"],
-      "default_value": "dark",
-      "required": false
-    }
+      "key": "twitch_events", "type": "group", "label": "Twitch Events", "required": false, "collapsed": true,
+      "fields": [
+        { "key": "includeFollowers", "type": "boolean", "label": "Followers", "default_value": true, "required": false },
+        { "key": "includeSubs", "type": "boolean", "label": "Subscriptions", "default_value": true, "required": false }
+      ]
+    },
+    { "key": "separator", "type": "divider", "label": "", "required": false },
+    { "key": "help_text", "type": "info", "label": "", "required": false, "content": "Configure the events you want to display." }
+  ]
+}
+\`\`\`
+
+**Designer Schema:** Extensions can define a \`designer_schema\` alongside \`config_schema\` for a fullpage visual design editor. The designer opens as a fullpage overlay with the schema fields on the left and a live preview on the right. Designer values are stored under \`config.design\`.
+
+\`\`\`json
+{
+  "designer_schema": [
+    { "key": "bubbleColor", "type": "color", "label": "Chat Bubble Color", "default_value": "#9146FF", "required": false },
+    { "key": "nameFont", "type": "font", "label": "Username Font", "default_value": "Inter", "required": false },
+    { "key": "badgeSize", "type": "slider", "label": "Badge Size", "default_value": 18, "required": false, "min": 12, "max": 32, "unit": "px" }
   ]
 }
 \`\`\`
@@ -1722,7 +2026,7 @@ Read config values via \`useLumioConfig()\`:
 \`\`\`tsx
 const [config] = useLumioConfig();
 const title = config.title ?? "My Widget";
-const maxItems = config.maxItems ?? 10;
+const fontSize = config.fontSize ?? 16;
 \`\`\`
 
 **When to use config_schema vs storage:**

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaflun/lumio-agent-skill",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "AI agent skill files for building Lumio Extensions",
   "type": "module",
   "main": "dist/index.js",