Getting Started Actions Live Data Sources Launch Folders WebShell Development Kit
Advanced

WebShell Development Kit

This page is the developer entry point after you understand WebTrigger concepts. A WebShell is a normal browser interface that calls local WebTrigger APIs for actions, live data, launch folders, and icons.

Use this as a practical SDK guide for hand-built shells, theme experiments, and AI-assisted shell creation.

Recommended Discovery Endpoint

GET /api/theme-context/export gives a WebShell or AI assistant the current actions, Live Data Sources, launch folders, API guide, and UI guidance in one place.

const context = await fetch('/api/theme-context/export').then(res => res.json());

const actions = context.actions || [];
const liveDataSources = context.liveDataSources || [];
const launchFolders = context.launchFolders || [];

Developer API

WebShell JavaScript should use same-origin relative paths. These endpoints are served by the PC running WebTrigger.

GET/api/theme-context/export

Discover actions, LDS, launch folders, icon guidance, and available API information.

GET/api/actions

List configured user actions.

POST/api/actions/execute/{id}

Execute a configured action. Confirmation actions use { "confirmed": true }.

GET/api/system-actions

List built-in media, desktop, and power actions.

POST/api/system-actions/{id}/execute

Execute a built-in action. Dangerous actions require confirmation.

GET/api/live-data

Get the current LDS snapshot.

GET/api/state/stream

Subscribe to live data changes with Server-Sent Events.

GET/api/launch-folders

List configured launch folders.

GET/api/launch-folders/{id}/items

List launchable items inside a folder.

POST/api/launch-items/{id}/launch

Launch a detected folder item.

GET/api/icons/resolve?actionId={id}

Resolve an action icon to an icon URL, type, and colorizable flag.

GET/api/icons/custom/{fileName}

Load a custom icon asset.

GET/api/icons/action-cache/{fileName}

Load an action icon cached by WebTrigger.

JavaScript Examples

Load Actions

const actions = await fetch('/api/actions').then(res => res.json());

for (const action of actions) {
  console.log(action.name || action.Name, action.id || action.Id);
}

Run an Existing Action

async function runAction(action) {
  const id = action.id || action.Id;
  const confirmed = !!(action.confirmationRequired || action.ConfirmationRequired);

  const res = await fetch(`/api/actions/execute/${encodeURIComponent(id)}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ confirmed })
  });

  const result = await res.json();

  if (res.status === 429) {
    console.log(`Cooldown: try again in ${result.retryAfterSeconds}s`);
  }

  if (result.requiresConfirmation) {
    console.log('Ask the user to confirm, then retry with confirmed: true.');
  }

  return result;
}

Display an LDS Snapshot

const liveData = await fetch('/api/live-data').then(res => res.json());

document.querySelector('[data-lds="cpu"]').textContent =
  liveData.cpu === 'N/A' ? '--' : `${liveData.cpu}%`;

Subscribe to Live Updates

const stream = new EventSource('/api/state/stream');

stream.onmessage = event => {
  const { key, value } = JSON.parse(event.data);
  const target = document.querySelector(`[data-lds="${key}"]`);
  if (target) target.textContent = value;
};

Resolve an Action Icon

async function resolveIcon(actionId) {
  const url = `/api/icons/resolve?actionId=${encodeURIComponent(actionId)}`;
  return fetch(url).then(res => res.json());
}

Expandable Patterns

Button deck pattern

Fetch actions, group them by category or tags, render big touch-friendly buttons, and call /api/actions/execute/{id} when pressed.

Dashboard / live data pattern

Render LDS cards for built-in keys like cpu, ram, volume, battery, and any custom LDS key the user creates. Use /api/state/stream for live updates.

Mobile companion pattern

Use large navigation tabs, large touch targets, search, and quick pages for actions, media controls, scripts, and system actions.

Themed immersive shell pattern

Keep the API calls simple, then put your creativity into layout, typography, motion, sound, and visual state. Cyber Fantasy uses this approach.

AI-assisted shell creation

Start by giving the assistant /api/theme-context/export, your layout goal, target device size, and the built-in safety rules. Review any generated JavaScript before importing it.

Bundled WebShell References

Default

Action lists, pinned controls, launch folders, system controls, and live status cards.

Action Deck

Page-based button grids and layout editing, backed by /api/actiondeck/layout.

Cyber Fantasy

A themed system dashboard that still uses straightforward action, live data, and launch-folder APIs.

Companion

Mobile-first navigation for actions, media, scripts, launch folders, and system controls.

Creation Checklist

  • Use same-origin relative API paths like /api/actions.
  • Escape user-provided names, descriptions, categories, and tags before rendering HTML.
  • Handle loading, success, error, confirmation, and cooldown states.
  • Keep touch targets large for phones, tablets, and wall panels.
  • Treat imported scripts, launch folders, HTTP actions, and Python actions as powerful user-trusted data.
  • Use /api/theme-context/export when you want the app to describe available actions, LDS, icons, and endpoints.