🎬 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

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

import { ScriptBreakdownSceneView, useScriptBreakdownScene } from "@vishu1301/script-writing";

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

Shot Breakdown

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

npm install @vishu1301/script-writing

Designed with ❤️ for the next generation of storytellers.