extwee 2.3.4 → 2.3.5

package/test/Twee/Twee.Escaping.test.js

@@ -0,0 +1,200 @@
+import { parse as parseTwee, escapeTweeMetacharacters, unescapeTweeMetacharacters } from '../../src/Twee/parse.js';
+import Passage from '../../src/Passage.js';
+
+describe('Twee Escaping', () => {
+  describe('unescapeTweeMetacharacters()', () => {
+    it('Should unescape square brackets', () => {
+      expect(unescapeTweeMetacharacters('Test\\[Name\\]')).toBe('Test[Name]');
+    });
+
+    it('Should unescape curly braces', () => {
+      expect(unescapeTweeMetacharacters('Test\\{Name\\}')).toBe('Test{Name}');
+    });
+
+    it('Should unescape backslashes', () => {
+      expect(unescapeTweeMetacharacters('Test\\\\Name')).toBe('Test\\Name');
+    });
+
+    it('Should unescape any character after backslash (robust decoding)', () => {
+      expect(unescapeTweeMetacharacters('\\q')).toBe('q');
+      expect(unescapeTweeMetacharacters('\\x')).toBe('x');
+      expect(unescapeTweeMetacharacters('\\5')).toBe('5');
+    });
+
+    it('Should handle complex combinations', () => {
+      expect(unescapeTweeMetacharacters('\\[Hello\\] \\{world\\} \\\\\\\\')).toBe('[Hello] {world} \\\\');
+    });
+
+    it('Should handle non-string input gracefully', () => {
+      expect(unescapeTweeMetacharacters(null)).toBe(null);
+      expect(unescapeTweeMetacharacters(undefined)).toBe(undefined);
+      expect(unescapeTweeMetacharacters(123)).toBe(123);
+    });
+
+    it('Should handle empty strings', () => {
+      expect(unescapeTweeMetacharacters('')).toBe('');
+    });
+
+    it('Should handle strings without escape sequences', () => {
+      expect(unescapeTweeMetacharacters('Normal Text')).toBe('Normal Text');
+    });
+  });
+
+  describe('escapeTweeMetacharacters()', () => {
+    it('Should escape square brackets', () => {
+      expect(escapeTweeMetacharacters('Test[Name]')).toBe('Test\\[Name\\]');
+    });
+
+    it('Should escape curly braces', () => {
+      expect(escapeTweeMetacharacters('Test{Name}')).toBe('Test\\{Name\\}');
+    });
+
+    it('Should escape backslashes', () => {
+      expect(escapeTweeMetacharacters('Test\\Name')).toBe('Test\\\\Name');
+    });
+
+    it('Should escape complex combinations', () => {
+      expect(escapeTweeMetacharacters('[Hello] {world} \\\\')).toBe('\\[Hello\\] \\{world\\} \\\\\\\\');
+    });
+
+    it('Should handle non-string input gracefully', () => {
+      expect(escapeTweeMetacharacters(null)).toBe(null);
+      expect(escapeTweeMetacharacters(undefined)).toBe(undefined);
+      expect(escapeTweeMetacharacters(123)).toBe(123);
+    });
+
+    it('Should handle empty strings', () => {
+      expect(escapeTweeMetacharacters('')).toBe('');
+    });
+
+    it('Should handle strings without metacharacters', () => {
+      expect(escapeTweeMetacharacters('Normal Text')).toBe('Normal Text');
+    });
+  });
+
+  describe('Round-trip escaping', () => {
+    it('Should preserve text through escape -> unescape cycle', () => {
+      const original = 'Test[Name]{Value}\\Path';
+      const escaped = escapeTweeMetacharacters(original);
+      const unescaped = unescapeTweeMetacharacters(escaped);
+      expect(unescaped).toBe(original);
+    });
+
+    it('Should handle complex nested scenarios', () => {
+      const original = '[{\\}]{[\\]}';
+      const escaped = escapeTweeMetacharacters(original);
+      const unescaped = unescapeTweeMetacharacters(escaped);
+      expect(unescaped).toBe(original);
+    });
+  });
+
+  describe('Twee parsing with escaping', () => {
+    it('Should correctly parse escaped passage names', () => {
+      const content = ':: Test\\[Name\\] \\{with\\} \\\\brackets\nContent here';
+      const story = parseTwee(content);
+      expect(story.passages[0].name).toBe('Test[Name] {with} \\brackets');
+    });
+
+    it('Should correctly parse escaped tags', () => {
+      const content = ':: TestPassage [tag\\[1\\] tag\\{2\\}]\nContent here';
+      const story = parseTwee(content);
+      expect(story.passages[0].tags).toEqual(['tag[1]', 'tag{2}']);
+    });
+
+    it('Should handle mixed escaped and non-escaped content', () => {
+      const content = ':: Test\\[Passage [normal escaped\\]tag]\nContent here';
+      const story = parseTwee(content);
+      expect(story.passages[0].name).toBe('Test[Passage');
+      expect(story.passages[0].tags).toEqual(['normal', 'escaped]tag']);
+    });
+
+    it('Should handle the cursed.twee test case correctly', () => {
+      const content = `:: StoryData
+{
+  "ifid": "22F25A58-7062-4927-95B6-F424DDB2EC65",
+  "format": "Harlowe",
+  "format-version": "3.3.8",
+  "start": "[Hello] {world} \\\\\\\\",
+  "zoom": 1
+}
+
+:: \\[Hello\\] \\{world\\} \\\\\\\\
+Content here`;
+      
+      const story = parseTwee(content);
+      expect(story.start).toBe('[Hello] {world} \\\\');
+      
+      // Find the passage by the unescaped name
+      const passage = story.getPassageByName('[Hello] {world} \\\\');
+      expect(passage).not.toBeNull();
+      expect(passage.name).toBe('[Hello] {world} \\\\');
+    });
+
+    it('Should handle complex metadata with escaped keys (if supported)', () => {
+      const content = ':: TestPassage {"position": "100,200", "size": "150,100"}\nContent here';
+      const story = parseTwee(content);
+      expect(story.passages[0].metadata.position).toBe('100,200');
+      expect(story.passages[0].metadata.size).toBe('150,100');
+    });
+  });
+
+  describe('Twee generation with escaping', () => {
+    it('Should escape passage names when generating Twee', () => {
+      const passage = new Passage('Test[Name]', 'Content', [], {});
+      const tweeOutput = passage.toTwee();
+      expect(tweeOutput).toContain(':: Test\\[Name\\]');
+    });
+
+    it('Should escape tag names when generating Twee', () => {
+      const passage = new Passage('TestPassage', 'Content', ['tag[1]', 'tag{2}'], {});
+      const tweeOutput = passage.toTwee();
+      expect(tweeOutput).toContain('[tag\\[1\\] tag\\{2\\}]');
+    });
+
+    it('Should handle complex escaping scenarios', () => {
+      const passage = new Passage('Test[Name]{Value}\\Path', 'Content', ['complex[tag]'], {});
+      const tweeOutput = passage.toTwee();
+      expect(tweeOutput).toContain(':: Test\\[Name\\]\\{Value\\}\\\\Path');
+      expect(tweeOutput).toContain('[complex\\[tag\\]]');
+    });
+
+    it('Should preserve normal names and tags without escaping', () => {
+      const passage = new Passage('NormalName', 'Content', ['normaltag'], {});
+      const tweeOutput = passage.toTwee();
+      expect(tweeOutput).toContain(':: NormalName');
+      expect(tweeOutput).toContain('[normaltag]');
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('Should handle empty passage names gracefully', () => {
+      const content = ':: \nContent here';
+      expect(() => parseTwee(content)).toThrow('Malformed passage header!');
+    });
+
+    it('Should handle passages with only escaped characters as names', () => {
+      const content = ':: \\[\\]\nContent here';
+      const story = parseTwee(content);
+      expect(story.passages[0].name).toBe('[]');
+    });
+
+    it('Should handle multiple consecutive escapes', () => {
+      const content = ':: Test\\\\\\\\Name\nContent here';
+      const story = parseTwee(content);
+      expect(story.passages[0].name).toBe('Test\\\\Name');
+    });
+
+    it('Should handle tags with only metacharacters', () => {
+      const content = ':: TestPassage [\\[\\] \\{\\}]\nContent here';
+      const story = parseTwee(content);
+      expect(story.passages[0].tags).toEqual(['[]', '{}']);
+    });
+
+    it('Should handle mixed whitespace and escaping', () => {
+      const content = ':: Test\\[Name\\]   [  tag\\[1\\]   tag2  ]\nContent here';
+      const story = parseTwee(content);
+      expect(story.passages[0].name).toBe('Test[Name]');
+      expect(story.passages[0].tags).toEqual(['tag[1]', 'tag2']);
+    });
+  });
+});

package/test/Web/web-twine1html.test.js

@@ -0,0 +1,105 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * Tests for web-twine1html.js module
+ * Tests module exports and functionality
+ */
+
+import { describe, expect, it } from '@jest/globals';
+
+// Import to test basic functionality
+import { parse, compile } from '../../src/Web/web-twine1html.js';
+import Extwee from '../../src/Web/web-twine1html.js';
+
+describe('web-twine1html.js module tests', () => {
+
+  describe('ES6 module exports', () => {
+    it('should export parse and compile functions', () => {
+      expect(parse).toBeDefined();
+      expect(compile).toBeDefined();
+      expect(typeof parse).toBe('function');
+      expect(typeof compile).toBe('function');
+    });
+
+    it('should export default object with parseTwine1HTML and compileTwine1HTML', () => {
+      expect(Extwee.parseTwine1HTML).toBeDefined();
+      expect(Extwee.compileTwine1HTML).toBeDefined();
+      expect(Extwee.parse).toBeDefined();
+      expect(Extwee.compile).toBeDefined();
+      expect(typeof Extwee.parseTwine1HTML).toBe('function');
+      expect(typeof Extwee.compileTwine1HTML).toBe('function');
+    });
+  });
+
+  describe('Global object assignment', () => {
+    it('should assign functions to global object when available', () => {
+      // In Node.js environment, should assign to globalThis
+      expect(globalThis.Extwee).toBeDefined();
+      expect(globalThis.Extwee.parseTwine1HTML).toBeDefined();
+      expect(globalThis.Extwee.compileTwine1HTML).toBeDefined();
+      expect(typeof globalThis.Extwee.parseTwine1HTML).toBe('function');
+      expect(typeof globalThis.Extwee.compileTwine1HTML).toBe('function');
+    });
+
+    it('should preserve existing Extwee properties', () => {
+      // Should not overwrite the entire object, just add properties
+      if (globalThis.Extwee && globalThis.Extwee.version) {
+        expect(globalThis.Extwee.version).toBeDefined();
+      }
+      expect(globalThis.Extwee.parseTwine1HTML).toBeDefined();
+      expect(globalThis.Extwee.compileTwine1HTML).toBeDefined();
+    });
+  });
+
+  describe('Functional integration tests', () => {
+    it('should have working parseTwine1HTML function', () => {
+      // Test with valid Twine 1 HTML
+      const sampleHtml = `
+        <html>
+          <head><title>Test</title></head>
+          <body>
+            <div id="storeArea" data-size="2">
+              <div tiddler="Start" tags="" twine-position="100,100">Start passage</div>
+            </div>
+          </body>
+        </html>
+      `;
+      
+      expect(() => {
+        const result = parse(sampleHtml);
+        expect(result).toBeDefined();
+        expect(result.passages).toBeDefined();
+      }).not.toThrow();
+    });
+
+    it('should have working compileTwine1HTML function', async () => {
+      // Import required classes dynamically to avoid circular imports
+      const { Story } = await import('../../src/Story.js');
+      const { default: Passage } = await import('../../src/Passage.js');
+      const { default: StoryFormat } = await import('../../src/StoryFormat.js');
+      
+      const story = new Story();
+      story.name = "Test Story";
+      story.addPassage(new Passage("Start", "This is the start", [], {}));
+      
+      const storyFormat = new StoryFormat();
+      storyFormat.source = "window.story = STORY;";
+      storyFormat.version = "1.0.0";
+      
+      expect(() => {
+        const result = compile(story, storyFormat, '', '', '');
+        expect(typeof result).toBe('string');
+      }).not.toThrow();
+    });
+
+    it('should have same functions in exports and global', () => {
+      // Test that parse and compile are the same functions
+      expect(parse).toBe(Extwee.parse);
+      expect(compile).toBe(Extwee.compile);
+      expect(parse).toBe(Extwee.parseTwine1HTML);
+      expect(compile).toBe(Extwee.compileTwine1HTML);
+    });
+  });
+});

package/test/Web/web-twine2archive.test.js

@@ -0,0 +1,96 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * Tests for web-twine2archive.js module
+ * Tests module exports and functionality
+ */
+
+import { describe, expect, it } from '@jest/globals';
+
+// Import to test basic functionality
+import { parse, compile } from '../../src/Web/web-twine2archive.js';
+import Extwee from '../../src/Web/web-twine2archive.js';
+
+describe('web-twine2archive.js module tests', () => {
+
+  describe('ES6 module exports', () => {
+    it('should export parse and compile functions', () => {
+      expect(parse).toBeDefined();
+      expect(compile).toBeDefined();
+      expect(typeof parse).toBe('function');
+      expect(typeof compile).toBe('function');
+    });
+
+    it('should export default object with parseTwine2ArchiveHTML and compileTwine2ArchiveHTML', () => {
+      expect(Extwee.parseTwine2ArchiveHTML).toBeDefined();
+      expect(Extwee.compileTwine2ArchiveHTML).toBeDefined();
+      expect(Extwee.parse).toBeDefined();
+      expect(Extwee.compile).toBeDefined();
+      expect(typeof Extwee.parseTwine2ArchiveHTML).toBe('function');
+      expect(typeof Extwee.compileTwine2ArchiveHTML).toBe('function');
+    });
+  });
+
+  describe('Global object assignment', () => {
+    it('should assign functions to global object when available', () => {
+      // In Node.js environment, should assign to globalThis
+      expect(globalThis.Extwee).toBeDefined();
+      expect(globalThis.Extwee.parseTwine2ArchiveHTML).toBeDefined();
+      expect(globalThis.Extwee.compileTwine2ArchiveHTML).toBeDefined();
+      expect(typeof globalThis.Extwee.parseTwine2ArchiveHTML).toBe('function');
+      expect(typeof globalThis.Extwee.compileTwine2ArchiveHTML).toBe('function');
+    });
+
+    it('should preserve existing Extwee properties', () => {
+      // Should not overwrite the entire object, just add properties
+      if (globalThis.Extwee && globalThis.Extwee.version) {
+        expect(globalThis.Extwee.version).toBeDefined();
+      }
+      expect(globalThis.Extwee.parseTwine2ArchiveHTML).toBeDefined();
+      expect(globalThis.Extwee.compileTwine2ArchiveHTML).toBeDefined();
+    });
+  });
+
+  describe('Functional integration tests', () => {
+    it('should have working parseTwine2ArchiveHTML function', () => {
+      // Test with valid Twine 2 Archive HTML
+      const sampleHtml = `
+        <tw-storydata name="Test" startnode="1" creator="Twine" creator-version="2.3.5">
+          <tw-passagedata pid="1" name="Start" tags="">Start passage</tw-passagedata>
+        </tw-storydata>
+      `;
+      
+      expect(() => {
+        const result = parse(sampleHtml);
+        expect(result).toBeDefined();
+        expect(Array.isArray(result)).toBe(true);
+      }).not.toThrow();
+    });
+
+    it('should have working compileTwine2ArchiveHTML function', async () => {
+      // Import required classes
+      const { Story } = await import('../../src/Story.js');
+      const { default: Passage } = await import('../../src/Passage.js');
+      
+      const story = new Story();
+      story.name = "Test Story";
+      story.IFID = "12345678-1234-5678-9012-123456789012";
+      story.addPassage(new Passage("Start", "This is the start", [], {}));
+      
+      expect(() => {
+        const result = compile([story]);
+        expect(typeof result).toBe('string');
+      }).not.toThrow();
+    });
+
+    it('should have same functions in exports and global', () => {
+      // Test that parse and compile are the same functions
+      expect(parse).toBe(Extwee.parse);
+      expect(compile).toBe(Extwee.compile);
+      expect(parse).toBe(Extwee.parseTwine2ArchiveHTML);
+      expect(compile).toBe(Extwee.compileTwine2ArchiveHTML);
+    });
+  });
+});

package/test/Web/web-tws.test.js

@@ -0,0 +1,77 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * Tests for web-tws.js module
+ * Tests module exports and functionality
+ */
+
+import { describe, expect, it } from '@jest/globals';
+
+// Import to test basic functionality
+import { parse } from '../../src/Web/web-tws.js';
+import Extwee from '../../src/Web/web-tws.js';
+
+describe('web-tws.js module tests', () => {
+
+  describe('ES6 module exports', () => {
+    it('should export parse function', () => {
+      expect(parse).toBeDefined();
+      expect(typeof parse).toBe('function');
+    });
+
+    it('should export default object with parseTWS', () => {
+      expect(Extwee.parseTWS).toBeDefined();
+      expect(Extwee.parse).toBeDefined();
+      expect(typeof Extwee.parseTWS).toBe('function');
+      expect(typeof Extwee.parse).toBe('function');
+    });
+  });
+
+  describe('Global object assignment', () => {
+    it('should assign functions to global object when available', () => {
+      // In Node.js environment, should assign to globalThis
+      expect(globalThis.Extwee).toBeDefined();
+      expect(globalThis.Extwee.parseTWS).toBeDefined();
+      expect(typeof globalThis.Extwee.parseTWS).toBe('function');
+    });
+
+    it('should preserve existing Extwee properties', () => {
+      // Should not overwrite the entire object, just add properties
+      if (globalThis.Extwee && globalThis.Extwee.version) {
+        expect(globalThis.Extwee.version).toBeDefined();
+      }
+      expect(globalThis.Extwee.parseTWS).toBeDefined();
+    });
+  });
+
+  describe('Functional integration tests', () => {
+    it('should have working parseTWS function', () => {
+      // Create a minimal valid TWS buffer (pickled data)
+      // This is a very basic test - TWS parsing is complex
+      const validBuffer = Buffer.from([
+        0x80, 0x02, // Python pickle protocol version 2
+        0x7d, 0x71, 0x00, // Empty dict
+        0x2e // STOP
+      ]);
+      
+      expect(() => {
+        const result = parse(validBuffer);
+        expect(result).toBeDefined();
+      }).not.toThrow();
+    });
+
+    it('should throw error for invalid input', () => {
+      expect(() => {
+        parse("not a buffer");
+      }).toThrow();
+    });
+
+    it('should have same functions in exports and global', () => {
+      // Test that parse is the same function
+      expect(parse).toBe(Extwee.parse);
+      expect(parse).toBe(Extwee.parseTWS);
+    });
+  });
+});

package/types/src/Story.d.ts

@@ -251,5 +251,5 @@ export class Story {
     #private;
 }
 export const creatorName: "extwee";
-export const creatorVersion: "2.3.4";
+export const creatorVersion: "2.3.5";
 import Passage from './Passage.js';

package/types/src/Twee/parse.d.ts

@@ -6,4 +6,25 @@
  * @returns {Story} story
  */
 export function parse(fileContents: string): Story;
+/**
+ * Escapes Twee 3 metacharacters according to the specification.
+ * This is used when writing Twee files to ensure special characters are properly escaped.
+ * @function escapeTweeMetacharacters
+ * @param {string} text - Text to escape
+ * @returns {string} Escaped text
+ */
+export function escapeTweeMetacharacters(text: string): string;
+/**
+ * Unescapes Twee 3 metacharacters according to the specification.
+ *
+ * From the Twee 3 specification:
+ * - Encoding: To avoid ambiguity, non-escape backslashes must also be escaped via
+ * the same mechanism (i.e. `foo\bar` must become `foo\\bar`).
+ * - Decoding: To make decoding more robust, any escaped character within a chunk of
+ * encoded text must yield the character minus the backslash (i.e. `\q` must yield `q`).
+ * @function unescapeTweeMetacharacters
+ * @param {string} text - Text to unescape
+ * @returns {string} Unescaped text
+ */
+export function unescapeTweeMetacharacters(text: string): string;
 import { Story } from '../Story.js';