SE Widget Studio Web
A personal, code-accessible workbench for StreamElements Custom Widgets. Submit HTML, CSS, JavaScript, and the real FIELDS schema through the API or web import screen, then use a private editing link to preview themes, run synthetic tests, and generate visual assets.
The Next.js application lives at this repository's root. Consumer widgets remain plain HTML/CSS/JS/FIELDS; they do not need React, a bundler, or changes to their production files. The shared simulation and renderer also remain available as a local CLI.
What it does
- Imports versioned snapshots without modifying the original files.
- Runs widgets inside opaque-origin sandboxed iframes with runtime network access blocked. Google Fonts are the one exception, and widgets load them as in StreamElements: trusted server code fetches them into an append-only cache, and previews and jobs get them from there (Google Fonts).
- Substitutes
{{field}} and {field} placeholders in HTML, CSS, and JavaScript, and reloads the widget when a field changes, as the StreamElements editor does.
- Generates controls from FIELDS, with themes, fixtures, scenes, framing, and a theme gallery.
- Saves immutable revisions and rejects stale full replacements instead of overwriting another editor's work.
- Runs deterministic browser scenarios and recipes for screenshots, thumbnails, contact sheets, and short silent videos.
- Uses the same shared engine for the web application, local CLI, and automated jobs.
- Ships built-in synthetic sample images, so a widget can be previewed, tested, and rendered without creating or uploading media.
There are no user accounts and no external database. In production, private Vercel Blob stores projects, revisions, uploads, and final artifacts; Workflows orchestrate jobs; short-lived Sandboxes run the browser/media worker. The editing link is a secret capability, not a public sharing link.
Run locally
Requirements: Node.js >=22.20 <23 or >=24 <25, npm 10.9.3, and the committed lockfile. Browser jobs also require an already-installed Chrome/Chromium. Final video jobs require existing FFmpeg and ffprobe executables.
From the repository root, after authorizing dependency installation:
npm ci
npm run dev
Open http://127.0.0.1:3000 and choose Open demo project, or import a WidgetSnapshot JSON document. No Vercel credentials are needed locally. The default storage directory is .studio-data; keep it private and backed up if the projects matter.
Both npm run dev and npm start bind to 127.0.0.1. The Studio that agents use by default is the production build on port 4310, which the se-widget-studio skill's client targets:
npm run build
npm run serve # http://127.0.0.1:4310
Outside Vercel the Studio drops the hosted deployment's quotas (daily budgets, ten-minute jobs, 15-second videos, four video variants, 900 frames per job); a job instead waits for the machine-wide render slot and then for the machine check, and keeps the render disk guard (lib/limits.ts). The hosted deployment is paused since 2026-10-01.
A local job runs inside the server process, whichever session submitted it, so stop the server only once node skills/se-widget-studio/scripts/studio-client.mjs active prints "activeJobs":0. A job that a stopped server took along fails, and frees its project, the next time the restarted Studio reads it (Jobs).
The repository uses playwright-core. Normal startup, tests, and rendering never download Chromium, FFmpeg, codecs, or fonts. Install or select these tools deliberately; SE_WIDGET_STUDIO_BROWSER, STUDIO_FFMPEG_PATH, and STUDIO_FFPROBE_PATH can point to existing local executables.
Environment modes
| Setting | Local development | Vercel deployment |
|---|
STUDIO_STORAGE | local (default outside Vercel) | blob |
STUDIO_EXECUTION | local (default outside Vercel) | vercel |
STUDIO_DATA_DIR | Optional; defaults to .studio-data | Not used as a fallback |
| Blob credentials | Not required | Private Blob integration token, or configured store ID and Vercel OIDC identity |
STUDIO_SANDBOX_SNAPSHOT_ID | Not required | Required for jobs; trusted browser/media baseline |
STUDIO_CREATE_KEY | Optional creation gate | Optional creation gate; clients send X-Studio-Key |
.env.example documents local values. Do not copy its local mode settings into Vercel. Hosted deployments reject local storage and local workers rather than silently using ephemeral disk. Configure production resources and variables, then redeploy; see Vercel setup. Installing a plugin or successfully building the app does not provision or validate those resources.
API workflow
POST /api/v1/projects with a complete versioned snapshot.- Keep the returned capability secret; open
editorUrl only in a trusted browser.
- Read with
Authorization: Bearer <capability>.
- Replace the complete snapshot with
PUT and the latest JSON response's etag as If-Match.
- Submit a test or render job, poll its status, and download authorized artifacts.
The API reference includes runnable import examples, schemas, uploads, previews, history, limits, and error handling. A 201 response may contain a blocked revision: inspect its diagnostics before attempting a preview or job.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
