story-format-parser 1.0.2 → 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keane3029-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,110 +1,177 @@
-# .STORY Format Parser & Serializer
-
-A lightweight JavaScript parser and serializer for the custom `.STORY` plain text file format. Built with zero dependencies and cross-environment compatibility for **Node.js** and **Browser** environments.
-
----
-
-## Format Overview
-
-A `.STORY` document structures narrative data into days containing optional headers and body interactions.
-
-```story
-day: 1
-title: The Awakening
-weather: Rain
----
-# First scene
-ALICE: Hello world! Time is 10:30 AM
-* Thunder rumbles in the distance.
-===
-day: 2
-title: Shadows
-mood: Tense
----
-bob: What was that noise?
-* Steps echo down the hall.
-```
-
----
-
-## Features
-
-- **Zero Dependencies:** Standard, vanilla JavaScript.
-- **Universal Export:** Works seamlessly across Node.js (`require`) and Browser (`<script>` tag) runtimes.
-- **Non-Throwing Parser:** Returns detailed `warnings` with line numbers for malformed lines instead of throwing syntax runtime errors.
-- **Full Serialization:** Losslessly converts structured story objects back into standard `.STORY` formatted text.
-
----
-
-## Syntax Rules
-
-1. **Day Separator (`===`):** Separates days within a story file.
-2. **Header-Body Separator (`---`):** Divides header metadata from dialogue/narration lines within each day block.
-3. **Headers (`key: value`):** Reserved keys (`day`, `title`, `scene`, `mood`) map directly onto the day object. Custom/unknown keys are captured in `extra`.
-4. **Dialogue (`speaker: text`):** Dialogue lines are converted to lower-cased speaker identifiers (`speaker`) with body text (`text`).
-5. **Narration (`* text`):** Lines beginning with an asterisk are parsed as `type: "narration"`.
-6. **Comments (`# comment`):** Lines starting with `#` are ignored during parsing.
-
----
-
-## Installation & Setup
-
-Clone the repository to your local machine:
-
-```bash
-git clone https://github.com/keane3029-lab/.story-format.git
-cd .story-format
-```
-
----
-
-## Usage
-
-### Node.js
-
-```javascript
-const { parseStory, serializeStory } = require('./parseStory.js');
-
-const storyText = `
-day: 1
-title: Prologue
----
-* The adventure begins.
-ALICE: Are you ready?
-`;
-
-// Parse text to object structure
-const { days, warnings } = parseStory(storyText);
-console.log(days);
-
-// Serialize object structure back to .STORY format
-const rawText = serializeStory(days);
-console.log(rawText);
-```
-
-### Browser
-
-```html
-<script src="parseStory.js"></script>
-<script>
-  const input = "day: 1\n---\nalice: Ready when you are.";
-  const { days, warnings } = parseStory(input);
-  console.log(days);
-</script>
-```
-
----
-
-## Running Tests
-
-Run the built-in self-test script in Node.js:
-
-```bash
-npm test
-```
-
----
-
-## License
-
-[MIT](LICENSE)
+<p align="center">
+  <img src="story-logo.png" alt=".STORY Format Logo" width="100%">
+</p>
+
+# .STORY Format Parser & Serializer
+
+A lightweight JavaScript parser and serializer for the custom `.STORY` plain text file format, plus a Python port. Zero dependencies, works in **Node.js** and the **browser**.
+
+---
+
+## Format Overview
+
+A `.STORY` document is a list of days. Each day has optional headers, then a body of dialogue and narration.
+
+```story
+day: 1
+title: The Awakening
+weather: Rain
+---
+# First scene
+ALICE: Hello world. Time is 10:30 AM
+* Thunder rumbles in the distance.
+===
+day: 2
+title: Shadows
+mood: Tense
+---
+bob: What was that noise
+* Steps echo down the hall.
+```
+
+---
+
+## Features
+
+- **Zero Dependencies:** vanilla JavaScript.
+- **Universal Export:** works with `require` in Node and a `<script>` tag in the browser.
+- **Non-Throwing Parser:** bad lines produce `warnings` with line numbers instead of exceptions.
+- **Full Serialization:** turns the parsed objects back into `.STORY` text.
+- **Python Port:** `open-storyfiles.py` does the same parse and serialize in Python and can load files from disk.
+
+---
+
+## Syntax Rules
+
+1. **Day Separator (`===`):** on its own line, splits the file into days.
+2. **Header-Body Separator (`---`):** on its own line, ends the header and starts the body of a day.
+3. **Headers (`key: value`):** keys are lowercased. The reserved keys `day`, `title`, `scene` and `mood` map onto the day object. Any other key (like `weather` in the example) is stored in `extra`.
+4. **Day Number:** `day` becomes a number when it parses as one, otherwise it stays a string.
+5. **Dialogue (`speaker: text`):** speaker names are lowercased, so `ALICE:` becomes `alice`.
+6. **Narration (`* text`):** lines starting with `*` become narration entries.
+7. **Comments (`# comment`):** lines starting with `#` are ignored, and so are blank lines.
+8. **Bad Lines:** a header line with no colon is skipped with a warning. A body line with no colon is kept as narration and also gives a warning.
+
+---
+
+## Output Shape
+
+`parseStory(text)` returns `{ days, warnings }`.
+
+```js
+{
+  days: [
+    {
+      day: 1,                  // number, or string if not numeric, or null
+      title: "The Awakening",  // string or null
+      scene: null,             // string or null
+      mood: null,              // string or null
+      extra: { weather: "Rain" },
+      entries: [
+        { type: "dialogue",  speaker: "alice", text: "Hello world. Time is 10:30 AM" },
+        { type: "narration", speaker: null,    text: "Thunder rumbles in the distance." }
+      ]
+    }
+  ],
+  warnings: [
+    { line: 3, message: "Invalid header syntax: missing colon in line \"...\"" }
+  ]
+}
+```
+
+`warnings[].line` is the line number inside that day's block, counting from 1.
+
+`serializeStory(days)` takes the `days` array and returns `.STORY` text. Parsing then serializing keeps the data, but comments and blank lines are dropped, and speakers come out lowercase.
+
+---
+
+## Installation & Setup
+
+```bash
+git clone https://github.com/keane3029-lab/.story-format.git
+cd .story-format
+```
+
+---
+
+## Usage
+
+### Node.js
+
+```javascript
+const { parseStory, serializeStory } = require('./parseStory.js');
+
+const storyText = `
+day: 1
+title: Prologue
+---
+* The adventure begins.
+ALICE: Are you ready
+`;
+
+const { days, warnings } = parseStory(storyText);
+console.log(days);
+
+const rawText = serializeStory(days);
+console.log(rawText);
+```
+
+### Browser
+
+```html
+<script src="parseStory.js"></script>
+<script>
+  const input = "day: 1\n---\nalice: Ready when you are.";
+  const { days, warnings } = parseStory(input);
+  console.log(days);
+</script>
+```
+
+### Python
+
+`open-storyfiles.py` has `parse_story`, `load_story_file` and `serialize_story`, with the same output shape as the JS version.
+
+```python
+import importlib.util
+
+spec = importlib.util.spec_from_file_location("story", "open-storyfiles.py")
+story = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(story)
+
+result = story.load_story_file("sample.story")   # raises FileNotFoundError if missing
+print(result["days"])
+print(result["warnings"])
+
+print(story.serialize_story(result["days"]))
+```
+
+Run it directly to parse `sample.story` and print the JSON:
+
+```bash
+python open-storyfiles.py
+```
+
+If `sample.story` is missing, it runs a built-in inline test instead.
+
+---
+
+## Running Tests
+
+Run the built-in self-test in Node.js:
+
+```bash
+npm test
+```
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+## About
+
+- [About .STORY](about.md)
+- [Creator's Note](creators-note.md)

package/about.md

@@ -0,0 +1,55 @@
+# About .STORY
+
+.STORY is a lightweight plain text format for writing narrative as a series of days. Each day has optional metadata at the top and a body of dialogue and narration underneath. It is meant to be easy to write by hand, easy to read, and easy to parse.
+
+## Why it exists
+
+Most story tools lock your writing into a heavy editor or a complicated markup language. A .STORY file is just text. You can write one on a phone, in a terminal, or in any editor, and a small parser turns it into structured data your code can use.
+
+## What a file looks like
+
+```
+day: 1
+title: The Awakening
+weather: Rain
+---
+# First scene
+ALICE: Hello world. Time is 10:30 AM
+* Thunder rumbles in the distance.
+===
+day: 2
+title: Shadows
+mood: Tense
+---
+bob: What was that noise
+* Steps echo down the hall.
+```
+
+## Syntax at a glance
+
+| Syntax | Meaning |
+| --- | --- |
+| `===` | Separates one day from the next |
+| `---` | Separates a day's headers from its body |
+| `key: value` | A header. `day`, `title`, `scene`, and `mood` are reserved. Other keys are kept in `extra` |
+| `speaker: text` | A line of dialogue. Speaker names are lower-cased by the parser |
+| `* text` | A line of narration |
+| `# text` | A comment, ignored by the parser |
+
+## What is in this repo
+
+- `parseStory.js` is the parser and serializer, with zero dependencies
+- `sample.story` is an example file
+- `open-storyfiles.py` is a helper script for opening .story files
+- `package.json` holds the project and test config
+
+## Design goals
+
+- **Zero dependencies.** Plain vanilla JavaScript.
+- **Works everywhere.** Runs in Node.js with `require` and in the browser with a script tag.
+- **Forgiving.** The parser never throws on bad input. It returns `warnings` with line numbers instead.
+- **Lossless.** Parsed stories can be serialized back into standard .STORY text.
+
+## License
+
+MIT. See the LICENSE file.

package/creators-note.md

@@ -0,0 +1,31 @@
+# Creator's Note
+
+Hi, I'm Keane, the person behind .STORY.
+
+I am a student and indie developer based in Cagayan de Oro, Philippines. I do most of my building from my phone, so I care a lot about tools that are small, plain, and easy to use without a big setup. That is the idea behind this format.
+
+## Why I made it
+
+There are a lot of file formats out there for story game developers to choose from, and picking one can be a project on its own. Some are powerful but heavy, and some take a while to learn before you can write a single line. I wanted one simple option that stays out of the way: write your days, your dialogue, and your narration in plain text, and let a tiny parser handle the rest.
+
+## What I want it to be
+
+A format that anyone can write by hand and anything can read. No lock-in, no special editor, no heavy tooling. If you can type text, you can write a .STORY file.
+
+## Where it is going
+
+I plan to publish the parser to npm so anyone can install it with one command. Beyond that, I want to see what other people build with it, like story players, visual novel tools, and games.
+
+## Contributing
+
+Ideas, bug reports, and pull requests are welcome. If you find a line the parser handles badly, open an issue and include the line and the warning it gave you.
+
+## Support the project
+
+The best way to support .STORY is to spread the word. Star the repo, share it with other story game devs, and tell a friend who writes dialogue-heavy games or visual novels. The more people who know it exists, the more it grows, and the more it can be improved by people who actually use it.
+
+## Thanks
+
+Thank you for checking out .STORY. If you make something with it, I would love to see it.
+
+Keane

package/open-storyfiles.py

@@ -1,179 +1,181 @@
-import os
-import re
-import json
-
-def parse_story(text: str) -> dict:
-    """
-    Parses raw .STORY format string into a structured dictionary.
-    Returns a dict containing 'days' list and 'warnings' list.
-    """
-    days = []
-    warnings = []
-
-    if not isinstance(text, str):
-        warnings.append({"line": 0, "message": "Input must be a string."})
-        return {"days": days, "warnings": warnings}
-
-    # Split by day delimiter '===' on its own line
-    raw_days = re.split(r'^===\s*$', text, flags=re.MULTILINE)
-
-    for day_text in raw_days:
-        lines = day_text.splitlines()
-        day_obj = {
-            "day": None,
-            "title": None,
-            "scene": None,
-            "mood": None,
-            "extra": {},
-            "entries": []
-        }
-
-        in_header = True
-
-        for line_idx, line in enumerate(lines):
-            line_num = line_idx + 1
-            trimmed = line.strip()
-
-            # Ignore empty lines and comments
-            if not trimmed or trimmed.startswith("#"):
-                continue
-
-            # Check for header/body separator '---'
-            if in_header and re.match(r'^---\s*$', trimmed):
-                in_header = False
-                continue
-
-            if in_header:
-                if ":" not in line:
-                    warnings.append({
-                        "line": line_num,
-                        "message": f'Invalid header syntax: missing colon in line "{trimmed}"'
-                    })
-                    continue
-
-                key, value = line.split(":", 1)
-                key = key.strip().lower()
-                value = value.strip()
-
-                if key in ["day", "title", "scene", "mood"]:
-                    if key == "day":
-                        try:
-                            day_obj["day"] = int(value)
-                        except ValueError:
-                            day_obj["day"] = value
-                    else:
-                        day_obj[key] = value
-                else:
-                    day_obj["extra"][key] = value
-            else:
-                # Body parsing (dialogue vs narration)
-                if trimmed.startswith("*"):
-                    narration_text = trimmed[1:].strip()
-                    day_obj["entries"].append({
-                        "type": "narration",
-                        "speaker": None,
-                        "text": narration_text
-                    })
-                else:
-                    if ":" not in line:
-                        warnings.append({
-                            "line": line_num,
-                            "message": f'Invalid dialogue syntax: missing speaker colon in line "{trimmed}"'
-                        })
-                        # Fallback as narration
-                        day_obj["entries"].append({
-                            "type": "narration",
-                            "speaker": None,
-                            "text": trimmed
-                        })
-                        continue
-
-                    speaker, entry_text = line.split(":", 1)
-                    speaker = speaker.strip().lower()
-                    entry_text = entry_text.strip()
-
-                    day_obj["entries"].append({
-                        "type": "dialogue",
-                        "speaker": speaker,
-                        "text": entry_text
-                    })
-
-        if day_obj["day"] is not None or len(day_obj["entries"]) > 0 or len(day_obj["extra"]) > 0:
-            days.append(day_obj)
-
-    return {"days": days, "warnings": warnings}
-
-
-def load_story_file(file_path: str) -> dict:
-    """
-    Opens and parses a .STORY file from disk.
-    """
-    if not os.path.exists(file_path):
-        raise FileNotFoundError(f"Story file not found at path: {file_path}")
-
-    with open(file_path, "r", encoding="utf-8") as f:
-        content = f.read()
-
-    return parse_story(content)
-
-
-def serialize_story(days: list) -> str:
-    """
-    Serializes a list of day dictionaries back into .STORY formatted plain text.
-    """
-    if not isinstance(days, list):
-        return ""
-
-    day_blocks = []
-    for day_obj in days:
-        header_lines = []
-
-        if day_obj.get("day") is not None:
-            header_lines.append(f"day: {day_obj['day']}")
-        if day_obj.get("title"):
-            header_lines.append(f"title: {day_obj['title']}")
-        if day_obj.get("scene"):
-            header_lines.append(f"scene: {day_obj['scene']}")
-        if day_obj.get("mood"):
-            header_lines.append(f"mood: {day_obj['mood']}")
-
-        extra = day_obj.get("extra", {})
-        if isinstance(extra, dict):
-            for k, v in extra.items():
-                header_lines.append(f"{k}: {v}")
-
-        body_lines = []
-        for entry in day_obj.get("entries", []):
-            if entry.get("type") == "narration" or not entry.get("speaker"):
-                body_lines.append(f"* {entry.get('text', '')}")
-            else:
-                body_lines.append(f"{entry.get('speaker', '')}: {entry.get('text', '')}")
-
-        full_block = "\n".join(header_lines) + "\n---\n" + "\n".join(body_lines)
-        day_blocks.append(full_block)
-
-    return "\n===\n".join(day_blocks)
-
-
-# Quick runner test when executed directly
-if __name__ == "__main__":
-    sample_file = "sample.story"
-    
-    if os.path.exists(sample_file):
-        print(f"=== READING {sample_file} ===")
-        result = load_story_file(sample_file)
-        print("Parsed JSON Output:")
-        print(json.dumps(result["days"], indent=2))
-        print("\nWarnings:", result["warnings"])
-    else:
-        print(f"File {sample_file} not found. Running inline test.")
-        sample_data = """day: 1
-title: The Python Awakening
-scene: Code Room
----
-# Python parser test
-python_bot: Hello from Python land!
-* The script executes flawlessly.
-"""
-        result = parse_story(sample_data)
-        print(json.dumps(result["days"], indent=2))
+import os
+import re
+import json
+
+def parse_story(text: str) -> dict:
+    """
+    Parses raw .STORY format string into a structured dictionary.
+    Returns a dict containing 'days' list and 'warnings' list.
+    """
+    days = []
+    warnings = []
+
+    if not isinstance(text, str):
+        warnings.append({"line": 0, "message": "Input must be a string."})
+        return {"days": days, "warnings": warnings}
+
+    # Split by day delimiter '===' on its own line
+    raw_days = re.split(r'^===\s*$', text, flags=re.MULTILINE)
+
+    for day_text in raw_days:
+        lines = day_text.splitlines()
+        day_obj = {
+            "day": None,
+            "title": None,
+            "scene": None,
+            "mood": None,
+            "extra": {},
+            "entries": []
+        }
+
+        in_header = True
+
+        for line_idx, line in enumerate(lines):
+            line_num = line_idx + 1
+            trimmed = line.strip()
+
+            # Ignore empty lines and comments
+            if not trimmed or trimmed.startswith("#"):
+                continue
+
+            # Check for header/body separator '---'
+            if in_header and re.match(r'^---\s*$', trimmed):
+                in_header = False
+                continue
+
+            if in_header:
+                if ":" not in line:
+                    warnings.append({
+                        "line": line_num,
+                        "message": f'Invalid header syntax: missing colon in line "{trimmed}"'
+                    })
+                    continue
+
+                key, value = line.split(":", 1)
+                key = key.strip().lower()
+                value = value.strip()
+
+                if key in ["day", "title", "scene", "mood"]:
+                    if key == "day":
+                        # Strict integer check so "2b" stays a string (matches the JS port)
+                        if re.fullmatch(r'[+-]?[0-9]+', value):
+                            day_obj["day"] = int(value)
+                        else:
+                            day_obj["day"] = value
+                    else:
+                        day_obj[key] = value
+                else:
+                    day_obj["extra"][key] = value
+            else:
+                # Body parsing (dialogue vs narration)
+                if trimmed.startswith("*"):
+                    narration_text = trimmed[1:].strip()
+                    day_obj["entries"].append({
+                        "type": "narration",
+                        "speaker": None,
+                        "text": narration_text
+                    })
+                else:
+                    if ":" not in line:
+                        warnings.append({
+                            "line": line_num,
+                            "message": f'Invalid dialogue syntax: missing speaker colon in line "{trimmed}"'
+                        })
+                        # Fallback as narration
+                        day_obj["entries"].append({
+                            "type": "narration",
+                            "speaker": None,
+                            "text": trimmed
+                        })
+                        continue
+
+                    speaker, entry_text = line.split(":", 1)
+                    speaker = speaker.strip().lower()
+                    entry_text = entry_text.strip()
+
+                    day_obj["entries"].append({
+                        "type": "dialogue",
+                        "speaker": speaker,
+                        "text": entry_text
+                    })
+
+        has_header = any(day_obj[k] is not None for k in ("day", "title", "scene", "mood"))
+        if has_header or len(day_obj["entries"]) > 0 or len(day_obj["extra"]) > 0:
+            days.append(day_obj)
+
+    return {"days": days, "warnings": warnings}
+
+
+def load_story_file(file_path: str) -> dict:
+    """
+    Opens and parses a .STORY file from disk.
+    """
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"Story file not found at path: {file_path}")
+
+    with open(file_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    return parse_story(content)
+
+
+def serialize_story(days: list) -> str:
+    """
+    Serializes a list of day dictionaries back into .STORY formatted plain text.
+    """
+    if not isinstance(days, list):
+        return ""
+
+    day_blocks = []
+    for day_obj in days:
+        header_lines = []
+
+        if day_obj.get("day") is not None:
+            header_lines.append(f"day: {day_obj['day']}")
+        if day_obj.get("title"):
+            header_lines.append(f"title: {day_obj['title']}")
+        if day_obj.get("scene"):
+            header_lines.append(f"scene: {day_obj['scene']}")
+        if day_obj.get("mood"):
+            header_lines.append(f"mood: {day_obj['mood']}")
+
+        extra = day_obj.get("extra", {})
+        if isinstance(extra, dict):
+            for k, v in extra.items():
+                header_lines.append(f"{k}: {v}")
+
+        body_lines = []
+        for entry in day_obj.get("entries", []):
+            if entry.get("type") == "narration" or not entry.get("speaker"):
+                body_lines.append(f"* {entry.get('text', '')}")
+            else:
+                body_lines.append(f"{entry.get('speaker', '')}: {entry.get('text', '')}")
+
+        full_block = "\n".join(header_lines + ["---"] + body_lines)
+        day_blocks.append(full_block)
+
+    return "\n===\n".join(day_blocks)
+
+
+# Quick runner test when executed directly
+if __name__ == "__main__":
+    sample_file = "sample.story"
+    
+    if os.path.exists(sample_file):
+        print(f"=== READING {sample_file} ===")
+        result = load_story_file(sample_file)
+        print("Parsed JSON Output:")
+        print(json.dumps(result["days"], indent=2))
+        print("\nWarnings:", result["warnings"])
+    else:
+        print(f"File {sample_file} not found. Running inline test.")
+        sample_data = """day: 1
+title: The Python Awakening
+scene: Code Room
+---
+# Python parser test
+python_bot: Hello from Python land!
+* The script executes flawlessly.
+"""
+        result = parse_story(sample_data)
+        print(json.dumps(result["days"], indent=2))

package/package.json

@@ -1,17 +1,29 @@
-{
-  "name": "story-format-parser",
-  "version": "1.0.2",
-  "description": "Parser and serializer for the .STORY plain text file format.",
-  "main": "parseStory.js",
-  "scripts": {
-    "test": "node parseStory.js"
-  },
-  "keywords": [
-    "story",
-    "parser",
-    "interactive-fiction",
-    "text-format"
-  ],
-  "author": "",
-  "license": "MIT"
-}
+{
+  "name": "story-format-parser",
+  "version": "1.2.1",
+  "description": "Parser and serializer for the .STORY plain text file format.",
+  "main": "parseStory.js",
+  "files": [
+    "parseStory.js",
+    "open-storyfiles.py",
+    "sample.story",
+    "about.md",
+    "creators-note.md",
+    "story-logo.png"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keane3029-lab/.story-format.git"
+  },
+  "keywords": [
+    "story",
+    "parser",
+    "interactive-fiction",
+    "text-format"
+  ],
+  "author": "",
+  "license": "MIT"
+}

package/parseStory.js

@@ -1,146 +1,147 @@
-/**
- * .STORY Format Parser, Serializer, and File Reader
- * Zero-dependency universal library (Node.js & Browser)
- */
-
-function parseStory(text) {
-  const days = [];
-  const warnings = [];
-
-  if (typeof text !== "string") {
-    warnings.push({ line: 0, message: "Input must be a string." });
-    return { days, warnings };
-  }
-
-  const rawDays = text.split(/^===\s*$/m);
-
-  rawDays.forEach((dayText, dayIdx) => {
-    const lines = dayText.split(/\r?\n/);
-    const dayObj = {
-      day: null,
-      title: null,
-      scene: null,
-      mood: null,
-      extra: {},
-      entries: []
-    };
-
-    let inHeader = true;
-
-    lines.forEach((line, lineIdx) => {
-      const lineNum = lineIdx + 1;
-      const trimmed = line.trim();
-
-      // Ignore empty lines and comments
-      if (!trimmed || trimmed.startsWith("#")) {
-        return;
-      }
-
-      // Check header/body separator
-      if (inHeader && /^---\s*$/.test(trimmed)) {
-        inHeader = false;
-        return;
-      }
-
-      if (inHeader) {
-        const colonIndex = line.indexOf(":");
-        if (colonIndex === -1) {
-          warnings.push({
-            line: lineNum,
-            message: `Invalid header syntax: missing colon in line "${trimmed}"`
-          });
-          return;
-        }
-
-        const key = line.slice(0, colonIndex).trim().toLowerCase();
-        const value = line.slice(colonIndex + 1).trim();
-
-        if (["day", "title", "scene", "mood"].includes(key)) {
-          if (key === "day") {
-            const parsedDay = parseInt(value, 10);
-            dayObj.day = isNaN(parsedDay) ? value : parsedDay;
-          } else {
-            dayObj[key] = value;
-          }
-        } else {
-          dayObj.extra[key] = value;
-        }
-      } else {
-        // Parsing body (dialogue and narration)
-        if (trimmed.startsWith("*")) {
-          // Narration
-          const narrationText = trimmed.slice(1).trim();
-          dayObj.entries.push({
-            type: "narration",
-            speaker: null,
-            text: narrationText
-          });
-        } else {
-          // Dialogue
-          const colonIndex = line.indexOf(":");
-          if (colonIndex === -1) {
-            warnings.push({
-              line: lineNum,
-              message: `Invalid dialogue syntax: missing speaker colon in line "${trimmed}"`
-            });
-            // Fallback as unformatted narration
-            dayObj.entries.push({
-              type: "narration",
-              speaker: null,
-              text: trimmed
-            });
-            return;
-          }
-
-          const speaker = line.slice(0, colonIndex).trim().toLowerCase();
-          const text = line.slice(colonIndex + 1).trim();
-
-          dayObj.entries.push({
-            type: "dialogue",
-            speaker,
-            text
-          });
-        }
-      }
-    });
-
-    if (dayObj.day !== null || dayObj.entries.length > 0 || Object.keys(dayObj.extra).length > 0) {
-      days.push(dayObj);
-    }
-  });
-
-  return { days, warnings };
-}
-
-function serializeStory(days) {
-  if (!Array.isArray(days)) return "";
-
-  return days.map(dayObj => {
-    const headerLines = [];
-
-    if (dayObj.day !== null && dayObj.day !== undefined) headerLines.push(`day: ${dayObj.day}`);
-    if (dayObj.title) headerLines.push(`title: ${dayObj.title}`);
-    if (dayObj.scene) headerLines.push(`scene: ${dayObj.scene}`);
-    if (dayObj.mood) headerLines.push(`mood: ${dayObj.mood}`);
-
-    if (dayObj.extra && typeof dayObj.extra === "object") {
-      Object.entries(dayObj.extra).forEach(([k, v]) => {
-        headerLines.push(`\({k}:\){v}`);
-      });
-    }
-
-    const bodyLines = (dayObj.entries || []).map(entry => {
-      if (entry.type === "narration" || !entry.speaker) {
-        return `* ${entry.text}`;
-      }
-      return `\({entry.speaker}:\){entry.text}`;
-    });
-
-    return [...headerLines, "---", ...bodyLines].join("\n");
-  }).join("\n===\n");
-}
-
-/**
- * Reads and parses a .STORY file asynchronously in Node.js.
- * @param {string} filePath - Path to the .STORY file.
- * @returns {Promise<{ days: Array 
+/**
+ * .STORY Format Parser, Serializer, and File Reader
+ * Zero-dependency universal library (Node.js & Browser)
+ */
+
+function parseStory(text) {
+  const days = [];
+  const warnings = [];
+
+  if (typeof text !== "string") {
+    warnings.push({ line: 0, message: "Input must be a string." });
+    return { days, warnings };
+  }
+
+  const rawDays = text.split(/^===\s*$/m);
+
+  rawDays.forEach((dayText, dayIdx) => {
+    const lines = dayText.split(/\r?\n/);
+    const dayObj = {
+      day: null,
+      title: null,
+      scene: null,
+      mood: null,
+      extra: {},
+      entries: []
+    };
+
+    let inHeader = true;
+
+    lines.forEach((line, lineIdx) => {
+      const lineNum = lineIdx + 1;
+      const trimmed = line.trim();
+
+      // Ignore empty lines and comments
+      if (!trimmed || trimmed.startsWith("#")) {
+        return;
+      }
+
+      // Check header/body separator
+      if (inHeader && /^---\s*$/.test(trimmed)) {
+        inHeader = false;
+        return;
+      }
+
+      if (inHeader) {
+        const colonIndex = line.indexOf(":");
+        if (colonIndex === -1) {
+          warnings.push({
+            line: lineNum,
+            message: `Invalid header syntax: missing colon in line "${trimmed}"`
+          });
+          return;
+        }
+
+        const key = line.slice(0, colonIndex).trim().toLowerCase();
+        const value = line.slice(colonIndex + 1).trim();
+
+        if (["day", "title", "scene", "mood"].includes(key)) {
+          if (key === "day") {
+            // Strict integer check so "2b" stays a string (matches the Python port)
+            dayObj.day = /^[+-]?\d+$/.test(value) ? parseInt(value, 10) : value;
+          } else {
+            dayObj[key] = value;
+          }
+        } else {
+          dayObj.extra[key] = value;
+        }
+      } else {
+        // Parsing body (dialogue and narration)
+        if (trimmed.startsWith("*")) {
+          // Narration
+          const narrationText = trimmed.slice(1).trim();
+          dayObj.entries.push({
+            type: "narration",
+            speaker: null,
+            text: narrationText
+          });
+        } else {
+          // Dialogue
+          const colonIndex = line.indexOf(":");
+          if (colonIndex === -1) {
+            warnings.push({
+              line: lineNum,
+              message: `Invalid dialogue syntax: missing speaker colon in line "${trimmed}"`
+            });
+            // Fallback as unformatted narration
+            dayObj.entries.push({
+              type: "narration",
+              speaker: null,
+              text: trimmed
+            });
+            return;
+          }
+
+          const speaker = line.slice(0, colonIndex).trim().toLowerCase();
+          const text = line.slice(colonIndex + 1).trim();
+
+          dayObj.entries.push({
+            type: "dialogue",
+            speaker,
+            text
+          });
+        }
+      }
+    });
+
+    const hasHeader = dayObj.day !== null || dayObj.title !== null ||
+      dayObj.scene !== null || dayObj.mood !== null;
+    if (hasHeader || dayObj.entries.length > 0 || Object.keys(dayObj.extra).length > 0) {
+      days.push(dayObj);
+    }
+  });
+
+  return { days, warnings };
+}
+
+function serializeStory(days) {
+  if (!Array.isArray(days)) return "";
+
+  return days.map(dayObj => {
+    const headerLines = [];
+
+    if (dayObj.day !== null && dayObj.day !== undefined) headerLines.push(`day: ${dayObj.day}`);
+    if (dayObj.title) headerLines.push(`title: ${dayObj.title}`);
+    if (dayObj.scene) headerLines.push(`scene: ${dayObj.scene}`);
+    if (dayObj.mood) headerLines.push(`mood: ${dayObj.mood}`);
+
+    if (dayObj.extra && typeof dayObj.extra === "object") {
+      Object.entries(dayObj.extra).forEach(([k, v]) => {
+        headerLines.push(`${k}: ${v}`);
+      });
+    }
+
+    const bodyLines = (dayObj.entries || []).map(entry => {
+      if (entry.type === "narration" || !entry.speaker) {
+        return `* ${entry.text}`;
+      }
+      return `${entry.speaker}: ${entry.text}`;
+    });
+
+    return [...headerLines, "---", ...bodyLines].join("\n");
+  }).join("\n===\n");
+}
+
+if (typeof module === "object" && module.exports) {
+  module.exports = { parseStory, serializeStory };
+}

package/sample.story

@@ -1,3 +1,3 @@
-day: 1
-title: The Awakening
+day: 1
+title: The Awakening
 weather: Rain

package/.vscode/launch.json

@@ -1,14 +0,0 @@
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "type": "node",
-      "request": "launch",
-      "name": "Debug parseStory.js",
-      "program": "${workspaceFolder}/parseStory.js",
-      "skipFiles": [
-        "/**"
-      ]
-    }
-  ]
-}

package/.vscode/settings.json

@@ -1,5 +0,0 @@
-{
-  "files.associations": {
-    "*.story": "markdown"
-  }
-}