# StageType

> StageType is a free, static, offline-capable screenplay editor for students, playwrights, filmmakers and producers, hosted on GitHub Pages (`https://www.stagetype.com/`). Writers write their story while StageType automatically formats the screenplay (Scene Heading, Action, Character, Parenthetical, Dialogue, Transition), paginates for A4 or US Letter, exports submission-ready PDFs, and provides integrated shot plans, storyboards, timed animatics, lighting plans, and character relationship maps. No account is required, and scripts stay on the user's device.

**No AI in StageType.** StageType has no AI features and no AI integrated into the application in any form. It never sends script text to AI services. This `llms.txt` file is only a guide for LLMs that access, review or prepare content for this site.

## Key Pages & Documentation

- [Home Page](https://www.stagetype.com/): Overview, feature walkthrough screenshots, and 3-step quick start.
- [Screenplay Editor (`app.html`)](https://www.stagetype.com/app.html): The browser-based screenplay editor, shot planner, storyboard/animatic player, and character planner.
- [Humpty Dumpty Sample Script in Editor (`app.html#sample`)](https://www.stagetype.com/app.html#sample): Opens an editable copy of the "Humpty Dumpty" sample script with 3 scenes, 12 shots, storyboard frames, and character profiles.
- [Humpty Dumpty Sample Script JSON (`humpty-dumpty.stagetype.json`)](https://www.stagetype.com/humpty-dumpty.stagetype.json): Complete, reference `.stagetype.json` file for the "Humpty Dumpty" sample script (3 scenes, 62 blocks across all 6 element types, 12 linked shots, 4 character profiles with relationships, and 3 lighting set-ups).
- [About & How It Works (`about.html`)](https://www.stagetype.com/about.html): Screenplay writing workflow, keyboard shortcuts, features, and LLM script-to-JSON conversion instructions.
- [Help & Step-by-Step Guides (`docs/`)](https://www.stagetype.com/docs/): Visual guides with annotated screenshots and walkthrough videos.
- [Privacy Statement (`privacy.html`)](https://www.stagetype.com/privacy.html): Local-first storage (IndexedDB), optional Google Drive (`drive.file`), and privacy guarantees.
- [AI Policy (`ai.txt`)](https://www.stagetype.com/ai.txt): AI crawler permissions and privacy rules.
- [Humans (`humans.txt`)](https://www.stagetype.com/humans.txt): Credits, technology stack, and standards.

---

## Instructions for LLMs: Converting an Existing Script into StageType JSON (`.stagetype.json`)

When a user asks you (an LLM) to convert an existing screenplay, stage play, dialogue transcript, prose scene, Fountain file, Final Draft export, or outline into JSON for **StageType**:

1. **Output a single valid JSON object** matching StageType's `schemaVersion: 4` document format described below.
2. Tell the user to save the JSON output as a file ending in **`.stagetype.json`** (for example, `my-script.stagetype.json`) and open it in StageType via **File → Open script file…** (or **My scripts → Open script file…**) at `https://www.stagetype.com/app.html`.
3. **Never invent or omit student story content** unless the user explicitly asks you to write or adapt scenes. Preserve every scene, action beat, character cue, parenthetical, dialogue line, and transition in exact reading order.

### 1. Top-Level JSON Structure

A `.stagetype.json` file is a UTF-8 JSON object with the following top-level properties:

```json
{
  "schemaVersion": 4,
  "id": "script-unique-id-001",
  "createdAt": "2026-11-02T00:00:00.000Z",
  "updatedAt": "2026-11-02T00:00:00.000Z",
  "titlePage": {
    "title": "Script Title",
    "credit": "Written by",
    "author": "Writer Name",
    "source": "",
    "draftDate": "",
    "contact": ""
  },
  "settings": {
    "paperSize": "a4",
    "storyboardFormat": "widescreen",
    "storyboardPaper": "a4",
    "storyboardOrientation": "landscape"
  },
  "blocks": [
    { "id": "b1", "type": "scene", "text": "INT. LOCATION - DAY" }
  ],
  "shots": [],
  "characters": [],
  "lighting": [],
  "assets": []
}
```

### 2. Required Fields & Validation Rules (`validateDocument`)

StageType validates every imported file strictly before opening it. Follow these exact rules so validation succeeds:

- **`schemaVersion`** *(required integer)*: Must be `4` (versions `1` to `4` are accepted; always generate `4`).
- **`id`** *(required non-empty string)*: A unique document identifier, such as a UUID (`"550e8400-e29b-41d4-a716-446655440000"`) or slug (`"script-the-torn-envelope"`).
- **`createdAt` / `updatedAt`** *(strings)*: ISO-8601 timestamps (e.g., `"2026-11-02T12:00:00.000Z"`).
- **`titlePage`** *(object)*: All 6 fields must be strings (use `""` when unknown; never `null`):
  - `title`: The screenplay title (e.g., `"The Torn Envelope"`).
  - `credit`: Usually `"Written by"` (or `""`).
  - `author`: Writer's name (or `""`).
  - `source`: Adaptation credit if applicable, e.g., `"Based on..."` (or `""`).
  - `draftDate`: Draft label or date, e.g., `"First draft"` (or `""`).
  - `contact`: Optional contact details (default to `""` for student privacy).
- **`settings`** *(object)*:
  - `paperSize`: `"a4"` *(default)* or `"letter"`.
  - `storyboardFormat`: `"widescreen"` *(default, 16:9)*, `"cinema"` *(2.39:1)*, `"classic"` *(4:3)*, `"square"` *(1:1)*, or `"vertical"` *(9:16)*.
  - `storyboardPaper`: `"a4"` *(default)* or `"a3"`.
  - `storyboardOrientation`: `"landscape"` *(default)* or `"portrait"`.
- **`blocks`** *(required non-empty array)*: The ordered screenplay elements. Every item must be `{ "id": "<unique-string>", "type": "<block-type>", "text": "<string>" }`.

### 3. Screenplay Block Types (`blocks[].type`)

Each block's `type` **must** be one of these six exact lowercase strings:

1. **`"scene"`** — **Scene Heading (Slugline)**
   - Format: Uppercase `INT.`, `EXT.`, `INT./EXT.`, `EXT./INT.`, `I/E.`, or `EST.`, followed by the location, ` - `, and the time of day.
   - Examples: `"INT. SCHOOL CLASSROOM - DAY"`, `"EXT. CAR PARK - NIGHT"`, `"INT. HALLWAY - CONTINUOUS"`.
   - Do not include scene numbers inside `text`.

2. **`"action"`** — **Action / Description**
   - Format: Normal sentence case describing what the audience sees and hears in the present tense.
   - Create a separate `"action"` block for each paragraph. Do not put newline characters (`\n`) inside `text` and do not add leading spaces for indentation.
   - Example: `"SAM, 16, hides a torn envelope beneath his notebook."`

3. **`"character"`** — **Character Cue**
   - Format: Uppercase speaker name positioned immediately before their `"parenthetical"` or `"dialogue"` block.
   - Voiceover and off-screen extensions go in parentheses at the end of the cue: `"MAYA"`, `"SAM (O.S.)"`, `"NARRATOR (V.O.)"`.
   - Do **not** append `(CONT'D)` for page breaks; StageType computes `(MORE)` and `(CONT'D)` automatically during pagination.
   - If the source script has `SAM: What are you hiding?`, split it into two blocks: a `"character"` block (`"SAM"`) followed by a `"dialogue"` block (`"What are you hiding?"`).

4. **`"parenthetical"`** — **Parenthetical Direction**
   - Format: Brief delivery or action note wrapped in parentheses, e.g., `"(too quickly)"`, `"(whispering)"`, `"(to Maya)"`.
   - Placed after a `"character"` block (or between two `"dialogue"` blocks when a speech has a mid-speech pause/direction).

5. **`"dialogue"`** — **Dialogue**
   - Format: Normal sentence case for the character's spoken words.
   - Do **not** wrap the entire speech in quotation marks (`"..."`) unless the character is quoting something inside their speech.
   - Example: `"What are you hiding?"`

6. **`"transition"`** — **Transition**
   - Format: Uppercase editing or scene transition, e.g., `"CUT TO:"`, `"DISSOLVE TO:"`, `"SMASH CUT TO:"`, `"FADE OUT."`.
   - Only include transitions that exist in the source script; ordinary scene changes do not require a transition block.

### 4. Optional Shot Plan (`shots[]`)

Usually `"shots": []` when converting a text script. If the user also provides a shot list or asks you to plan shots for each scene, include objects with these exact fields and allowed values:

```json
{
  "id": "shot-1",
  "sceneId": "b1",
  "size": "WS",
  "angle": "Eye level",
  "movement": "Static",
  "lens": "35mm",
  "description": "Establishing shot of the classroom through the rain-streaked window.",
  "durationSec": 4,
  "blockIds": ["b2", "b3"],
  "frame": null,
  "lightingSetupId": ""
}
```

- `id`: Unique string ID (e.g., `"shot-1"`).
- `sceneId`: **Must** equal the `id` of the `"scene"` block this shot belongs to.
- `size`: One of `"EWS"` (Extreme wide), `"WS"` (Wide), `"FS"` (Full), `"MS"` (Medium), `"MCU"` (Medium close-up), `"CU"` (Close-up), `"ECU"` (Extreme close-up), `"OTS"` (Over the shoulder), `"POV"` (Point of view), `"2S"` (Two-shot), `"INSERT"` (Insert).
- `angle`: One of `"Eye level"`, `"High"`, `"Low"`, `"Overhead"`, `"Dutch"`.
- `movement`: One of `"Static"`, `"Pan"`, `"Tilt"`, `"Dolly"`, `"Tracking"`, `"Zoom"`, `"Handheld"`, `"Crane"`.
- `lens`: One of `""`, `"14mm"`, `"18mm"`, `"24mm"`, `"35mm"`, `"50mm"`, `"85mm"`, `"135mm"`, `"200mm"`.
- `durationSec`: Number from `0.5` to `600` (rounded to 0.1s; default `4`).
- `blockIds`: Array of `blocks[].id` strings covered by this shot (when linking dialogue, include both the `"character"` block ID and its `"parenthetical"` / `"dialogue"` block IDs).
- `frame`: Always `null` for text-only LLM conversions.
- `lightingSetupId`: `""`, or the `id` of a `lighting[]` set-up with the **same** `sceneId`.

### 5. Optional Character Profiles (`characters[]`)

Usually `"characters": []` unless character bios/notes are present or requested. StageType automatically detects all speaking characters from `"character"` blocks, so `characters` is only needed for planning profiles and relationship maps:

```json
{
  "id": "char-sam",
  "name": "SAM",
  "role": "protagonist",
  "age": "16",
  "description": "Quiet student carrying a secret.",
  "traits": ["Guarded", "Observant"],
  "want": "To keep the envelope hidden until after school.",
  "need": "To ask Maya for help.",
  "flaw": "Tries to solve everything alone.",
  "internalConflict": "Fear of being found out vs. loyalty to Maya.",
  "externalConflict": "Maya noticing the torn envelope.",
  "arc": "Opens up and shares the truth.",
  "notes": "",
  "frameShape": "portrait",
  "portrait": null,
  "relationships": [
    {
      "id": "rel-sam-maya",
      "targetId": "char-maya",
      "type": "friend",
      "note": "Best friends since primary school."
    }
  ]
}
```

- `name`: Uppercase base character name **without** `(V.O.)` or `(O.S.)` extensions (max 80 chars, unique per character).
- `role`: One of `""`, `"protagonist"`, `"antagonist"`, `"supporting"`, `"minor"`.
- `traits`: Array of up to 24 short strings (max 40 chars each).
- `frameShape`: `"portrait"`, `"square"`, or `"landscape"`.
- `portrait`: `null`.
- `relationships[].targetId`: Must match another character profile's `id` in `characters[]`.
- `relationships[].type`: One of `"family"`, `"friend"`, `"romance"`, `"mentor"`, `"ally"`, `"rival"`, `"enemy"`, `"colleague"`, `"other"`.

### 6. Optional Lighting Plan (`lighting[]`)

Usually `"lighting": []`. If the user asks for a lighting plan, add one or more set-ups per scene:

```json
{
  "id": "light-1",
  "sceneId": "b1",
  "name": "Rainy afternoon",
  "timeOfDay": "Day",
  "mood": "Low-key",
  "notes": "Window light only; keep the room dim.",
  "lights": [
    { "id": "l1", "role": "Key", "type": "Window / sun", "colourTemp": "5600K", "gel": "", "intensity": 80, "note": "Through the classroom window", "x": 0.2, "y": 0.3, "angle": 30 }
  ],
  "subjects": [
    { "id": "p1", "label": "SAM", "characterId": "", "x": 0.5, "y": 0.4 }
  ],
  "camera": { "x": 0.5, "y": 0.9, "angle": 270 },
  "reference": null
}
```

- `sceneId`: **Must** equal the `id` of the `"scene"` block this set-up belongs to.
- `timeOfDay`: One of `""`, `"Dawn"`, `"Morning"`, `"Day"`, `"Golden hour"`, `"Dusk"`, `"Night"`, `"Interior only"`.
- `mood`: One of `""`, `"Natural"`, `"High-key"`, `"Low-key"`, `"Soft"`, `"Hard"`, `"Silhouette"`, `"Chiaroscuro"`, `"Colourful"`.
- `lights[]` (up to 12): `role` one of `"Key"`, `"Fill"`, `"Back"`, `"Practical"`, `"Background"`, `"Bounce"`; `type` one of `"LED panel"`, `"Fresnel"`, `"Softbox"`, `"Tube light"`, `"Lamp"`, `"Window / sun"`, `"Reflector"`, `"Phone torch"`; `colourTemp` one of `""`, `"2700K"`, `"3200K"`, `"4300K"`, `"5600K"`, `"6500K"`; `intensity` 0–100.
- `x` / `y`: Position on the top-down plan from `0` to `1` (`x` left → right, `y` back of the set → camera side). `angle`: degrees clockwise from pointing right (`90` points towards the camera side, `270` away from it).
- `subjects[]` (up to 8): people on the plan; `characterId` is `""` or the `id` of a `characters[]` profile.
- `reference`: `null`.

### 7. Reference Example: The "Humpty Dumpty" Sample Script (`.stagetype.json`)

Use StageType's built-in **"Humpty Dumpty"** sample script as your canonical reference when converting or formatting scripts:
- **Complete 3-scene JSON file** (with all 62 blocks, 12 linked shots, 4 character profiles, and 3 lighting set-ups): [`https://www.stagetype.com/humpty-dumpty.stagetype.json`](https://www.stagetype.com/humpty-dumpty.stagetype.json)
- **Open live in the editor**: [`https://www.stagetype.com/app.html#sample`](https://www.stagetype.com/app.html#sample)

Below is a complete, valid `.stagetype.json` excerpt from the **"Humpty Dumpty"** sample script demonstrating every block type (`scene`, `action`, `character` with `(V.O.)`, `parenthetical`, `dialogue`, `transition`), linked `shots`, and `characters`:

```json
{
  "schemaVersion": 4,
  "id": "sample-humpty-dumpty",
  "createdAt": "2026-11-02T00:00:00.000Z",
  "updatedAt": "2026-11-02T00:00:00.000Z",
  "titlePage": {
    "title": "Humpty Dumpty",
    "credit": "Written by",
    "author": "The StageType Team",
    "source": "Based on the traditional nursery rhyme",
    "draftDate": "Sample script",
    "contact": ""
  },
  "settings": {
    "paperSize": "a4",
    "storyboardFormat": "widescreen",
    "storyboardPaper": "a4",
    "storyboardOrientation": "landscape"
  },
  "blocks": [
    {
      "id": "scene1",
      "type": "scene",
      "text": "EXT. CASTLE WALL - DAY"
    },
    {
      "id": "s1-wall",
      "type": "action",
      "text": "A tall stone wall runs along the edge of a castle garden. The sun is out."
    },
    {
      "id": "s1-humpty",
      "type": "action",
      "text": "HUMPTY DUMPTY, a large egg in a small red bow tie, sits on the very top with his legs swinging."
    },
    {
      "id": "s1-narrator-cue",
      "type": "character",
      "text": "NARRATOR (V.O.)"
    },
    {
      "id": "s1-narrator",
      "type": "dialogue",
      "text": "Humpty Dumpty sat on a wall. He did this every day, and every day somebody told him not to."
    },
    {
      "id": "s1-captain-arrives",
      "type": "action",
      "text": "Below, the CAPTAIN of the guard marches past, stops, and shades her eyes."
    },
    {
      "id": "s1-cap1-cue",
      "type": "character",
      "text": "CAPTAIN"
    },
    {
      "id": "s1-cap1",
      "type": "dialogue",
      "text": "Morning, Humpty. That wall is very high."
    },
    {
      "id": "s1-hum2-cue",
      "type": "character",
      "text": "HUMPTY DUMPTY"
    },
    {
      "id": "s1-hum2-paren",
      "type": "parenthetical",
      "text": "(waving her away)"
    },
    {
      "id": "s1-hum2",
      "type": "dialogue",
      "text": "I have sat up here for years. Nothing is going to..."
    },
    {
      "id": "s1-fall",
      "type": "action",
      "text": "He tips backwards, very slowly, and is gone."
    },
    {
      "id": "s3-fade",
      "type": "transition",
      "text": "FADE OUT."
    }
  ],
  "shots": [],
  "characters": [],
  "lighting": [],
  "assets": []
}
```