@zaflun/lumio-sdk 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zaflun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @zaflun/lumio-sdk
+
+The official SDK for building [Lumio](https://lumio.vision) extensions — widgets, overlays, bot modules, integrations, and themes for live streamers.
+
+## Installation
+
+```bash
+npm install @zaflun/lumio-sdk react react-dom
+```
+
+## Quick Start
+
+```tsx
+import { Lumio, CompactView, Text, Toggle, useExtensionStorage } from "@zaflun/lumio-sdk";
+
+function MyWidget() {
+  const [storage, setStorage] = useExtensionStorage("settings", { visible: true });
+
+  return (
+    <CompactView title="My Widget">
+      <Toggle
+        label="Visible"
+        checked={storage.visible}
+        onChange={(checked) => setStorage({ ...storage, visible: checked })}
+      />
+      <Text content={storage.visible ? "Hello World!" : ""} />
+    </CompactView>
+  );
+}
+
+Lumio.render(<MyWidget />, { target: "editor" });
+```
+
+## What's included
+
+### 14 UI Components
+
+**Layout:** `Box`, `VStack`, `HStack`, `CompactView`, `List`
+**Display:** `Text`, `Image`
+**Input:** `Button`, `Toggle`, `TextField`, `TextArea`, `NumberField`, `Dropdown`, `Slider`
+**Animation:** `Animated` (with 22 built-in presets)
+
+### 10 Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useExtensionStorage()` | Persistent key-value storage synced across surfaces |
+| `useVisionState()` | Per-key state with real-time sync |
+| `useExtensionContext()` | Extension metadata (ID, target, overlay) |
+| `useLumioEvent()` | Subscribe to platform events (49 event types) |
+| `useLumioConfig()` | Read/write extension config |
+| `useLumioTheme()` | Active overlay/widget theme (colors, fonts) |
+| `useLumioIdentity()` | Current user/account context |
+| `useLumioAction()` | Trigger platform actions (21 action types) |
+| `useQuery()` | Call server query functions |
+| `useMutation()` | Call server mutation functions |
+
+### Server Functions (`@zaflun/lumio-sdk/server`)
+
+```typescript
+import { defineSchema, defineTable, v, queryRows, insertRow } from "@zaflun/lumio-sdk/server";
+
+export default defineSchema({
+  scores: defineTable({
+    player: v.string(),
+    points: v.number(),
+  }).storage("instance"),
+});
+
+export const getScores = queryRows("scores");
+export const addScore = insertRow("scores", { player: arg("player"), points: 0 });
+```
+
+### Animation
+
+```typescript
+import { Animated, useAnimation, defineKeyframes } from "@zaflun/lumio-sdk";
+
+// Built-in presets: fadeIn, slideUp, zoomIn, bounce, pulse, ...
+<Animated in="fadeIn" duration={500}>
+  <Text content="Hello!" />
+</Animated>
+```
+
+### Custom Fonts
+
+```typescript
+import { localFont } from "@zaflun/lumio-sdk";
+
+const scoreFont = localFont({
+  src: "./fonts/Orbitron-Bold.woff2",
+  family: "Orbitron",
+  fallback: ["sans-serif"],
+});
+```
+
+## Three Surfaces
+
+| Surface | File | Where it renders |
+|---------|------|-----------------|
+| `editor` | `src/editor.tsx` | Dashboard sidebar panel |
+| `layer` | `src/layer.tsx` | OBS overlay (transparent) |
+| `interactive` | `src/interactive.tsx` | Audience page |
+
+All surfaces share storage — changes in the editor propagate to the overlay in real time.
+
+## Security
+
+Extensions run in a sandboxed Web Worker with zero DOM access. A custom React reconciler serializes the component tree to JSON, which the host renders. Extension code cannot access cookies, JWT tokens, localStorage, or any host resources.
+
+## Documentation
+
+- [Getting Started](https://developers.lumio.vision/getting-started/quickstart)
+- [Component Reference](https://developers.lumio.vision/sdk/hooks)
+- [Server Functions](https://developers.lumio.vision/server-functions/overview)
+- [Full Docs](https://developers.lumio.vision)
+
+## License
+
+MIT © [zaflun](https://withzaflun.com)

package/dist/index.d.ts

@@ -0,0 +1,489 @@
+import React, { CSSProperties } from 'react';
+import { LumioEventType, LumioActionType } from '@zaflun/lumio-protocol';
+
+interface RenderOptions {
+    target: "editor" | "layer" | "interactive";
+}
+declare const Lumio: {
+    render(element: React.ReactElement, options: RenderOptions): void;
+};
+
+type NotificationHandler = (params: unknown) => void;
+type RequestHandler = (params: unknown) => Promise<unknown>;
+interface WorkerBridgeOptions {
+    requestTimeout?: number;
+}
+declare class WorkerBridge {
+    private notificationHandlers;
+    private requestHandlers;
+    private pendingRequests;
+    private requestCounter;
+    private requestTimeout;
+    private messageListener;
+    private destroyed;
+    constructor(options?: WorkerBridgeOptions);
+    notify(method: string, params?: unknown): void;
+    request(method: string, params?: unknown): Promise<unknown>;
+    onNotification(method: string, handler: NotificationHandler): () => void;
+    onRequest(method: string, handler: RequestHandler): void;
+    destroy(): void;
+    private handleMessage;
+}
+
+type VisionStyle = Pick<CSSProperties, "display" | "flexDirection" | "alignItems" | "justifyContent" | "gap" | "padding" | "paddingTop" | "paddingRight" | "paddingBottom" | "paddingLeft" | "margin" | "marginTop" | "marginRight" | "marginBottom" | "marginLeft" | "width" | "height" | "minWidth" | "minHeight" | "maxWidth" | "maxHeight" | "overflow" | "overflowX" | "overflowY" | "position" | "top" | "right" | "bottom" | "left" | "zIndex" | "backgroundColor" | "color" | "opacity" | "border" | "borderTop" | "borderRight" | "borderBottom" | "borderLeft" | "borderRadius" | "borderWidth" | "borderStyle" | "borderColor" | "fontSize" | "fontWeight" | "fontFamily" | "lineHeight" | "textAlign" | "textTransform" | "letterSpacing" | "transform" | "transition" | "animation" | "animationName" | "animationDuration" | "animationTimingFunction" | "animationDelay" | "animationIterationCount" | "animationFillMode" | "animationDirection" | "animationPlayState" | "cursor" | "pointerEvents" | "objectFit" | "grid" | "gridTemplate" | "gridTemplateColumns" | "gridTemplateRows" | "gridArea" | "gridColumn" | "gridRow" | "gridGap" | "flex" | "flexGrow" | "flexShrink" | "flexBasis" | "flexWrap">;
+
+interface BoxProps {
+    children?: React.ReactNode;
+    style?: VisionStyle;
+}
+declare function Box({ children, style }: BoxProps): React.ReactElement;
+
+interface VStackProps {
+    children?: React.ReactNode;
+    gap?: number;
+    style?: VisionStyle;
+}
+declare function VStack({ children, gap, style }: VStackProps): React.ReactElement;
+
+interface HStackProps {
+    children?: React.ReactNode;
+    gap?: number;
+    style?: VisionStyle;
+}
+declare function HStack({ children, gap, style }: HStackProps): React.ReactElement;
+
+interface CompactViewProps {
+    title: string;
+    children?: React.ReactNode;
+}
+declare function CompactView({ title, children }: CompactViewProps): React.ReactElement;
+
+interface ListProps<T> {
+    items: T[];
+    renderItem: (item: T, index: number) => React.ReactNode;
+    emptyText?: string;
+}
+declare function List<T>({ items, renderItem, emptyText }: ListProps<T>): React.ReactElement;
+
+interface TextProps {
+    content: string;
+    variant?: "default" | "heading" | "muted";
+}
+declare function Text({ content, variant }: TextProps): React.ReactElement;
+
+interface ImageProps {
+    src: string;
+    alt: string;
+    objectFit?: React.CSSProperties["objectFit"];
+}
+declare function Image({ src, alt, objectFit }: ImageProps): React.ReactElement;
+
+interface ButtonProps {
+    label: string;
+    onClick: () => void;
+    variant?: "default" | "destructive";
+    disabled?: boolean;
+}
+declare function Button({ label, onClick, variant, disabled }: ButtonProps): React.ReactElement;
+
+interface ToggleProps {
+    label: string;
+    checked: boolean;
+    onChange: (value: boolean) => void;
+}
+declare function Toggle({ label, checked, onChange }: ToggleProps): React.ReactElement;
+
+interface TextFieldProps {
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+}
+declare function TextField({ label, value, onChange, placeholder }: TextFieldProps): React.ReactElement;
+
+interface TextAreaProps {
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    rows?: number;
+}
+declare function TextArea({ label, value, onChange, placeholder, rows }: TextAreaProps): React.ReactElement;
+
+interface NumberFieldProps {
+    label: string;
+    value: number;
+    onChange: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+declare function NumberField({ label, value, onChange, min, max, step }: NumberFieldProps): React.ReactElement;
+
+interface DropdownOption {
+    value: string;
+    label: string;
+}
+interface DropdownProps {
+    label: string;
+    value: string;
+    options: DropdownOption[];
+    onChange: (value: string) => void;
+}
+declare function Dropdown({ label, value, options, onChange }: DropdownProps): React.ReactElement;
+
+interface SliderProps {
+    label: string;
+    value: number;
+    onChange: (value: number) => void;
+    min: number;
+    max: number;
+    step?: number;
+}
+declare function Slider({ label, value, onChange, min, max, step }: SliderProps): React.ReactElement;
+
+declare function useExtensionStorage<T = Record<string, unknown>>(key: string, initialValue: T): [T, (value: T) => void];
+
+declare function useVisionState<T>(key: string, defaultValue: T): [T, (value: T) => void];
+
+interface ExtensionContext {
+    extensionId: string | null;
+    target: "editor" | "layer" | "interactive" | null;
+    overlayId: string | null;
+    interactiveUrl: string | null;
+}
+declare function useExtensionContext(): ExtensionContext;
+
+declare function useLumioEvent(eventType: LumioEventType): unknown | null;
+
+interface LumioConfig {
+    extension_id?: string;
+    install_id?: string;
+    account_id?: string;
+    target?: "editor" | "layer" | "interactive";
+    permissions?: string[];
+    settings?: Record<string, unknown>;
+}
+declare function useLumioConfig(): [LumioConfig, (config: LumioConfig) => void];
+
+interface OverlayTheme {
+    colors: {
+        primary: string;
+        secondary: string;
+        accent: string;
+        background: string;
+        surface: string;
+        text: string;
+        muted: string;
+        border: string;
+    };
+    fonts: {
+        heading: string;
+        body: string;
+    };
+    borderRadius: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+    spacing: number;
+}
+/**
+ * Returns the active overlay/widget theme variables.
+ *
+ * Extensions use this to style themselves consistently with the
+ * overlay or widget they're rendered in. Only relevant for `layer`
+ * and `interactive` targets (OBS overlay, widget pages).
+ *
+ * Theme is provided via lifecycle.init and updated via theme.change when
+ * the user switches the overlay/widget theme.
+ */
+declare function useLumioTheme(): OverlayTheme;
+
+interface LumioIdentity {
+    userId: string | null;
+    accountId: string | null;
+    role: string | null;
+}
+declare function useLumioIdentity(): LumioIdentity;
+
+interface UseLumioActionResult {
+    execute: (params?: Record<string, unknown>) => void;
+    data: unknown | null;
+    isLoading: boolean;
+    error: string | null;
+}
+declare function useLumioAction(action: LumioActionType): UseLumioActionResult;
+
+interface UseQueryResult {
+    data: unknown | null;
+    isLoading: boolean;
+    error: string | null;
+    refetch: () => void;
+}
+declare function useQuery(functionName: string, params?: Record<string, unknown>): UseQueryResult;
+
+interface UseMutationResult {
+    mutate: (params?: Record<string, unknown>) => void;
+    mutateAsync: (params?: Record<string, unknown>) => Promise<unknown>;
+    data: unknown | null;
+    isLoading: boolean;
+    error: string | null;
+}
+declare function useMutation(functionName: string): UseMutationResult;
+
+type KeyframeBlock = Record<string, string>;
+type KeyframeDefinition = Record<string, KeyframeBlock>;
+declare function defineKeyframes(definition: KeyframeDefinition): string;
+declare function flushKeyframes(): void;
+
+declare const ANIMATION_PRESETS: {
+    readonly fadeIn: {
+        readonly from: {
+            readonly opacity: "0";
+        };
+        readonly to: {
+            readonly opacity: "1";
+        };
+    };
+    readonly fadeOut: {
+        readonly from: {
+            readonly opacity: "1";
+        };
+        readonly to: {
+            readonly opacity: "0";
+        };
+    };
+    readonly zoomIn: {
+        readonly from: {
+            readonly opacity: "0";
+            readonly transform: "scale(0.5)";
+        };
+        readonly to: {
+            readonly opacity: "1";
+            readonly transform: "scale(1)";
+        };
+    };
+    readonly zoomOut: {
+        readonly from: {
+            readonly opacity: "1";
+            readonly transform: "scale(1)";
+        };
+        readonly to: {
+            readonly opacity: "0";
+            readonly transform: "scale(0.5)";
+        };
+    };
+    readonly slideLeftIn: {
+        readonly from: {
+            readonly opacity: "0";
+            readonly transform: "translateX(-100%)";
+        };
+        readonly to: {
+            readonly opacity: "1";
+            readonly transform: "translateX(0)";
+        };
+    };
+    readonly slideLeftOut: {
+        readonly from: {
+            readonly opacity: "1";
+            readonly transform: "translateX(0)";
+        };
+        readonly to: {
+            readonly opacity: "0";
+            readonly transform: "translateX(-100%)";
+        };
+    };
+    readonly slideRightIn: {
+        readonly from: {
+            readonly opacity: "0";
+            readonly transform: "translateX(100%)";
+        };
+        readonly to: {
+            readonly opacity: "1";
+            readonly transform: "translateX(0)";
+        };
+    };
+    readonly slideRightOut: {
+        readonly from: {
+            readonly opacity: "1";
+            readonly transform: "translateX(0)";
+        };
+        readonly to: {
+            readonly opacity: "0";
+            readonly transform: "translateX(100%)";
+        };
+    };
+    readonly slideUpIn: {
+        readonly from: {
+            readonly opacity: "0";
+            readonly transform: "translateY(-100%)";
+        };
+        readonly to: {
+            readonly opacity: "1";
+            readonly transform: "translateY(0)";
+        };
+    };
+    readonly slideUpOut: {
+        readonly from: {
+            readonly opacity: "1";
+            readonly transform: "translateY(0)";
+        };
+        readonly to: {
+            readonly opacity: "0";
+            readonly transform: "translateY(-100%)";
+        };
+    };
+    readonly slideDownIn: {
+        readonly from: {
+            readonly opacity: "0";
+            readonly transform: "translateY(100%)";
+        };
+        readonly to: {
+            readonly opacity: "1";
+            readonly transform: "translateY(0)";
+        };
+    };
+    readonly slideDownOut: {
+        readonly from: {
+            readonly opacity: "1";
+            readonly transform: "translateY(0)";
+        };
+        readonly to: {
+            readonly opacity: "0";
+            readonly transform: "translateY(100%)";
+        };
+    };
+    readonly pushLeftIn: {
+        readonly from: {
+            readonly transform: "translateX(100%)";
+        };
+        readonly to: {
+            readonly transform: "translateX(0)";
+        };
+    };
+    readonly pushLeftOut: {
+        readonly from: {
+            readonly transform: "translateX(0)";
+        };
+        readonly to: {
+            readonly transform: "translateX(-100%)";
+        };
+    };
+    readonly pushRightIn: {
+        readonly from: {
+            readonly transform: "translateX(-100%)";
+        };
+        readonly to: {
+            readonly transform: "translateX(0)";
+        };
+    };
+    readonly pushRightOut: {
+        readonly from: {
+            readonly transform: "translateX(0)";
+        };
+        readonly to: {
+            readonly transform: "translateX(100%)";
+        };
+    };
+    readonly pushUpIn: {
+        readonly from: {
+            readonly transform: "translateY(100%)";
+        };
+        readonly to: {
+            readonly transform: "translateY(0)";
+        };
+    };
+    readonly pushUpOut: {
+        readonly from: {
+            readonly transform: "translateY(0)";
+        };
+        readonly to: {
+            readonly transform: "translateY(-100%)";
+        };
+    };
+    readonly pushDownIn: {
+        readonly from: {
+            readonly transform: "translateY(-100%)";
+        };
+        readonly to: {
+            readonly transform: "translateY(0)";
+        };
+    };
+    readonly pushDownOut: {
+        readonly from: {
+            readonly transform: "translateY(0)";
+        };
+        readonly to: {
+            readonly transform: "translateY(100%)";
+        };
+    };
+    readonly pulse: {
+        readonly "0%": {
+            readonly transform: "scale(1)";
+        };
+        readonly "50%": {
+            readonly transform: "scale(1.05)";
+        };
+        readonly "100%": {
+            readonly transform: "scale(1)";
+        };
+    };
+    readonly bounce: {
+        readonly "0%": {
+            readonly transform: "translateY(0)";
+        };
+        readonly "50%": {
+            readonly transform: "translateY(-10px)";
+        };
+        readonly "100%": {
+            readonly transform: "translateY(0)";
+        };
+    };
+};
+type AnimationPresetName = keyof typeof ANIMATION_PRESETS;
+declare function getPreset(name: AnimationPresetName): string;
+
+interface AnimatedProps {
+    children: React.ReactNode;
+    in?: AnimationPresetName | string;
+    out?: AnimationPresetName | string;
+    loop?: AnimationPresetName | string;
+    duration?: number;
+    loopDuration?: number;
+    easing?: string;
+    delay?: number;
+    visible?: boolean;
+    onAnimationEnd?: () => void;
+}
+declare function Animated({ children, in: inProp, out: outProp, loop: loopProp, duration, loopDuration, easing, delay, visible, onAnimationEnd, }: AnimatedProps): React.ReactElement;
+
+interface UseAnimationResult {
+    trigger: (preset: AnimationPresetName | string, duration?: number) => string;
+    reset: () => void;
+    isAnimating: boolean;
+    currentAnimation: string | null;
+    style: Record<string, string | number>;
+}
+declare function useAnimation(): UseAnimationResult;
+
+type FontDisplay = "auto" | "block" | "swap" | "fallback" | "optional";
+interface FontSource {
+    path: string;
+    weight?: string;
+    style?: string;
+}
+interface LocalFontOptions {
+    src: string | FontSource[];
+    family: string;
+    weight?: string;
+    style?: string;
+    display?: FontDisplay;
+    fallback?: string[];
+}
+interface LocalFontDefinition {
+    fontFamily: string;
+}
+declare function localFont(options: LocalFontOptions): LocalFontDefinition;
+
+export { ANIMATION_PRESETS, Animated, type AnimatedProps, type AnimationPresetName, Box, type BoxProps, Button, type ButtonProps, CompactView, type CompactViewProps, Dropdown, type DropdownOption, type DropdownProps, type ExtensionContext, type FontDisplay, type FontSource, HStack, type HStackProps, Image, type ImageProps, type KeyframeBlock, type KeyframeDefinition, List, type ListProps, type LocalFontDefinition, type LocalFontOptions, Lumio, type LumioConfig, type LumioIdentity, NumberField, type NumberFieldProps, type OverlayTheme, type RenderOptions, Slider, type SliderProps, Text, TextArea, type TextAreaProps, TextField, type TextFieldProps, type TextProps, Toggle, type ToggleProps, type UseAnimationResult, type UseLumioActionResult, type UseMutationResult, type UseQueryResult, VStack, type VStackProps, type VisionStyle, WorkerBridge, defineKeyframes, flushKeyframes, getPreset, localFont, useAnimation, useExtensionContext, useExtensionStorage, useLumioAction, useLumioConfig, useLumioEvent, useLumioIdentity, useLumioTheme, useMutation, useQuery, useVisionState };