# PAPERMOTION

> **Words in motion. Stories in transition.**

PAPERMOTION is an automatic browser-based newspaper-style match-cut video generator inspired by classic broadsheet typography and cinematic optical match cuts. Enter any word or phrase (e.g. `AURA`, `FREEDOM`, `LOVE`, `DREAM`, `WORDS IN MOTION`), and PAPERMOTION automatically generates diverse newspaper articles, highlights the target text in vibrant newsprint yellow, computes match-cut camera trajectories, renders sequential animation frames, and encodes a real downloadable video directly in your browser.

Built with vanilla web standards (HTML5, CSS3, ES6+ JavaScript, WebCodecs, and Canvas 2D), PAPERMOTION operates 100% client-side without backend dependencies, mandatory accounts, or paid APIs, and is fully compatible with GitHub Pages.

---

## Quick Start: Automatic Match-Cut Video Generation

1. Open `index.html` in your web browser or start a local server:
   ```bash
   python3 -m http.server 8080
   ```
2. On the landing page hero bar, enter any target word or phrase:
   - Try single words: `AURA`, `FREEDOM`, `LOVE`, `DREAM`
   - Try multi-word phrases: `WORDS IN MOTION`, `BREAKING NEWS`, `MIDNIGHT CHRONICLE`
3. Click **Generate Video** (or click any of the instant preset pills).
4. Watch the real-time frame generation progress modal.
5. Preview the finished video in the player and click **Download Video (.mp4 / .webm)**!

---

## Grand Phase 02: Core Engine & Video Generation Architecture

Grand Phase 02 implements the complete automatic generation and encoding engine while strictly preserving all Grand Phase 01 design foundations and interfaces:

### Sub-Phases Implemented

1. **Sub-Phase 01 — Generator Integration & Input Processing (`input-processor.js`)**
   - Clean, validated input processing for single words and multi-word phrases.
   - Whitespace normalization and length validation.
   - Concurrency lock with cancellation support (`AbortController`).
2. **Sub-Phase 02 — Newspaper Text Generation Engine (`newspaper-generator.js` & `newspaper-templates.js`)**
   - Generates 8+ unique broadsheet editorial compositions per run across 6 archetypes (`lead-headline`, `dropcap-column`, `pullquote-editorial`, `subhead-banner`, `column-narrative`, `wire-bulletin`).
   - Authentic mastheads, volume markers, dates, cities, kickers, and dense multi-column prose.
3. **Sub-Phase 03 — Target Word Detection & Highlighting Engine (`text-matcher.js` & `highlight-engine.js`)**
   - Exact case-insensitive word-boundary matching (`\b`) preventing false-positive substrings.
   - Exact coordinate tracking of target bounding boxes via canvas text measurement.
   - High-contrast newsprint highlighter yellow (`#FFE600`) rendered behind black ink glyphs.
4. **Sub-Phase 04 — Newspaper Composition & Layout Engine (`layout-engine.js`)**
   - Off-screen high-definition broadsheet layout generator (1400×2000 virtual clipping canvas).
   - Authentic double-ruled mastheads, kickers, justified column text, and subtle paper texture.
5. **Sub-Phase 05 — Match-Cut Positioning & Camera Engine (`camera-engine.js`)**
   - Focuses and aligns the target word with the optical center of the video frame.
   - Dynamic scaling so the word prominently occupies 40%–60% of the screen width.
   - Continuous subtle camera push/drift and organic micro-jitter.
   - Optical 2-frame match-cut flash contrast transition between cuts.
6. **Sub-Phase 06 — Automatic Frame Generation Pipeline (`frame-generator.js`)**
   - Deterministic multi-frame generation (e.g. 90 frames for 3.0s at 30 FPS).
   - Full aspect ratio support: Portrait `9:16` (1080×1920), Landscape `16:9` (1920×1080), Square `1:1` (1080×1080), Portrait `4:5` (1080×1350).
   - Pre-loads web fonts (`document.fonts.ready`) for pixel-accurate text measurement.
7. **Sub-Phase 07 — Frame Rendering & Animation Pipeline (`frame-renderer.js`)**
   - Offscreen Canvas 2D frame rendering with camera coordinate matrices.
   - Soft lens vignette and analog newspaper contrast overlays.
8. **Sub-Phase 08 — Video Encoding & Export Engine (`video-encoder.js`)**
   - **Real H.264 MP4 Output**: Powered by browser-native WebCodecs `VideoEncoder` + bundled local `mp4-muxer`.
   - **WebM Output**: Native `MediaRecorder` canvas capture stream (`video/webm;codecs=vp9` or `vp8`).
   - Pure client-side processing without server roundtrips.
9. **Sub-Phase 09 — Video Preview & Download System (`video-exporter.js` & `generator-ui.js`)**
   - Video result modal with HTML5 video player (`controls autoplay loop`).
   - Instant one-click file download with clean filenames (e.g. `papermotion-AURA-1080x1920.mp4`).
   - Video metadata badges (Duration, Resolution, Frames, FPS, Format, File Size).
10. **Sub-Phase 10 — Generator Settings & Advanced Customization**
    - Configurable video duration (2.0s, 3.0s, 4.5s), resolution (1080p, 720p), FPS (24, 30, 60), and formats.

---

## Directory Structure

```text
PaperMotion/
├── index.html                  # Main application entry point & view container
├── README.md                   # Project documentation & overview
├── LICENSE                     # MIT License
├── assets/                     # Static media and brand assets
│   ├── fonts/                  # Local font storage directory
│   └── icons/                  # Vector graphics (favicon.svg, logo.svg)
├── src/
│   ├── css/
│   │   ├── variables.css       # Core design tokens, layout dimensions, transitions
│   │   ├── themes.css          # Dark Premium and Minimal White theme palettes
│   │   ├── layout.css          # Base reset, view switching, header, footer & grid
│   │   ├── components.css      # Buttons, badges, cards, inputs, modals, toasts, progress cards
│   │   ├── editor.css          # Workspace layout, sidebars, canvas stage & timeline
│   │   └── responsive.css      # Viewport media queries & mobile navigation drawer
│   └── js/
│       ├── app.js              # Application bootstrapper & global shortcuts
│       ├── theme.js            # Theme manager (Dark/Light, persistence, OS detection)
│       ├── navigation.js       # View router (Landing <-> Editor) & drawer controller
│       ├── editor.js           # Workspace state, word tokenizer, canvas preview, timeline
│       ├── components/
│       │   ├── modal.js        # Accessible modal dialog controller
│       │   └── toast.js        # Toast notification service
│       ├── data/
│       │   └── presets.js      # Curated editorial presets configuration data
│       ├── generator/          # GRAND PHASE 02: Core Engine & Video Generation
│       │   ├── input-processor.js      # Input sanitization, validation & concurrency lock
│       │   ├── newspaper-templates.js  # Curated broadsheet headlines, kickers & articles
│       │   ├── newspaper-generator.js  # Procedural broadsheet composition generator
│       │   ├── text-matcher.js         # Exact word-boundary matching & phrase parser
│       │   ├── highlight-engine.js     # Exact bounding geometry & yellow highlighter
│       │   ├── layout-engine.js        # Typesetting engine (masthead, columns, rules)
│       │   ├── camera-engine.js        # Match-cut optical alignment, zoom & camera drift
│       │   ├── frame-renderer.js       # Canvas 2D frame compositor with vignettes
│       │   ├── frame-generator.js      # Multi-frame sequential rendering pipeline
│       │   ├── video-encoder.js        # WebCodecs H.264 MP4 & MediaRecorder WebM
│       │   ├── video-exporter.js       # End-to-end video packaging & download pipeline
│       │   └── generator-ui.js         # UI bridge connecting hero input & export modals
│       └── vendor/
│           └── mp4-muxer.min.js        # Standalone local ISO BMFF MP4 container writer
└── docs/
    └── ARCHITECTURE.md         # Architecture, design principles & Phase 02 roadmap
```

---

## Keyboard Shortcuts

| Key | Action | Context |
| :--- | :--- | :--- |
| <kbd>T</kbd> | Toggle Theme (Dark Premium / Minimal White) | Global |
| <kbd>?</kbd> | Open Keyboard Shortcuts Help Modal | Global |
| <kbd>Esc</kbd> | Close Active Modal or Mobile Drawer | Global |
| <kbd>Space</kbd> | Play / Pause Timeline Simulation | Editor Workspace |
| <kbd>1</kbd> | Switch Aspect Ratio to 16:9 Landscape | Editor Workspace |
| <kbd>2</kbd> | Switch Aspect Ratio to 9:16 Vertical (Stories/Reels) | Editor Workspace |
| <kbd>3</kbd> | Switch Aspect Ratio to 1:1 Square | Editor Workspace |
| <kbd>4</kbd> | Switch Aspect Ratio to 4:5 Portrait | Editor Workspace |

---

## License

PAPERMOTION is released under the [MIT License](LICENSE).
