@vishu1301/script-writing 1.5.5 → 1.5.7

package/README.md

@@ -1,61 +1,120 @@
-# Script Writing & Breakdown Library
+# 🎬 Script Writing & Breakdown Library
 
-An advanced, React and Next.js-based script writing and breakdown analysis library for the web.
+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.
 
-This package provides developers with an intuitive suite of tools to draft, edit, and format scripts according to industry standards, alongside powerful script and shot breakdown utilities to highlight, tag, and analyze scene elements for pre-production.
+---
 
-## Core Modules
+## 📌 Scope & Objective
 
-The library is divided into three primary modules: **Screenplay Editor**, **Script Breakdown**, and **Shot Breakdown**. Each module exposes headless hooks for robust state management and pre-built React views for rapid UI integration.
+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.
 
-### 1. Screenplay Editor
-Draft, edit, and format screenplays with an intuitive WYSIWYG editor.
-- **Industry-Standard Formatting:** Automatically formats text to screenplay guidelines, dynamically handling Scene Headings, Action, Character, Parenthetical, Dialogue, and Transitions.
-- **Smart Auto-Suggestions:** Intelligently suggests previously used Characters, Locations, and Character Extensions (like V.O., O.S.) as you type.
-- **PDF Import & Export:** Built-in utilities to import existing scripts from PDFs (`pdfjs-dist`) and export drafts into beautifully formatted screenplay PDFs (`html2canvas-pro` & `jsPDF`).
-- **Keyboard Shortcuts:** Fluid writing experience utilizing familiar keyboard shortcuts (e.g., `Ctrl + ↑/↓` to change block types, `Enter` for smart block transitions).
-- **Core Exports:** `useScreenplayEditor` (Hook), `ScreenplayEditorView` (Component).
+### 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.
 
-### 2. Script Breakdown
-Analyze and tag script elements to prepare for scheduling and production.
-- **Interactive Scene Viewer:** View parsed scripts in breakdown mode where text is immutable but fully interactive.
-- **Element Tagging:** Select blocks of text to tag them as Cast, Props, Wardrobe, VFX, Vehicles, Extras, etc.
-- **Color-Coded Analysis:** Industry-standard color-coded highlighting applied automatically as elements are tagged.
-- **Core Exports:** `useScriptBreakdownScene` (Hook), `ScriptBreakdownSceneView` (Component).
+---
 
-### 3. Shot Breakdown
-Visually plan camera work, cinematography, and storyboarding shot-by-shot linked directly to the screenplay text.
-- **Multi-Camera Management:** Initialize your digital production with multiple cameras and easily swap between them when assigning shots.
-- **Extensive Shot Configuration:** Detailed properties for each shot covering Core Identification, Optics & Mechanics (Lens, Movement, Support, Aperture), Visual Composition (Framing, Depth of Field), and Narrative Context (Lighting, Sound, VFX, Emotional Purpose).
-- **Text-to-Shot Mapping:** Highlight specific script sections on the editor space to directly bind them to newly created shots, dynamically overlaying shot durations on the script.
-- **Core Exports:** `useShotBreakdownScene` (Hook), `ShotBreakdownSceneView` (Component).
+## 🛠 How It Works: The Technical Perspective
 
-## Installation
+Built with **React** and **Next.js**, the library follows a "Headless Logic, Styled View" architecture.
 
-Install the package via npm, yarn, or pnpm:
+### 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.
 
-```bash
-npm install @vishu1301/script-writing
-```
+### 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.
 
-## Quick Start
-*Note: The UI views utilize standard Tailwind CSS utility classes and Lucide React icons.*
+**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.
 
-### Screenplay Editor Example
+### 4. Implementation Examples
+
+#### Screenplay Editor
 ```tsx
 import { ScreenplayEditorView, useScreenplayEditor } from "@vishu1301/script-writing";
 
-export default function ScriptApp() {
-  const editorProps = useScreenplayEditor();
+export default function Page() {
+  const editor = useScreenplayEditor({
+    onSave: (data) => console.log("Script JSON:", data)
+  });
   
-  return (
-    <div className="w-full min-h-screen bg-zinc-50">
-      <ScreenplayEditorView {...editorProps} />
-    </div>
-  );
+  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} />;
 }
 ```
 
-## Developer Notes
+---
+
+## 🎨 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
+```
 
-This package relies heavily on data attributes and high-specificity style injection to force screenplay fonts (Courier Prime). For customized font integration or headless implementation, utilize the provided hooks to map output block objects into your custom interface.
+*Designed with ❤️ for the next generation of storytellers.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vishu1301/script-writing",
-  "version": "1.5.5",
+  "version": "1.5.7",
   "type": "module",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",