# 🎬 Script Writing & Breakdown Library

A high-performance, industry-standard documentation for `@vishu1301/script-writing`. This library is designed to bridge the gap between creative writing and technical pre-production.

---

## 📌 Scope & Objective

The **Script Writing & Breakdown Library** is an all-in-one suite for filmmakers, screenwriters, and production teams. It transforms the traditionally fragmented process of writing, breaking down, and shot-listing into a unified digital workflow.

### Problems It Solves:
1. **Formatting Friction**: Screenwriters often waste 30% of their time on margins and indentation. This library automates industry-standard formatting.
2. **Disconnected Workflows**: Breakdown sheets and shot lists are usually separate documents. Here, they are dynamically linked to the live screenplay.
3. **Multilingual Barriers**: Native storytelling in Indic languages (Hindi, Gujarati) is often hard due to lack of specialized editors. Our phonetic engine solves this.
4. **Data Silos**: Pre-production data (Cast, Props, VFX) is extracted directly from the text, ensuring nothing is missed.

---

## 🛠 How It Works: The Technical Perspective

Built with **React** and **Next.js**, the library follows a "Headless Logic, Styled View" architecture.

### 1. The Architecture
- **State Management**: Heavy lifting is done via custom hooks (`useScreenplayEditor`, `useScriptBreakdown`). These manage the nested JSON tree representing the screenplay.
- **Deterministic Finite State Machine (DFSM)**: The `MultilingualInputService` uses a DFSM to handle complex phonetic sequences (e.g., typing `k + h` results in `ख`) in real-time without lag.
- **Virtual DOM Interaction**: Uses data-attributes and CSS-in-JS to enforce "Courier Prime" typography while maintaining a content-editable environment.

### 2. Core Technical Stack
- **Parsing**: Advanced regex and sequence analysis for automatic block type detection.
- **PDF Engine**:
    - **Import**: Uses `pdfjs-dist` to reverse-engineer standard PDF layouts back into editable JSON blocks.
    - **Export**: Combines `html2canvas-pro` for high-fidelity rendering and `jsPDF` for multi-page document generation.
- **Data Binding**: Shots are linked to script fragments via unique ID mapping, allowing "Text-to-Shot" overlays.

### 3. The DFSM Architectural Edge
At the heart of the multilingual engine is a **Deterministic Finite State Machine (DFSM)**. Traditionally, handling complex Indic scripts (like Hindi or Gujarati) in a web editor leads to "State Hell" due to overlapping keystrokes.

**How DFSM solves the architecture:**
- **State Isolation**: Every keystroke (e.g., typing 'k' then 'h') is a transition between predefined states. This prevents unexpected character garbling.
- **Look-back Logic**: The machine remembers the `prevChar` and current `state`, allowing it to transform `k + h` into `ख` or `ક + h` into `ખ` with 100% predictability.
- **Zero Latency**: By mapping transitions in a flat configuration, we achieve $O(1)$ transformation speed, ensuring the editor feels as snappy as a native OS keyboard.
- **Headless Linguistic Layer**: The logic is entirely decoupled from the React lifecycle, allowing the engine to be tested in isolation and reused across different UI components.

### 4. Implementation Examples

#### Screenplay Editor
```tsx
import { ScreenplayEditorView, useScreenplayEditor } from "@vishu1301/script-writing";

export default function Page() {
  const editor = useScreenplayEditor({
    onSave: (data) => console.log("Script JSON:", data)
  });
  
  return <ScreenplayEditorView {...editor} />;
}
```

#### Script Breakdown
```tsx
import { ScriptBreakdownSceneView, useScriptBreakdownScene } from "@vishu1301/script-writing";

export default function Page() {
  const breakdown = useScriptBreakdownScene({ scene_url: "scene_1.sbx" });
  return <ScriptBreakdownSceneView {...breakdown} />;
}
```

#### Shot Breakdown
```tsx
import { ShotBreakdownView, useShotBreakdownScene } from "@vishu1301/script-writing";

export default function Page() {
  const shots = useShotBreakdownScene({ 
    scene_url: "scene_1.sbx",
    preloadedCameras: [{ name: "A-Cam" }] 
  });
  return <ShotBreakdownView {...shots} />;
}
```

---

## 🎨 How It Works: The Non-Technical Perspective

If you can use Google Docs, you can write a feature film here.

### 1. For Screenwriters (The Flow)
- **Tab & Enter System**: Press **Enter** to move to the next logical block (e.g., Character → Dialogue). Press **Tab** to cycle through formatting types (e.g., Action → Character).
- **Auto-Complete**: The system remembers your characters and locations. Type "J" and it suggests "JACK" and "JACK'S APARTMENT".
- **Phonetic Typing**: Type in English (hinglish/gujlish) and watch it turn into beautiful Hindi or Gujarati script instantly.

### 2. For Directors & DPs (Shot Breakdown)
- **Visual Mapping**: Highlight a sentence in the script and click "Add Shot". That sentence is now linked to a camera setup.
- **Lens & Movement**: Add technical details like "50mm Prime", "Dolly In", or "Low Angle" in a structured sidebar that populates your shot list automatically.

### 3. For ADs & Producers (Script Breakdown)
- **Color Tagging**: Highlight "Red Dress" and tag it as **Wardrobe**. It instantly highlights in the standard production color (Purple) and adds it to your scene's breakdown sheet.
- **Scene Analysis**: The system automatically counts scenes, pages, and locations, giving you a bird's-eye view of your production complexity.

---

## 🚀 Key Modules

| Module | Purpose | Key Feature |
| :--- | :--- | :--- |
| **Screenplay Editor** | Writing & Formatting | Smart Auto-Suggestions & PDF Import |
| **Script Breakdown** | Tagging & Logistics | Interactive Element Highlighting |
| **Shot Breakdown** | Cinematography | Text-to-Shot Dynamic Mapping |
| **Multilingual Engine**| Native Storytelling | Professional Phonetic Transliteration |

---

## 📥 Installation

```bash
npm install @vishu1301/script-writing
```

*Designed with ❤️ for the next generation of storytellers.*