KolyadaPages 1.0.0 — illustrated manual

1. Before you start

Prerequisites: a desktop computer with Google Chrome. Nothing else is needed. You don't need to install anything, create an account or connect to the internet. Unzip KolyadaPages-1.0.0.zip and double-click KolyadaPages.html. If it opens in another program, right-click it and choose “Open with → Google Chrome”.

When to adopt it: lock the rehearsal edition before you print binders, then print the binders from the KolyadaPages PDF. KolyadaPages lays out pages itself. It cannot reproduce the page numbers of a script that was already printed from Word, Final Draft or a PDF.

Tested on: Google Chrome 152 in headless mode on Linux (kernel 5.15), at 1440×900 and 390×844 windows; screenshots in this manual come from those runs. Other browsers, macOS, Windows and physical printers have not been tested. Exported PDFs were checked with PyMuPDF and pypdf.

2. First result with the sample (5 minutes)

Click ▶ Try the sample play. The original fictional one-act The Lantern Keeper’s Inventory loads as a draft.
Check the summary (55 paragraphs, 3 scene headings, 4 speaker names, 6 pages) and click 🔒 Lock rehearsal edition.
Open 2 Review and click ▶ Load sample revision 1 (Blue).
Expected result: 6 changes · 5 page groups to replace · 6 replacement pages · full script 7 pages. The replacement pages are 1, 2, 2A, 4 (OMITTED), 5 and 6.
Click ✔ Commit revision 1 (Blue), then ⬇ Download distribution ZIP and 💾 Save project file.
Optional: in Review, load sample revision 2 (Pink). Expected: 4 changes; pages 2, 4 and 6 are replaced; 2A disappears; page 4 returns with text.

KolyadaPages start screen with Try the sample play, Choose a TXT script and Open a project file buttons, and the Open project and New project buttons in the top bar — Start screen. The adoption note is shown beside the first import. The top bar keeps **📂 Open project…** and **✚ New project** available in every step.

Lock step showing title, edition name, date, counts and the speaker table — Lock step: check the title, edition colour, date, counts and speakers before locking.

3. Writing your TXT script

Use a plain-text file saved as UTF-8 (in Word: File → Save As → Plain Text, encoding Unicode UTF-8). Rules:

TITLE: The Lantern Keeper's Inventory

SCENE 1. The lamp room. Dusk.

(Stage directions start with a round or square bracket.)

MARA: A speech is the NAME in capitals, a colon, then the text.
A line directly below, with no blank line, continues the same speech.

MARA (CONT'D): Extensions in brackets, such as (CONT'D), are kept.

Scene headings start with an upper-case ACT, SCENE, PROLOGUE or EPILOGUE.
Speaker names are upper case and have at most 30 characters. Any upper-case word followed by a colon at the start of a line is read as a speaker.
A line that is none of these (after a blank line) is treated as a stage direction, and the review counts it as a warning.
Normalization: line endings, tabs, no-break spaces and repeated spaces become single spaces. The exact original file is kept in the project file. Use Download original draft text in the Distribute step to get it back.
Characters must be printable in Windows-1252 (English and Western European letters, curly quotes, dashes, €). Other characters, such as emoji or Cyrillic, block locking and are listed with their line and code point.

4. Lock your own script

Click Choose a TXT script… in the Lock step. Check the counts and the page preview. If the same performer appears under two printed names, use the Role column (for example “same role as INSPECTOR”) so their character sheets are combined. The printed text does not change. Enter the edition colour and date, then lock. Download the ZIP in Distribute and print binders from rev00-full-script.pdf.

5. Review a revised draft

In 2 Review, choose the playwright’s new TXT draft. Nothing changes until you commit. The review shows:

Page strip: every primary page group, marked ✓ Unchanged, ✎ Changed, ✎ Grows (A pages), Restored or ⊘ Omitted. The marks are text and symbols, not colour alone.
Changes: number, page, type (Changed, Added, Cut, Speaker changed), flags (stage-direction, possible-move, scene-heading, speaker-change), scene and a word-level old → new view. You can filter by character or type.
Previous and proposed pages of the selected group side by side. Changed lines carry a margin asterisk.

Review step with revision name, date, change counts and the speaker table — Review of sample revision 1: 6 changes, 5 groups, 6 replacement pages.

Side-by-side previous page 2 and proposed pages 2 and 2A with asterisks on new speeches — Group 2: the issued page (left) and the proposed pages 2 and 2A (right). The new MARA and ODILE speeches carry asterisks.

Review step on a narrow 390 pixel wide window with stacked controls — The same workflow on a 390-pixel-wide window.

If the draft is identical to the current script, the review says No changes and commit stays disabled. The program pairs paragraphs automatically, and it can misjudge a moved or heavily rewritten speech. Read every change before you commit.

6. Distribute and save

After committing, the 3 Distribute step lists every committed edition. Choose an edition, the paper size (US Letter or A4) and optionally the binder holders (one name per line, up to 50). Then download the ZIP. Save the project file after every commit. The next revision must build on it.

Distribute step with committed editions table, paper size, recipients and download buttons — Distribute: committed editions, paper size, recipients, ZIP and project file.

7. What is in the distribution ZIP

File	Use
`revNN-full-script.pdf`	Complete current script for new cast, understudies and designers. Untouched pages are identical to the copies already in binders.
`revNN-replacement-pages.pdf`	Only the changed groups, complete, in binder order, including OMITTED placeholders.
`revNN-change-log.txt` / `.csv`	Page, old page, scene, type, old/new speaker and role, old/new text and flags. The TXT is ready to paste into a rehearsal report.
`revNN-character-changes.txt` / `.pdf`	One section per role, with the cue before each change. Stage directions are listed for the company. Roles without changes say “No changes in this revision.”
`revNN-swap-checklist.txt` / `.pdf`	For each changed group, remove all previously issued pages and insert the complete new group. Includes tick boxes for each listed recipient.
`manifest.json`	Revision, counts and the SHA-256 of each file. Hashes identify files; they are not a signature.

The rehearsal-edition ZIP (rev00) contains the full script, a roles list and the manifest.

CSV safety: any cell starting with =, +, -, @, a tab or a carriage return gets a leading apostrophe (') so spreadsheets do not run it as a formula. The TXT files and the project file keep the exact text.

Rendered replacement page 2 from the exported PDF with revision header and margin asterisks — Actual exported page 2 of revision 1 (rendered from the PDF). It has a revision header and asterisks in the right margin.

Rendered top of the swap checklist PDF listing remove and insert pages per group — Actual swap checklist from revision 1.

8. Page rules

Pages use Courier 12 pt, 60 columns and 50 lines at 12 pt spacing, with the same line layout on Letter and A4. The left margin is 1 inch. Body text ends at least 1.25 inches from the right edge and 1.5 inches from the bottom. The header sits about 0.7 inch from the top, and revision asterisks are printed in the right margin.
The locked edition defines numbered primary page groups. A revision lays out again only the groups it touches. Text that grows past the page creates 2A, 2B… (up to J). A group whose text is all cut becomes 4 OMITTED.
New text joins the page group of the text before it. If the text before it is followed by an emptied or omitted group, the new text goes into that group, so you can restore cut material deliberately.
The same speech is not guaranteed to stay on the same A-page across revisions. This is why the checklist always swaps whole groups.
Untouched groups keep their pages, labels, revision headers and earlier asterisks exactly.

9. Reopen a project or start another

Click 📂 Open project… in the top bar (or Open a project file… on the start screen) and choose your .kolyada.json. The top-bar button works in every step, including after you have locked an edition or while a draft is shown. KolyadaPages checks the structure, limits and SHA-256 of each stored draft. It then re-creates every edition from the drafts and compares the page labels. If the file is refused, a message explains why. The project that was already open stays exactly as it was.

✚ New project clears the window so that you can lock another play. If the current project has committed work that you have not saved in a project file, both buttons first ask you to Save current project first, continue without saving, or cancel. Chrome also warns before you close the tab in that state.

The SHA-256 values detect accidental or careless edits; they are not a signature. A file edited deliberately and consistently, with matching hashes and page labels, opens as a different project. Keep your own backup copies of project files.

10. Limits

Each maximum below is accepted exactly; one more is refused with the message shown, and nothing in the open project changes.

Item	Maximum	What you see when it is exceeded
Draft file	2 MiB (2,097,152 bytes) of UTF-8 text	“… is larger than the 2 MiB draft limit (2,097,153 bytes).” The file is not read.
Paragraphs per draft	1,000	“The script has more than 1,000 paragraphs.”
Roles (after grouping names)	30	“The draft has 31 roles; the limit is 30.” Group alternative names in the Role column to continue.
Speaker name	30 characters	“Line N: the speaker name … is longer than 30 characters.”
Current script pages, including A pages and OMITTED placeholders	100	When locking: “The script is longer than 100 pages.” In a revision: “The script would have 101 pages including overflow and OMITTED pages; the limit is 100.”
Overflow pages per page group	10 (A–J)	“Page group N would need 11 overflow pages; the limit is 10 (NA–NJ).”
Committed revisions after the locked edition	10	The Review step shows Revision limit reached instead of the import button.
Recipients	50, each up to 60 characters	A red note under the list (“… 51 are entered.” or “… has 61.”). The ZIP and save buttons pause until the list is fixed.
Project file	48 MiB (50,331,648 bytes)	“… is larger than the 48 MiB project-file limit (50,331,649 bytes).” The file is not read. Eleven 2 MiB drafts make a project file of about 44 MiB, so every project the app can save fits.

After ten revisions, save the project file, download the original draft text of revision 10 in Distribute, choose ✚ New project and lock that draft as a new rehearsal edition. A new edition is laid out from scratch, so print new binders from it.

Not supported in 1.0: Word (.docx), PDF or Final Draft input; preserving page numbers from scripts printed elsewhere; annotation transfer; non-Windows-1252 characters; two-column, lyric or score layouts. Very long words wrap by splitting. Moved passages appear as a cut and an addition, flagged “possible-move” when the text is identical.

11. Troubleshooting

Message or symptom	What to do
“not valid UTF-8 text”	Save the draft again as Plain Text with UTF-8 encoding.
“characters that the PDF export cannot print”	Replace the listed characters (line and code point are shown) and import again.
“lines without a speaker or brackets”	Check those lines in the preview. Add `NAME:` or brackets if they are dialogue or directions.
“would need 11 overflow pages”	The new material for one page group is too long. Lock a new edition from the current script, or spread the change.
“No changes”	The draft matches the current script; there is nothing to distribute.
Project refused as altered/inconsistent	Use your previous saved copy. Do not edit project files by hand. The project already open is not changed by a refused file.
“Open … ?” asks to save first	The open project has committed work that is not in a saved project file. Choose Save current project first, then Open now.
Download buttons are greyed out in Distribute	The recipient list has more than 50 names or a name longer than 60 characters. Fix the list; the red note says which.
Downloads do not appear	Allow downloads for this file in Chrome’s download settings; files go to your Downloads folder.

Review step blocked with a list of unsupported characters by line and code point — A draft with an emoji and a Chinese character is blocked before commit; each character is listed with its line and code point.

12. Privacy and uninstall

KolyadaPages runs only inside the open browser tab. Its content-security policy blocks network connections, and it has no account, analytics or upload. Scripts stay in memory until you download a ZIP or save a project file. Nothing is stored in the browser after you close the tab. To uninstall, delete the unzipped folder. Remove any downloaded ZIPs and project files you no longer need.