### Watch Mode for Example Applications

Source: https://github.com/stagewise-io/stagewise/blob/main/CLAUDE.md

Specifically watches and rebuilds example applications. Use this if you are only working on framework integration examples.

```bash
pnpm dev:examples
```

--------------------------------

### Starting Storybook

Source: https://github.com/stagewise-io/stagewise/blob/main/packages/stage-ui/README.md

Command to start the Storybook development server for previewing components and color definitions.

```bash
pnpm --filter stagewise storybook
```

--------------------------------

### Example Custom Release Notes Output

Source: https://github.com/stagewise-io/stagewise/blob/main/VERSIONING.md

An example of how custom release notes are merged into the changelog format.

```markdown
## 1.0.1 (2024-01-15)

This release includes a major redesign of the navigation system.

### Migration Guide

Update your navigation configuration:
- Old: `nav.configure({ ... })
- New: `nav.setup({ ... })

### Features

* add dark mode support (def5678)
...
```

--------------------------------

### Install Mediabunny

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/can-decode.md

Install the correct version of Mediabunny using npx.

```bash
npx remotion add mediabunny
```

--------------------------------

### Initialize ThreeCanvas with Lights and a Mesh

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/3d.md

Wrap your 3D scene in `<ThreeCanvas>` and configure its dimensions. Add ambient and directional lights for scene illumination. This example demonstrates a basic setup with a sphere.

```tsx
import{ThreeCanvas}from"@remotion/three";import{useVideoConfig}from"remotion";const{width,height}=useVideoConfig();
<ThreeCanvas width={width} height={height}><ambientLight intensity={0.4}/><directionalLight position={[5,5,5]} intensity={0.8}/><mesh><sphereGeometry args={[1,32,32];}/><meshStandardMaterial color="red"/></mesh></ThreeCanvas>;
```

--------------------------------

### Install Karton

Source: https://github.com/stagewise-io/stagewise/blob/main/packages/karton/README.md

Install Karton using npm or pnpm.

```bash
npm install @stagewise/karton
# or
pnpm add @stagewise/karton
```

--------------------------------

### Usage Example for getVideoDimensions

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/get-video-dimensions.md

Demonstrates how to call `getVideoDimensions` with a video URL and log the resulting width and height. The example assumes the function is already defined.

```javascript
const dimensions=await getVideoDimensions("https://remotion.media/video.mp4");
console.log(dimensions.width)/*e.g.1920*/;
console.log(dimensions.height)/*e.g.1080*/;
```

--------------------------------

### Start Fresh Alpha Version

Source: https://github.com/stagewise-io/stagewise/blob/main/VERSIONING.md

Use `--new-cycle` to abandon the current prerelease and start a fresh alpha version when adding new features during beta.

```bash
pnpm version:stagewise --channel alpha --new-cycle
```

--------------------------------

### Install @remotion/captions

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/display-captions.md

Install the @remotion/captions package using npm or yarn.

```bash
npx remotion add @remotion/captions
```

--------------------------------

### Version Transition Examples

Source: https://github.com/stagewise-io/stagewise/blob/main/VERSIONING.md

Shows examples of version transitions between different release stages, including bumping to alpha, incrementing within alpha, moving from alpha to beta, releasing a final version, and bumping to beta from a released version.

```text
1.0.0 | alpha | 1.0.1-alpha001 (bump applied)
1.0.1-alpha001 | alpha | 1.0.1-alpha002
1.0.1-alpha005 | beta | 1.0.1-beta001
1.0.1-beta003 | release | 1.0.1
1.0.1 | beta | 1.0.2-beta001 (bump applied)
```

--------------------------------

### SKILL.md Example for Remotion Styleguide

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/styleguides/howto.md

This is an example of a `SKILL.md` file for a Remotion video styleguide. It includes YAML frontmatter with name and description, and references other styleguide components like layouts, storyboard templates, and elements.

```markdown
---
name: mycompany-video-styleguide
description: mycompany video styleguide for making videos with Remotion.
---

`DESIGN.md` is in workspace root.

## `./layouts`

- `logo-slide.md`: single logo slide. outro / last slide.
- `person-with-name-overlay.md`: camera shot with name + role overlay.
- `video-demo-slide-text-left.md`: product demo with short explainer on side.

## `./storyboard-templates`

- `feature-launch.md`: short feature demo, 20-40s, social media.
- `extended-product-demo.md`: longer demo with explainers and camera content.

## `./elements`

- `logo.md`: watermark, intro/outro, demo components.
- `mascot.md`: floating mascot in product demos.
```

--------------------------------

### References Section Example

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/skills/learn-skill/SKILL.md

Example of how to list reference files in a Markdown skill file, specifying their content and when they should be loaded.

```markdown
## References
- `references/render-loops-debugging.md` — workflow for diagnosing excess re-renders. Load when investigating render performance.
```

--------------------------------

### Example Usage of Custom Extended Utilities

Source: https://github.com/stagewise-io/stagewise/blob/main/packages/tailwindcss-color-modifiers/README.md

Provides HTML examples for using custom utilities with and without color modifiers, demonstrating how the plugin extends functionality.

```html
<!-- Base utility: handled by your @utility -->
<div class="shimmer-from-blue-500 shimmer-to-purple-500">

<!-- With modifiers: handled by the plugin -->
<div class="shimmer-from-blue-500/l20 shimmer-to-purple-500/c-10">
```

--------------------------------

### Start Remotion Studio

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/SKILL.md

Launch the Remotion Studio development server to preview your video compositions in the browser.

```bash
npx remotion studio
```

--------------------------------

### Start Electron Browser App with Typecheck

Source: https://github.com/stagewise-io/stagewise/blob/main/CLAUDE.md

Starts the Electron browser application, which is the main product. This command also includes a typecheck to ensure code integrity.

```bash
pnpm -F stagewise start
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/stagewise-io/stagewise/blob/main/CLAUDE.md

Use this command to install all project dependencies. Node.js version 18+ and pnpm version 10.x are required.

```bash
pnpm install
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/stagewise-io/stagewise/blob/main/AGENTS.md

Provides concrete examples of conventional commit messages, adhering to the specified format and scope requirements.

```bash
feat(browser): add dark mode toggle
```

```bash
fix(karton): resolve connection timeout
```

--------------------------------

### Install Tailwind CSS Color Modifiers

Source: https://github.com/stagewise-io/stagewise/blob/main/packages/tailwindcss-color-modifiers/README.md

Install the plugin using your preferred package manager.

```bash
pnpm add -D @stagewise/tailwindcss-color-modifiers
# or
npm install -D @stagewise/tailwindcss-color-modifiers
# or
yarn add -D @stagewise/tailwindcss-color-modifiers
```

--------------------------------

### Execute Shell Command: Start Dev Server

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/src/backend/agents/shared/prompts/system/environment.md

Start a development server, specifying a working directory and a wait condition based on an output pattern. The `idle_ms` is set to 0 for servers with legitimate long silent startup phases.

```json
{ "explanation": "Start dev server", "command": "pnpm dev", "cwd": "w1", "wait_until": { "output_pattern": "ready|listening", "timeout_ms": 30000, "idle_ms": 0 } }
```

--------------------------------

### Start Development Watch Mode

Source: https://github.com/stagewise-io/stagewise/blob/main/CLAUDE.md

Starts all packages in watch mode using Turbo. This command is useful for continuous development and seeing changes reflected immediately.

```bash
pnpm dev
```

--------------------------------

### Run HogQL Query Example

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/posthog/SKILL.md

Example of a POST request body to run a HogQL query. This is the primary analytical tool for querying events, persons, and more with SQL-like syntax.

```json
{
  "query": {
    "kind": "HogQLQuery",
    "query": "SELECT event, count() AS cnt FROM events WHERE timestamp > now() - interval 7 day GROUP BY event ORDER BY cnt DESC LIMIT 20"
  }
}
```

--------------------------------

### Good Example of File Naming in Table

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/styleguides/howto.md

This example demonstrates a good practice for file naming within a markdown table, providing clear context for the file's purpose.

```markdown
| `./elements/logo.md` | Watermarks, intro/outro, demos |
```

--------------------------------

### Install Whisper.cpp and Transcribe Audio

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/transcribe-captions.md

This script installs Whisper.cpp, downloads a specified model, and then transcribes an audio file into captions. Ensure your audio is in WAV format at 16KHz, or use FFmpeg to convert it first. The output captions are saved to a JSON file.

```typescript
import path from"path";import{downloadWhisperModel,installWhisperCpp,transcribe,toCaptions}from"@remotion/install-whisper-cpp";import fs from"fs";
const to=path.join(process.cwd(),"whisper.cpp");await installWhisperCpp({to,version:"1.5.5"});await downloadWhisperModel({model:"medium.en",folder:to});
// Convert audio to 16KHz wav first if needed:
// import {execSync} from 'child_process';
// execSync('ffmpeg -i /path/to/audio.mp4 -ar 16000 /path/to/audio.wav -y');
const whisperCppOutput=await transcribe({model:"medium.en",whisperPath:to,whisperCppVersion:"1.5.5",inputPath:"/path/to/audio123.wav",tokenLevelTimestamps:true});const{captions}=toCaptions({whisperCppOutput});fs.writeFileSync("captions123.json",JSON.stringify(captions,null,2));
```

--------------------------------

### Run Web Stats Query Example

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/posthog/SKILL.md

Example of a POST request body to run a WebStatsTableQuery. Useful for analyzing web traffic data like page views and user sessions within a specified date range.

```json
{
  "query": {
    "kind": "WebStatsTableQuery",
    "dateRange": { "date_from": "2025-01-01", "date_to": "2025-01-31" },
    "breakdownBy": "Page",
    "limit": 10
  }
}
```

--------------------------------

### Usage Example for canDecode()

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/can-decode.md

Demonstrates how to use the `canDecode` function with a video URL and log the result to the console.

```typescript
const src="https://remotion.media/video.mp4";
const isDecodable=await canDecode(src);
if(isDecodable){
    console.log("Video can be decoded")
}
else{
    console.log("Video cannot be decoded by this browser")
}
```

--------------------------------

### Get Audio Duration in Browser

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/get-audio-duration.md

Use this function to get the duration of an audio file from a URL. It handles the Mediabunny input setup and duration computation.

```typescript
import{Input,ALL_FORMATS,UrlSource}from"mediabunny";
export const getAudioDuration=async(src:string)=>{
  const input=new Input({formats:ALL_FORMATS,source:new UrlSource(src,{getRetryDelay:()=>null})});
  const durationInSeconds=await input.computeDuration();
  return durationInSeconds;
};
```

```typescript
const duration=await getAudioDuration("https://remotion.media/audio.mp3");
console.log(duration); /*e.g. 180.5 (seconds)*/
```

```typescript
import{staticFile}from"remotion";
const duration=await getAudioDuration(staticFile("audio.mp3"));
```

--------------------------------

### File Path Examples with Mount Prefix

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/src/backend/agents/shared/prompts/fragments/filesystem.md

Illustrates how to construct file paths using the mount prefix for various file operations.

```text
w6053/src/index.ts
```

```text
w6053/.stagewise/WORKSPACE.md
```

```text
w6053/**/*.json
```

--------------------------------

### Usage Example: Get Video Duration

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/get-video-duration.md

Demonstrates how to call the `getVideoDuration` function and log the result. The duration is returned in seconds.

```typescript
const duration=await getVideoDuration("https://remotion.media/video.mp4");
console.log(duration);
/*e.g.10.5(seconds)*/
```

--------------------------------

### Trim Animation Start with Negative 'from'

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/trimming.md

Use a negative 'from' prop on the Sequence component to trim the beginning of an animation. This shifts the animation's start time backward, making it appear partway through the overall timeline. For example, setting `from={-0.5*fps}` delays the animation's start by 0.5 seconds.

```jsx
import {Sequence, useVideoConfig} from "remotion";
const fps = useVideoConfig();
<Sequence from={-0.5*fps}>
  <MyAnimation />
</Sequence>;
```

--------------------------------

### Karton Server Setup

Source: https://github.com/stagewise-io/stagewise/blob/main/packages/karton/README.md

Set up the Karton server, including defining procedures, initial state, and integrating with an HTTP server.

```typescript
import { createKartonServer } from '@stagewise/karton/server';
import express from 'express';
import { createServer } from 'http';

const app = express();
const httpServer = createServer(app);

const server = await createKartonServer<MyApp>({
  procedures: {
    increment: async (callingClientId) => {
      server.setState(draft => {
        draft.counter++;
      });
    },
    addUser: async (name, callingClientId) => {
      server.setState(draft => {
        draft.users.push(name);
      });
    }
  },
  initialState: {
    counter: 0,
    users: []
  }
});

// Hook the upgrade handler of the karton created websockert server into your local webserver
httpServer.on('upgrade', (req, socket, head) => {
  if(req.url === '/path-for-karton-ws-connection') {
    server.wss.handleUpgrade(request, socket, head, (ws: any) => {
      server.wss.emit('connection', ws, request);
    })
  }
})

httpServer.listen(3000);
```

--------------------------------

### Create an annotation (JSON)

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/posthog/SKILL.md

Example JSON body for creating a new annotation. Requires content and date_marker.

```json
{
  "content": "Deployed v2.1.0",
  "date_marker": "2025-03-15T12:00:00Z",
  "scope": "project"
}
```

--------------------------------

### Explore Database Schema

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/supabase/SKILL.md

Example of how to list all tables in the 'public' schema using the database query endpoint.

```APIDOC
## Explore Database Schema

### Description
Example of how to list all tables in the 'public' schema.

### Method
POST

### Endpoint
/projects/${ref}/database/query/read-only

### Request Body
- **query** (string) - Required - The SQL query to execute.
```

--------------------------------

### Startup Sequence: WindowLayoutService Initialization

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/src/backend/services/window-layout/focus-handling.md

Details the initial steps of the WindowLayoutService constructor, including base window creation and initial view setup.

```typescript
1. WindowLayoutService constructor
   └─ BaseWindow created
   └─ uiController view added to contentView (only child at this point)
   └─ isWebContentInteractive = false (class field default)
```

--------------------------------

### Run Development Server

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/website/README.md

Use these commands to start the Next.js development server. Open http://localhost:3000 in your browser to view the application.

```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```

--------------------------------

### Startup Sequence: UI React App Mount

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/src/backend/services/window-layout/focus-handling.md

Outlines the steps that occur after the UI React app mounts, including the start of the WebContentsBoundsSyncer and the first layout update.

```typescript
3. UI React app mounts and renders
   └─ WebContentsBoundsSyncer starts RAF loop
   └─ ResizeObserver fires → sends first layoutUpdate(bounds)
```

--------------------------------

### Bad YAML Skill Description Example

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/skills/learn-skill/references/authoring-guide.md

Avoid vague and unspecific descriptions. This example is too general and does not provide enough information for discovery.

```yaml
description: Helps with documents
```

--------------------------------

### Karton Client Setup (Vanilla JS)

Source: https://github.com/stagewise-io/stagewise/blob/main/packages/karton/README.md

Initialize a Karton client for vanilla JavaScript applications, defining client procedures and fallback state.

```typescript
import { createKartonClient } from '@stagewise/karton/client';

const client = createKartonClient<MyApp>({
  webSocketPath: 'ws://localhost:3000/path-for-karton-ws-connection',
  procedures: {
    notify: async (message) => {
      console.log('Server notification:', message);
    }
  },
  fallbackState: {
    counter: 0,
    users: []
  }
});

// Read state
console.log(client.state.counter);

// Call server procedures
await client.serverProcedures.increment();
await client.serverProcedures.addUser('Alice');
```

--------------------------------

### Full Figma Setup Recipe

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/figma/SKILL.md

Run this in a single IIFE for each Figma tab to enable live selection monitoring. It opens the Figma app, adds a binding to the tab, subscribes to selection changes, and injects a polling script.

```javascript
// 1. Open the figma-app so the user sees live selection badges
await API.openApp('figma-app', { pluginId: 'figma', height: 120 });

// 2. Identify the Figma tab (use the tab whose URL contains figma.com/design/)
const tabId = "<figma-tab-id>";

// 3. Inject a Runtime binding so the tab can push data to the sandbox
await API.sendCDP(tabId, "Runtime.addBinding", { name: "sendToAgent" });

// 4. Subscribe to binding calls — accumulate AND forward to app
globalThis.figmaSelection = globalThis.figmaSelection || [];
globalThis._unsubFigmaBinding = API.onCDPEvent(tabId, "Runtime.bindingCalled", (event) => {
  if (event.name === "sendToAgent") {
    try {
      const payload = JSON.parse(event.payload);
      // Store for agent reads
      globalThis.figmaSelection = payload.nodes || [];
      // Forward to figma-app for live badge rendering
      API.sendMessage('figma-app', {
        type: 'selectionChanged',
        nodes: payload.nodes || [],
        timestamp: payload.timestamp,
      }, { pluginId: 'figma' });
    } catch {}
  }
});

// 5. Inject a polling script into the Figma tab
//    It reads figma.currentPage.selection every 200ms and pushes
//    changes through the binding.
await API.sendCDP(tabId, "Runtime.evaluate", {
  expression: "(
    function() {
      if (window.__figmaSelectionWatcher) return; // prevent duplicates
      window.__figmaSelectionWatcher = true;
      window.__lastSelKey = '';
      setInterval(() => {
        try {
          if (typeof figma === 'undefined' || !figma.currentPage) return;
          const sel = figma.currentPage.selection;
          const key = sel.map(n => n.id).join(',');
          if (key === window.__lastSelKey) return;
          window.__lastSelKey = key;
          window.sendToAgent(JSON.stringify({
            timestamp: Date.now(),
            nodes: sel.map(n => ({
              id: n.id,
              name: n.name,
              type: n.type,
              width: n.width,
              height: n.height,
            })),
          }));
        } catch {}
      }, 200);
    }
  )()",
});

API.output("Figma selection monitoring active. Select elements in the Figma tab — they will appear as badges in the Figma App.");

```

--------------------------------

### Bad Example of File Naming in Table

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/styleguides/howto.md

This example shows a less descriptive file naming convention within a markdown table, which is discouraged.

```markdown
| `./storyboard-templates/feature-launch.md` | Logo component explainer. Use throughout video. |
```

--------------------------------

### Import and Basic Usage

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/audio.md

Import the Audio component from `@remotion/media` and use it with a static file or a remote URL.

```APIDOC
## Import Audio

Use `<Audio>` from `@remotion/media`.

```tsx
import { Audio } from "@remotion/media";
import { staticFile } from "remotion";

export const MyComposition = () => {
  return <Audio src={staticFile("audio.mp3")} />;
};
```

Remote URL works too: 
```tsx
<Audio src="https://remotion.media/audio.mp3" />
```

Default: start now, full volume, full length. Stack many `<Audio>` for many tracks.
```

--------------------------------

### Vercel API GET Request

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/vercel/SKILL.md

Helper function to make GET requests to the Vercel API. It automatically includes the Bearer token in the Authorization header.

```javascript
async function vercelGet(path) {
  const res = await fetch(`https://api.vercel.com${path}`, {
    headers: {
      Authorization: `Bearer ${cred.token}`,
      'Content-Type': 'application/json',
    },
  });
  if (!res.ok) throw new Error(`Vercel API ${res.status}: ${await res.text()}`);
  return res.json();
}
```

--------------------------------

### Startup Sequence: handleUIReady

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/src/backend/services/window-layout/focus-handling.md

Describes the final steps in the startup sequence after the UI is ready, including showing the base window and applying initial state.

```typescript
5. handleUIReady
   └─ baseWindow.show() — window becomes visible to the user
   └─ Initial window state applied (maximize, fullscreen)
```

--------------------------------

### Client Instantiation

Source: https://github.com/stagewise-io/stagewise/blob/main/packages/karton/SPEC.md

Configuration and creation of a Karton client instance.

```APIDOC
## Client Instantiation

### Description
Creates a Karton client instance with the provided configuration.

### Type Definition
```typescript
interface KartonClientConfig<AppType> {
  webSocketPath: string;
  procedures: KartonClientProcedures<AppType>;
  fallbackState: KartonState<AppType>;
}

interface KartonClient<AppType> {
  state: KartonState<AppType>;
  serverProcedures: KartonServerProcedures<AppType>;
  isConnected: boolean;
}

type CreateKartonClient = <AppType>(config: KartonClientConfig<AppType>) => KartonClient<AppType>;
```

### Usage
```typescript
const createKartonClient: CreateKartonClient<AppType>;
```
```

--------------------------------

### Plan File Specification Example

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/skills/plan/SKILL.md

Illustrates the expected markdown structure for an implementation plan file, including title, description, context, and tasks with sub-steps.

```markdown
# Rename Commands to Skills

Rename all "command" terminology to "skill" across shared types, backend, and UI.

## Context

The codebase currently uses "command" (`CommandDefinition`, `CommandSource`, etc.) but the
user-facing terminology has shifted to "skill". The rename touches 3 files and 6 import sites.

## Tasks

- [ ] Rename `CommandDefinition` type and its source file

  Rename `w4ba9/src/shared/commands.ts` → `skills.ts`. Inside the file:
  - `CommandSource` → `SkillSource`
  - `CommandDefinition` → `SkillDefinition`
  - `toCommandDefinitionUI` → `toSkillDefinitionUI`

  Update all 6 import sites listed in the Context section.

- [ ] Update Karton state key from `commands` to `skills`

  In `w4ba9/src/shared/karton-contracts/ui/index.ts` (line ~629),
  change the state key and update the JSDoc comment above it.

- [ ] Verify typecheck passes

  Run `pnpm -F stagewise typecheck` for both `tsconfig.ui.json` and `tsconfig.backend.json`.

```

--------------------------------

### Initialize Picker App and Send Options

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/mini-apps/references/examples.md

Open the 'picker' app and set up a message listener in the sandbox. Then, send initial options to the app using `API.sendMessage`.

```javascript
await API.openApp("picker");

// Register listener for user selections
globalThis.pickerMessages = [];
globalThis._unsubPicker = API.onMessage("picker", (msg) => {
  globalThis.pickerMessages.push(msg);
});

// Send options to the app
await API.sendMessage("picker", {
  action: "setOptions",
  items: [
    { id: 1, label: "Option A" },
    { id: 2, label: "Option B" },
    { id: 3, label: "Option C" },
  ]
});
```

--------------------------------

### GET Request with Error Handling

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/javascript-sandbox/references/examples.md

Performs a GET request to an external API and handles potential HTTP errors. Returns the JSON response if the request is successful.

```javascript
const resp = await fetch("https://api.example.com/users?limit=10");
if (!resp.ok) throw new Error(`API error ${resp.status}: ${await resp.text()}`);
const data = await resp.json();
return data;
```

--------------------------------

### Scaffold a New Remotion Project

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/SKILL.md

Use `create-video` to scaffold a new Remotion project in an empty folder. Replace `my-video` with your desired project name. This command creates a new folder with a complete project structure.

```bash
npx create-video@latest --yes --blank --no-tailwind my-video
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/stagewise-io/stagewise/blob/main/VERSIONING.md

Examples of correctly formatted commit messages following the Conventional Commits specification with a mandatory scope. Sub-scopes and missing scopes are shown as invalid.

```bash
# Good
feat(stagewise): add dark mode toggle
fix(karton): resolve connection timeout issue
docs(stagewise): update installation guide

# Bad - will be rejected
feat(stagewise-ui): add button component  # Sub-scope not allowed
feat: add new feature                     # Missing scope
```

--------------------------------

### Get Video Duration in Browser

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/get-video-duration.md

Use this function to get the duration of a video from a URL in a browser environment. It configures Mediabunny to use `UrlSource` and disables retry delays.

```typescript
import{Input,ALL_FORMATS,UrlSource}from"mediabunny";export const getVideoDuration=async(src:string)=>{
const input=new Input({formats:ALL_FORMATS,source:new UrlSource(src,{getRetryDelay:()=>null})});
const durationInSeconds=await input.computeDuration();
return durationInSeconds
};
```

--------------------------------

### Basic Transition Series Setup

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/transitions.md

Use TransitionSeries to arrange scenes with transitions between them. Transitions shorten the timeline as scenes overlap.

```tsx
import{TransitionSeries,linearTiming}from"@remotion/transitions";import{fade}from"@remotion/transitions/fade";
<TransitionSeries><TransitionSeries.Sequence durationInFrames={60}><SceneA/></TransitionSeries.Sequence><TransitionSeries.Transition presentation={fade()} timing={linearTiming({durationInFrames:15});}/><TransitionSeries.Sequence durationInFrames={60}><SceneB/></TransitionSeries.Sequence></TransitionSeries>;
```

--------------------------------

### Figma API GET Request Helper

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/figma/SKILL.md

A helper function to make GET requests to the Figma API using the provided credential. It handles constructing the URL and checking for successful responses.

```javascript
async function figmaGet(path) {
  const res = await fetch(`https://api.figma.com/v1${path}`, {
    headers: { 'X-Figma-Token': cred.token },
  });
  if (!res.ok) throw new Error(`Figma API ${res.status}: ${await res.text()}`);
  return res.json();
}
```

--------------------------------

### Create Initial Git Tag for New Package

Source: https://github.com/stagewise-io/stagewise/blob/main/VERSIONING.md

After adding a new package configuration, create and push its initial git tag to the repository.

```bash
git tag @stagewise/new-package@0.0.1
git push --tags
```

--------------------------------

### Frame Referencing Inside Sequences

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/sequencing.md

When using `useCurrentFrame()` inside a component rendered by `<Sequence>`, it returns the local frame number starting from `0` relative to the sequence's start, not the global composition frame.

```tsx
<Sequence from={60} durationInFrames={30}><MyComponent/>{/*Inside MyComponent, useCurrentFrame() returns 0-29, not 60-89*/}</Sequence>
```

--------------------------------

### Prerelease Version Examples

Source: https://github.com/stagewise-io/stagewise/blob/main/VERSIONING.md

Illustrates the format for prerelease versions, which concatenates the channel name and a 3-digit zero-padded counter. This format ensures compatibility with SemVer 1.0 / NuGet's SemanticVersion parser.

```text
1.0.1-alpha001 - First alpha for upcoming 1.0.1
1.0.1-alpha002 - Second alpha
1.0.1-beta001 - First beta (after alpha phase)
1.0.1 - Final release
```

--------------------------------

### Karton Server Instantiation

Source: https://github.com/stagewise-io/stagewise/blob/main/packages/karton/SPEC.md

Configuration and creation of a Karton server instance. The `AppType` is statically checked for the correct base structure.

```APIDOC
## KartonServerConfig<AppType>

### Description
Configuration interface for the Karton server.

### Properties
- **procedures** (KartonServerProcedureImplementations<AppType>) - Optional: Implementations for server procedures. Can be registered lazily. Extracts required procedures from `AppType` and adds a `callingClientId` argument.
- **initialState** (KartonState<AppType>) - Required: The initial state of the Karton server.

## KartonServer<AppType>

### Description
Represents the Karton server instance.

### Properties
- **state** (KartonState<AppType>) - Read-only access to the current server state.
- **setState** ((recipe: (draft: KartonState<AppType>) => void) => KartonState<AppType>) - Function to update the state using an Immer-like recipe. Returns the updated state.
- **clientProcedures** (KartonClientProcedures<AppType>) - Client-side procedures that the server can call.
- **connectedClients** (string[]) - Read-only list of connected client IDs.
- **wss** (WebSocketServer) - The WebSocket server instance.
- **registerServerProcedureHandler** - Registers a server procedure handler lazily.
- **removeServerProcedureHandler** - Removes a server procedure handler.

## createKartonServer<AppType>

### Description
Function to create a new Karton server instance.

### Parameters
- **config** (KartonServerConfig<AppType>) - Configuration object for the server.

### Returns
- Promise<KartonServer<AppType>> - A promise that resolves to the Karton server instance.
```

--------------------------------

### Trim Start and Delay Animation with Nested Sequences

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/trimming.md

Nest Sequence components to achieve both trimming of the start and delaying the appearance of an animation. The inner sequence handles the initial trim, and the outer sequence introduces a delay to the result.

```jsx
<Sequence from={30}>
  <Sequence from={-15}>
    <MyAnimation />
  </Sequence>
</Sequence>
```

--------------------------------

### GitHub API GET Request Helper

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/github/SKILL.md

A helper function to make GET requests to the GitHub API. It automatically includes necessary headers like Accept, Authorization, and API version. Throws an error if the response is not successful.

```javascript
async function ghGet(path) {
  const res = await fetch(`https://api.github.com${path}`, {
    headers: {
      Accept: 'application/vnd.github+json',
      Authorization: `Bearer ${cred.token}`,
      'X-GitHub-Api-Version': '2022-11-28',
    },
  });
  if (!res.ok) throw new Error(`GitHub API ${res.status}: ${await res.text()}`);
  return res.json();
}
```

--------------------------------

### Start Storybook for Browser UI Components

Source: https://github.com/stagewise-io/stagewise/blob/main/CLAUDE.md

Launches Storybook for the browser application's UI components. This is useful for developing and visualizing components in isolation.

```bash
pnpm -F stagewise storybook
```

--------------------------------

### Startup Sequence: createTab Initialization

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/src/backend/services/window-layout/focus-handling.md

Describes the process of creating a new tab, including setting its visibility, adding its view, and initial z-order adjustments.

```typescript
2. createTab(initialUrl, true)
   └─ TabController created
   └─ tab.setVisible(false)
   └─ tab view added to contentView
   └─ updateZOrder() — UI stays on top (isWebContentInteractive = false)
   └─ handleSwitchTab(tabId)
       └─ currentWebContentBounds is null → tab stays invisible
       └─ isWebContentInteractive = false (explicit)
       └─ updateZOrder()
```

--------------------------------

### Get Video Dimensions from Local File

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/get-video-dimensions.md

This snippet shows how to get video dimensions from a local file object. It requires importing `Input`, `ALL_FORMATS`, and `FileSource` from 'mediabunny'. The `file` object should be provided via input or drag-and-drop.

```typescript
import{Input,ALL_FORMATS,FileSource}from"mediabunny";
const input=new Input({formats:ALL_FORMATS,source:new FileSource(file)})/*File obj from input/drag-drop*/;
const videoTrack=await input.getPrimaryVideoTrack();
const width=videoTrack.displayWidth;
const height=videoTrack.displayHeight;
```

--------------------------------

### Get Video Dimensions from URL

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/get-video-dimensions.md

Use this function to get the width and height of a video from a given URL. It requires importing `Input`, `ALL_FORMATS`, and `UrlSource` from 'mediabunny'. Ensure a video track is present, otherwise an error is thrown.

```typescript
import{Input,ALL_FORMATS,UrlSource }from"mediabunny";
export const getVideoDimensions=async(src:string)=>{
const input=new Input({formats:ALL_FORMATS,source:new UrlSource(src,{getRetryDelay:()=> null})});
const videoTrack = await input.getPrimaryVideoTrack();
if (!videoTrack) {
throw new Error("No video track found");
}
return {width: videoTrack.displayWidth,height: videoTrack.displayHeight};
};
```

--------------------------------

### Startup Sequence: handleLayoutUpdate

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/src/backend/services/window-layout/focus-handling.md

Details the actions taken when handleLayoutUpdate is called, specifically setting currentWebContentBounds and making the active tab visible.

```typescript
4. handleLayoutUpdate(bounds)
   └─ currentWebContentBounds = bounds (no longer null)
   └─ activeTab.setVisible(true)
   └─ activeTab.setBounds(bounds)
   └─ (z-order is NOT changed here — stays as-is)
```

--------------------------------

### PostHog GET Request Helper

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/posthog/SKILL.md

A helper function to make GET requests to the PostHog API. It automatically includes the Authorization header and handles basic error responses. Ensure the BASE URL is correctly set for the user's region.

```javascript
const BASE = 'https://us.posthog.com'; // or https://eu.posthog.com

async function phGet(path) {
  const res = await fetch(`${BASE}${path}`, {
    headers: {
      Authorization: `Bearer ${cred.personalApiKey}`,
      'Content-Type': 'application/json',
    },
  });
  if (!res.ok) throw new Error(`PostHog API ${res.status}: ${await res.text()}`);
  return res.json();
}
```

--------------------------------

### Create a database migration

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/supabase/SKILL.md

Initiate a new database migration by providing a name and the SQL statements to execute.

```http
POST /v1/projects/{ref}/database/migrations
Body: { "name": "add_users_table", "statements": ["CREATE TABLE ..."] }
```

--------------------------------

### Common Patterns

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/vercel/SKILL.md

Examples of common patterns for interacting with the Vercel API.

```APIDOC
## Common Patterns

### Check if latest deployment succeeded
```js
const cred = await API.getCredential('vercel-pat');
const { deployments } = await vercelGet('/v6/deployments?projectId=YOUR_PROJECT&limit=1&target=production');
const latest = deployments[0];
return { status: latest.state, url: latest.url, createdAt: new Date(latest.createdAt).toISOString() };
```

### Fetch recent error logs for a deployment
```js
const cred = await API.getCredential('vercel-pat');
const events = await vercelGet('/v2/deployments/DEPLOYMENT_ID/events?direction=backward&limit=200');
const errors = events.filter(e => e.level === 'error' || e.type === 'stderr');
return errors.map(e => e.text || e.payload?.text).filter(Boolean).join('\n');
```
```

--------------------------------

### Basic Usage with TransitionSeries

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/remotion/references/rules/light-leaks.md

Demonstrates how to integrate the LightLeak component within a TransitionSeries.Overlay for scene transitions. It reveals in the first half and retracts in the second half of its duration.

```APIDOC
## Basic usage with TransitionSeries

```tsx
import {TransitionSeries} from "@remotion/transitions";
import {LightLeak} from "@remotion/light-leaks";

<TransitionSeries>
  <TransitionSeries.Sequence durationInFrames={60}>
    <SceneA />
  </TransitionSeries.Sequence>
  <TransitionSeries.Overlay durationInFrames={30}>
    <LightLeak />
  </TransitionSeries.Overlay>
  <TransitionSeries.Sequence durationInFrames={60}>
    <SceneB />
  </TransitionSeries.Sequence>
</TransitionSeries>;
```
```

--------------------------------

### Get the latest release

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/github/SKILL.md

Retrieves information about the latest release of a repository.

```APIDOC
## GET /repos/{owner}/{repo}/releases/latest

### Description
Gets the latest release for the repository.

### Method
GET

### Endpoint
`/repos/{owner}/{repo}/releases/latest`
```

--------------------------------

### YAML Skill Description Example

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/skills/learn-skill/references/authoring-guide.md

Use this format for skill descriptions. It should clearly state what the skill does, when to use it, and include relevant trigger phrases and domain terms.

```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
```

--------------------------------

### Create a Log Channel with write()

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/skills/debug/SKILL.md

Use the `write` function to create an empty JSONL file for logging. The channel name must follow kebab-case rules.

```javascript
write('logs/react-renders.jsonl', '')
```

--------------------------------

### Get Disk Utilization

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/supabase/SKILL.md

Retrieves information about the disk space utilization for the project.

```APIDOC
## Get Disk Utilization

### Description
Returns disk utilization information.

### Method
GET

### Endpoint
/v1/projects/{ref}/config/disk/util
```

--------------------------------

### List organization projects

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/supabase/SKILL.md

Get a list of all projects associated with a particular organization.

```http
GET /v1/organizations/{slug}/projects
```

--------------------------------

### Open Minimal App in Sandbox

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/mini-apps/references/examples.md

Use the `API.openApp` function to launch a mini app from the sandbox environment.

```javascript
await API.openApp("hello");
```

--------------------------------

### Karton React Client Setup

Source: https://github.com/stagewise-io/stagewise/blob/main/packages/karton/README.md

Set up Karton for React applications using createKartonReactClient, providing hooks for state and procedures.

```typescript
import { createKartonReactClient } from '@stagewise/karton/react/client';

const [KartonProvider, useKarton] = createKartonReactClient<MyApp>({
  webSocketPath: 'ws://localhost:3000/path-for-karton-ws-connection',
  procedures: {
    notify: async (message) => {
      console.log('Server notification:', message);
    }
  },
  fallbackState: {
    counter: 0,
    users: []
  }
});

// In your app
function App() {
  return (
    <KartonProvider>
      <Counter />
    </KartonProvider>
  );
}

// In your components
function Counter() {
  const counter = useKartonState(s => s.counter);
  const increment = useKartonProcedure(p => p.increment);
  
  return (
    <div>
      <p>Counter: {counter}</p>
      <button onClick={() => increment()}>Increment</button>
    </div>
  );
}
```

--------------------------------

### Get a specific survey

Source: https://github.com/stagewise-io/stagewise/blob/main/apps/browser/bundled/plugins/posthog/SKILL.md

Retrieves details for a specific survey using its ID.

```APIDOC
## GET /api/projects/{project_id}/surveys/{id}/

### Description
Retrieves details for a specific survey using its ID.

### Method
GET

### Endpoint
/api/projects/{project_id}/surveys/{id}/
```