extwee 2.3.11 → 2.3.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/CHANGELOG.md +219 -0
  2. package/CONTRIBUTING.md +305 -0
  3. package/README.md +16 -0
  4. package/build/extwee.core.min.js +1 -1
  5. package/build/extwee.twine1html.min.js +1 -1
  6. package/build/extwee.twine2archive.min.js +1 -1
  7. package/build/extwee.tws.min.js +1 -1
  8. package/logs/arrays.html +79 -0
  9. package/logs/arrays.twee +64 -0
  10. package/logs/example.html +47 -0
  11. package/logs/fixing.js +23 -0
  12. package/logs/format-fixed.js +8 -0
  13. package/logs/format.js +8 -0
  14. package/logs/test-entities.cjs +40 -0
  15. package/package.json +19 -16
  16. package/src/Story.js +2 -2
  17. package/types/src/Story.d.ts +1 -1
  18. package/.github/FUNDING.yml +0 -3
  19. package/.github/codeql-analysis.yml +0 -51
  20. package/.github/dependabot.yml +0 -11
  21. package/.github/workflows/dependabot-automerge.yml +0 -23
  22. package/.github/workflows/nodejs.yml +0 -28
  23. package/.travis.yml +0 -13
  24. package/babel.config.json +0 -18
  25. package/docs/.nojekyll +0 -0
  26. package/docs/README.md +0 -224
  27. package/docs/_sidebar.md +0 -19
  28. package/docs/build/extwee.core.min.js +0 -1
  29. package/docs/build/extwee.twine1html.min.js +0 -1
  30. package/docs/build/extwee.twine2archive.min.js +0 -1
  31. package/docs/build/extwee.tws.min.js +0 -1
  32. package/docs/demos/compiler/extwee.core.min.js +0 -1
  33. package/docs/demos/compiler/index.css +0 -105
  34. package/docs/demos/compiler/index.html +0 -359
  35. package/docs/demos/decompile/extwee.core.min.js +0 -1
  36. package/docs/demos/decompile/index.css +0 -584
  37. package/docs/demos/decompile/index.html +0 -468
  38. package/docs/examples/dynamicPassages.md +0 -28
  39. package/docs/examples/jsonToTwee.md +0 -23
  40. package/docs/examples/twsToTwee.md +0 -25
  41. package/docs/formats/json.md +0 -17
  42. package/docs/formats/twee.md +0 -13
  43. package/docs/formats/twine1HTML.md +0 -13
  44. package/docs/formats/twine2ArchiveHTML.md +0 -13
  45. package/docs/formats/twine2HTML.md +0 -13
  46. package/docs/formats/tws.md +0 -9
  47. package/docs/index.html +0 -26
  48. package/docs/install/npm.md +0 -16
  49. package/docs/install/npx.md +0 -79
  50. package/docs/objects/passage.md +0 -47
  51. package/docs/objects/story.md +0 -69
  52. package/docs/objects/storyformat.md +0 -27
  53. package/eslint.config.js +0 -28
  54. package/extwee.config.json +0 -6
  55. package/extwee.config.md +0 -67
  56. package/jest.config.json +0 -5
  57. package/test/CLI/CLI.test.js +0 -49
  58. package/test/CLI/files/example.json +0 -1
  59. package/test/CLI/files/example6.twee +0 -22
  60. package/test/CLI/files/harlowe.js +0 -3
  61. package/test/CLI/files/input.html +0 -47
  62. package/test/CLI/files/output/test.twee +0 -0
  63. package/test/CLI/files/test.twee +0 -18
  64. package/test/CLI/files/tweeExample.twee +0 -17
  65. package/test/CLI/files/twine1/LICENSE.txt +0 -32
  66. package/test/CLI/files/twine1/code.js +0 -5
  67. package/test/CLI/files/twine1/engine.js +0 -43
  68. package/test/CLI/files/twine1/header.html +0 -325
  69. package/test/CLI/files/twine1Test.html +0 -371
  70. package/test/CLI/files/twineExample.html +0 -16
  71. package/test/Config/Config.test.js +0 -76
  72. package/test/Config/files/empty.json +0 -3
  73. package/test/Config/files/full.json +0 -8
  74. package/test/Config/files/invalid.json +0 -1
  75. package/test/Config/files/valid.json +0 -6
  76. package/test/Config/isDirectory.test.js +0 -50
  77. package/test/Config/isFile.test.js +0 -53
  78. package/test/Config/loadStoryFormat.test.js +0 -117
  79. package/test/Config/readDirectories.test.js +0 -78
  80. package/test/IFID/IFID.Generate.test.js +0 -10
  81. package/test/JSON/JSON.Parse.test.js +0 -316
  82. package/test/Objects/Passage.test.js +0 -274
  83. package/test/Objects/SnowmanCompatibility.test.js +0 -111
  84. package/test/Objects/Story.test.js +0 -1075
  85. package/test/Objects/StoryFormat.test.js +0 -219
  86. package/test/Roundtrip/Files/Example1.html +0 -64
  87. package/test/Roundtrip/Files/LICENSE +0 -19
  88. package/test/Roundtrip/Files/example1.twee +0 -10
  89. package/test/Roundtrip/Files/example2.twee +0 -27
  90. package/test/Roundtrip/Files/example4.twee +0 -27
  91. package/test/Roundtrip/Files/harlowe.js +0 -3
  92. package/test/Roundtrip/Files/round.html +0 -49
  93. package/test/Roundtrip/Roundtrip.test.js +0 -54
  94. package/test/StoryFormat/StoryFormat.Parse.test.js +0 -479
  95. package/test/TWS/Parse.test.js +0 -56
  96. package/test/TWS/TWSParser/Example5.tws +0 -414
  97. package/test/TWS/TWSParser/noscale.tws +0 -0
  98. package/test/TWS/TWSParser/nostory.tws +0 -0
  99. package/test/Twee/Twee.Escaping.test.js +0 -200
  100. package/test/Twee/Twee.Parse.test.js +0 -108
  101. package/test/Twee/TweeParser/cursed.twee +0 -16
  102. package/test/Twee/TweeParser/cycling.twee +0 -75
  103. package/test/Twee/TweeParser/emptytags.twee +0 -2
  104. package/test/Twee/TweeParser/example.twee +0 -32
  105. package/test/Twee/TweeParser/malformed.twee +0 -2
  106. package/test/Twee/TweeParser/missing.twee +0 -19
  107. package/test/Twee/TweeParser/multipleScriptPassages.twee +0 -19
  108. package/test/Twee/TweeParser/multipleStyleTag.twee +0 -19
  109. package/test/Twee/TweeParser/multipletags.twee +0 -10
  110. package/test/Twee/TweeParser/noTitle.twee +0 -2
  111. package/test/Twee/TweeParser/notes.twee +0 -16
  112. package/test/Twee/TweeParser/pasagemetadataerror.twee +0 -2
  113. package/test/Twee/TweeParser/scriptPassage.twee +0 -16
  114. package/test/Twee/TweeParser/singletag.twee +0 -13
  115. package/test/Twee/TweeParser/start.twee +0 -2
  116. package/test/Twee/TweeParser/startMetadata.twee +0 -14
  117. package/test/Twee/TweeParser/storydataerror.twee +0 -25
  118. package/test/Twee/TweeParser/style.twee +0 -16
  119. package/test/Twee/TweeParser/stylePassage.twee +0 -16
  120. package/test/Twee/TweeParser/test.twee +0 -25
  121. package/test/Twine1HTML/Twine1HTML.Compile.test.js +0 -180
  122. package/test/Twine1HTML/Twine1HTML.Parse.Web.test.js +0 -484
  123. package/test/Twine1HTML/Twine1HTML.Parse.test.js +0 -183
  124. package/test/Twine1HTML/Twine1HTMLCompiler/Twine1/LICENSE +0 -674
  125. package/test/Twine1HTML/Twine1HTMLCompiler/Twine1/engine.js +0 -43
  126. package/test/Twine1HTML/Twine1HTMLCompiler/Twine1/jquery.js +0 -4
  127. package/test/Twine1HTML/Twine1HTMLCompiler/Twine1/modernizr.js +0 -4
  128. package/test/Twine1HTML/Twine1HTMLCompiler/engineTest.html +0 -1
  129. package/test/Twine1HTML/Twine1HTMLCompiler/jonah-1.4.2/LICENSE +0 -32
  130. package/test/Twine1HTML/Twine1HTMLCompiler/jonah-1.4.2/code.js +0 -4
  131. package/test/Twine1HTML/Twine1HTMLCompiler/jonah-1.4.2/header.html +0 -327
  132. package/test/Twine1HTML/Twine1HTMLCompiler/test.html +0 -0
  133. package/test/Twine1HTML/Twine1HTMLCompiler/test1.html +0 -6
  134. package/test/Twine1HTML/Twine1HTMLCompiler/test2.html +0 -6
  135. package/test/Twine1HTML/Twine1HTMLCompiler/test3.html +0 -43
  136. package/test/Twine1HTML/Twine1HTMLCompiler/test4.html +0 -372
  137. package/test/Twine1HTML/Twine1HTMLCompiler/test5.html +0 -372
  138. package/test/Twine2ArchiveHTML/Twine2ArchiveHTML.Compile.test.js +0 -35
  139. package/test/Twine2ArchiveHTML/Twine2ArchiveHTML.Parse.Web.test.js +0 -293
  140. package/test/Twine2ArchiveHTML/Twine2ArchiveHTML.Parse.test.js +0 -42
  141. package/test/Twine2ArchiveHTML/Twine2ArchiveHTMLCompiler/test1.html +0 -6
  142. package/test/Twine2ArchiveHTML/Twine2ArchiveHTMLParser/test1.html +0 -3
  143. package/test/Twine2HTML/Twine2HTML.Compile.test.js +0 -139
  144. package/test/Twine2HTML/Twine2HTML.Parse.Web.test.js +0 -329
  145. package/test/Twine2HTML/Twine2HTML.Parse.test.js +0 -192
  146. package/test/Twine2HTML/Twine2HTMLCompiler/TestTags.html +0 -42
  147. package/test/Twine2HTML/Twine2HTMLCompiler/creator.html +0 -50
  148. package/test/Twine2HTML/Twine2HTMLCompiler/example6.twee +0 -16
  149. package/test/Twine2HTML/Twine2HTMLCompiler/format.js +0 -9
  150. package/test/Twine2HTML/Twine2HTMLCompiler/missingStoryTitle.twee +0 -29
  151. package/test/Twine2HTML/Twine2HTMLCompiler/test11.html +0 -121
  152. package/test/Twine2HTML/Twine2HTMLCompiler/test2.html +0 -58
  153. package/test/Twine2HTML/Twine2HTMLCompiler/test3.html +0 -49
  154. package/test/Twine2HTML/Twine2HTMLCompiler/test4.html +0 -50
  155. package/test/Twine2HTML/Twine2HTMLCompiler/test6.html +0 -49
  156. package/test/Twine2HTML/Twine2HTMLParser/Example1.html +0 -53
  157. package/test/Twine2HTML/Twine2HTMLParser/Tags.html +0 -15
  158. package/test/Twine2HTML/Twine2HTMLParser/lyingStartnode.html +0 -15
  159. package/test/Twine2HTML/Twine2HTMLParser/lyingTagColors.html +0 -48
  160. package/test/Twine2HTML/Twine2HTMLParser/missingCreator.html +0 -11
  161. package/test/Twine2HTML/Twine2HTMLParser/missingCreatorVersion.html +0 -11
  162. package/test/Twine2HTML/Twine2HTMLParser/missingFormat.html +0 -11
  163. package/test/Twine2HTML/Twine2HTMLParser/missingFormatVersion.html +0 -11
  164. package/test/Twine2HTML/Twine2HTMLParser/missingIFID.html +0 -11
  165. package/test/Twine2HTML/Twine2HTMLParser/missingPassageTags.html +0 -15
  166. package/test/Twine2HTML/Twine2HTMLParser/missingPosition.html +0 -15
  167. package/test/Twine2HTML/Twine2HTMLParser/missingScript.html +0 -14
  168. package/test/Twine2HTML/Twine2HTMLParser/missingSize.html +0 -35
  169. package/test/Twine2HTML/Twine2HTMLParser/missingStartnode.html +0 -11
  170. package/test/Twine2HTML/Twine2HTMLParser/missingStyle.html +0 -14
  171. package/test/Twine2HTML/Twine2HTMLParser/missingZoom.html +0 -11
  172. package/test/Twine2HTML/Twine2HTMLParser/tagColors.html +0 -31
  173. package/test/Twine2HTML/Twine2HTMLParser/twineExample.html +0 -23
  174. package/test/Twine2HTML/Twine2HTMLParser/twineExample2.html +0 -15
  175. package/test/Twine2HTML/Twine2HTMLParser/twineExample3.html +0 -15
  176. package/test/Twine2HTML/Twine2HTMLParser/unescaping.html +0 -33
  177. package/test/Web/web-core-coverage.test.js +0 -175
  178. package/test/Web/web-core-global.test.js +0 -93
  179. package/test/Web/web-core.test.js +0 -156
  180. package/test/Web/web-exports.test.js +0 -136
  181. package/test/Web/web-twine1html.test.js +0 -105
  182. package/test/Web/web-twine2archive.test.js +0 -96
  183. package/test/Web/web-tws.test.js +0 -77
  184. package/test/Web/window.Extwee.test.js +0 -97
  185. package/tsconfig.json +0 -21
  186. package/webpack.config.js +0 -47
package/logs/test-entities.cjs ADDED
@@ -0,0 +1,40 @@
1
+ const jsdom = require('jsdom');
2
+ const { JSDOM } = jsdom;
3
+
4
+ // Test in a DOM context
5
+ const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
6
+ const doc = dom.window.document;
7
+
8
+ // Create elements with both encodings
9
+ const div1 = doc.createElement('div');
10
+ div1.setAttribute('data-test', 'test&apos;value');
11
+ const div2 = doc.createElement('div');
12
+ div2.setAttribute('data-test', 'test&#39;value');
13
+
14
+ console.log('div1 getAttribute:', div1.getAttribute('data-test'));
15
+ console.log('div2 getAttribute:', div2.getAttribute('data-test'));
16
+ console.log('Are they equal?', div1.getAttribute('data-test') === div2.getAttribute('data-test'));
17
+
18
+ // Test with innerHTML
19
+ div1.innerHTML = 'Text with &apos;quote&apos;';
20
+ div2.innerHTML = 'Text with &#39;quote&#39;';
21
+ console.log('div1 textContent:', div1.textContent);
22
+ console.log('div2 textContent:', div2.textContent);
23
+ console.log('Text content equal?', div1.textContent === div2.textContent);
24
+
25
+ // Test parsing HTML with both
26
+ const html1 = '<tw-passagedata name="Test" data-value="It&apos;s">Content</tw-passagedata>';
27
+ const html2 = '<tw-passagedata name="Test" data-value="It&#39;s">Content</tw-passagedata>';
28
+
29
+ const container1 = doc.createElement('div');
30
+ const container2 = doc.createElement('div');
31
+ container1.innerHTML = html1;
32
+ container2.innerHTML = html2;
33
+
34
+ const passage1 = container1.querySelector('tw-passagedata');
35
+ const passage2 = container2.querySelector('tw-passagedata');
36
+
37
+ console.log('\nParsing tw-passagedata:');
38
+ console.log('passage1 data-value:', passage1.getAttribute('data-value'));
39
+ console.log('passage2 data-value:', passage2.getAttribute('data-value'));
40
+ console.log('Attributes equal?', passage1.getAttribute('data-value') === passage2.getAttribute('data-value'));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "extwee",
3
- "version": "2.3.11",
3
+ "version": "2.3.13",
4
4
  "description": "A story compiler tool using Twine-compatible formats",
5
5
  "author": "Dan Cox",
6
6
  "main": "index.js",
@@ -36,33 +36,33 @@
36
36
  "commander": "^14.0.2",
37
37
  "graphemer": "^1.4.0",
38
38
  "html-entities": "^2.6.0",
39
- "node-html-parser": "^7.0.1",
39
+ "node-html-parser": "^7.0.2",
40
40
  "pickleparser": "^0.2.1",
41
41
  "semver": "^7.7.3",
42
42
  "shelljs": "^0.10.0"
43
43
  },
44
44
  "devDependencies": {
45
- "@babel/cli": "^7.28.3",
46
- "@babel/core": "^7.28.5",
47
- "@babel/preset-env": "^7.28.5",
48
- "@eslint/js": "^9.39.1",
49
- "@inquirer/prompts": "^8.0.1",
50
- "@types/node": "^24.10.1",
45
+ "@babel/cli": "^7.28.6",
46
+ "@babel/core": "^7.28.6",
47
+ "@babel/preset-env": "^7.28.6",
48
+ "@eslint/js": "^9.39.2",
49
+ "@inquirer/prompts": "^8.2.0",
50
+ "@types/node": "^25.0.9",
51
51
  "@types/semver": "^7.7.1",
52
52
  "babel-loader": "^10.0.0",
53
53
  "clean-jsdoc-theme": "^4.3.0",
54
54
  "core-js": "^3.47.0",
55
- "eslint": "^9.39.1",
56
- "eslint-plugin-jest": "^29.1.0",
57
- "eslint-plugin-jsdoc": "^61.3.0",
58
- "globals": "^16.5.0",
55
+ "eslint": "^9.39.2",
56
+ "eslint-plugin-jest": "^29.12.1",
57
+ "eslint-plugin-jsdoc": "^62.3.0",
58
+ "globals": "^17.0.0",
59
59
  "jest": "^30.2.0",
60
60
  "jest-environment-jsdom": "^30.2.0",
61
61
  "regenerator-runtime": "^0.14.1",
62
62
  "typescript": "^5.9.3",
63
- "typescript-eslint": "^8.47.0",
64
- "webpack": "^5.103.0",
65
- "webpack-bundle-analyzer": "^5.0.1",
63
+ "typescript-eslint": "^8.53.1",
64
+ "webpack": "^5.104.1",
65
+ "webpack-bundle-analyzer": "^5.1.1",
66
66
  "webpack-cli": "^6.0.1"
67
67
  },
68
68
  "repository": {
@@ -73,5 +73,8 @@
73
73
  "url": "https://github.com/videlais/extwee/issues"
74
74
  },
75
75
  "type": "module",
76
- "types": "./types/index.d.ts"
76
+ "types": "./types/index.d.ts",
77
+ "engines": {
78
+ "node": ">=18.18.0"
79
+ }
77
80
  }
package/src/Story.js CHANGED
@@ -7,7 +7,7 @@ import { encode } from 'html-entities';
7
7
  const creatorName = 'extwee';
8
8
 
9
9
  // Set the creator version.
10
- const creatorVersion = '2.3.11';
10
+ const creatorVersion = '2.3.13';
11
11
 
12
12
  /**
13
13
  * Story class.
@@ -436,7 +436,7 @@ class Story {
436
436
  if (Object.prototype.hasOwnProperty.call(metadata, 'tag-colors')) {
437
437
  this.tagColors = metadata['tag-colors'];
438
438
  }
439
- } catch (event) {
439
+ } catch {
440
440
  // Ignore errors.
441
441
  }
442
442
 
package/types/src/Story.d.ts CHANGED
@@ -251,5 +251,5 @@ export class Story {
251
251
  #private;
252
252
  }
253
253
  export const creatorName: "extwee";
254
- export const creatorVersion: "2.3.11";
254
+ export const creatorVersion: "2.3.13";
255
255
  import Passage from './Passage.js';
package/.github/FUNDING.yml DELETED
@@ -1,3 +0,0 @@
1
- # These are supported funding model platforms
2
-
3
- ko_fi: videlais
package/.github/codeql-analysis.yml DELETED
@@ -1,51 +0,0 @@
1
- name: "CodeQL"
2
-
3
- on:
4
- push:
5
- branches: [ develop ]
6
- paths-ignore:
7
- - 'test/**'
8
- pull_request:
9
- branches: [ develop ]
10
- paths-ignore:
11
- - 'test/**'
12
-
13
- jobs:
14
- analyze:
15
- name: Analyze
16
- runs-on: ubuntu-latest
17
-
18
- strategy:
19
- fail-fast: false
20
- matrix:
21
- language: [ 'javascript' ]
22
-
23
- steps:
24
- - name: Checkout repository
25
- uses: actions/checkout@v3
26
-
27
- - name: Initialize CodeQL
28
- uses: github/codeql-action/init@v2
29
- with:
30
- languages: ${{ matrix.language }}
31
-
32
- - name: Perform CodeQL Analysis
33
- uses: github/codeql-action/analyze@v2
34
- with:
35
- upload: false # disable the upload here - we will upload in a different action
36
- output: sarif-results
37
-
38
- - name: filter-sarif
39
- uses: advanced-security/filter-sarif@v1
40
- with:
41
- # filter out all test files unless they contain a sql-injection vulnerability
42
- patterns:
43
- -test/**/*
44
- +test/**/*:js/sql-injection
45
- input: sarif-results/${{ matrix.language }}.sarif
46
- output: sarif-results/${{ matrix.language }}.sarif
47
-
48
- - name: Upload SARIF
49
- uses: github/codeql-action/upload-sarif@v2
50
- with:
51
- sarif_file: sarif-results/${{ matrix.language }}.sarif
package/.github/dependabot.yml DELETED
@@ -1,11 +0,0 @@
1
- # To get started with Dependabot version updates, you'll need to specify which
2
- # package ecosystems to update and where the package manifests are located.
3
- # Please see the documentation for all configuration options:
4
- # https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
5
-
6
- version: 2
7
- updates:
8
- - package-ecosystem: "npm" # See documentation for possible values
9
- directory: "/" # Location of package manifests
10
- schedule:
11
- interval: "monthly"
package/.github/workflows/dependabot-automerge.yml DELETED
@@ -1,23 +0,0 @@
1
- name: Dependabot auto-merge
2
- on: pull_request
3
-
4
- permissions:
5
- contents: write
6
- pull-requests: write
7
-
8
- jobs:
9
- dependabot:
10
- runs-on: ubuntu-latest
11
- if: github.event.pull_request.user.login == 'dependabot[bot]' && github.repository == 'videlais/extwee'
12
- steps:
13
- - name: Dependabot metadata
14
- id: metadata
15
- uses: dependabot/fetch-metadata@d7267f607e9d3fb96fc2fbe83e0af444713e90b7
16
- with:
17
- github-token: "${{ secrets.GITHUB_TOKEN }}"
18
- - name: Enable auto-merge for Dependabot PRs
19
- if: steps.metadata.outputs.update-type == 'version-update:semver-patch'
20
- run: gh pr merge --auto --merge "$PR_URL"
21
- env:
22
- PR_URL: ${{github.event.pull_request.html_url}}
23
- GH_TOKEN: ${{secrets.GITHUB_TOKEN}}
package/.github/workflows/nodejs.yml DELETED
@@ -1,28 +0,0 @@
1
- name: Node CI
2
-
3
- on: [push]
4
-
5
- permissions:
6
- contents: read
7
-
8
- jobs:
9
- build:
10
-
11
- runs-on: ubuntu-latest
12
-
13
- strategy:
14
- matrix:
15
- node-version: [23.x]
16
-
17
- steps:
18
- - uses: actions/checkout@v4
19
- - name: Use Node.js ${{ matrix.node-version }}
20
- uses: actions/setup-node@v4
21
- with:
22
- node-version: ${{ matrix.node-version }}
23
- - run: npm install
24
- - run: npm run lint
25
- - run: npm run lint:test
26
- - run: npm run test
27
- env:
28
- CI: true
package/.travis.yml DELETED
@@ -1,13 +0,0 @@
1
- language: node_js
2
-
3
- node_js:
4
- - "node"
5
-
6
- install:
7
- - npm install
8
- - npm install codecov
9
-
10
- script:
11
- - npm run test
12
- - npm run report-coverage
13
- - codecov
package/babel.config.json DELETED
@@ -1,18 +0,0 @@
1
- {
2
- "plugins": [],
3
- "presets": [
4
- [
5
- "@babel/env",
6
- {
7
- "targets": {
8
- "edge": "17",
9
- "firefox": "60",
10
- "chrome": "67",
11
- "safari": "11.1"
12
- },
13
- "useBuiltIns": "usage",
14
- "corejs": "3.8.0"
15
- }
16
- ]
17
- ]
18
- }
package/docs/.nojekyll DELETED
File without changes
package/docs/README.md DELETED
@@ -1,224 +0,0 @@
1
- <a name="readme-top"></a>
2
-
3
- [![codecov](https://codecov.io/gh/videlais/extwee/branch/master/graph/badge.svg)](https://codecov.io/gh/videlais/extwee)
4
-
5
- [![npm version](https://badge.fury.io/js/extwee.svg)](https://badge.fury.io/js/extwee)
6
-
7
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8
-
9
- [![NPM Badge](https://nodei.co/npm/extwee.png?downloads=true)](https://www.npmjs.com/package/extwee)
10
-
11
- ## Table of Contents
12
-
13
- <ol>
14
- <li><a href="#story-compilation">Story Compilation</a></li>
15
- <li><a href="#format-support">Format Support</a></li>
16
- <li><a href="#usage">Node and Web API</a></li>
17
- <ol>
18
- <li><a href="#objects">Objects</a></li>
19
- <li><a href="#parsers">Parsers</a></li>
20
- <li><a href="#compilers">Compilers</a></li>
21
- </ol>
22
- <li><a href="#web-build-imports">Web Build Imports</a></li>
23
- <li><a href="#documentation">Documentation</a></li>
24
- <li><a href="#command-line-usage">Command-Line Usage</a></li>
25
- <li><a href="#config-file-usage">Config File Usage</a></li>
26
- <li><a href="#escaping- meta-characters">Escaping Meta-Characters</a></li>
27
- <li><a href="#license">License</a></li>
28
- </ol>
29
-
30
- ## Story Compilation
31
-
32
- The process of *story compilation* converts human-readable content, what is generally called a *story*, into a playable format such as HyperText Markup Language (HTML). The result is then presented as links or other visual, interactive elements for another party.
33
-
34
- The term *compilation* is used because different parts of code are put together in a specific arrangement to enable later play. As part of Twine-compatible HTML, this means combining JavaScript code (generally a "story format") with story HTML data.
35
-
36
- Extwee is **not** an authoring tool. It cannot be used to create story content. This data must be created using other tools or processes. Extwee can then *compile* the content with story format code to produce something playable.
37
-
38
- Playable formats are the following and require external story formats[^1] to enable play:
39
-
40
- - Twine 2 HTML
41
- - Twine 1 HTML
42
-
43
- More human-readable formats include:
44
-
45
- - Twee 3[^2]
46
- - Twine 2 JSON[^3]
47
-
48
- From 2009 to 2015, Twine 1 supported a now [historical format named TWS](https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-twsoutput.md). This was a binary format used for archival purposes. Extwee can read this format but does not support creating it because no other tools, including current versions of Twine, accept it as valid input.
49
-
50
- Twine 2 supports exporting a collection of stories (known as a *library*) in the [Twine 2 Archive HTML format](https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-archive-spec.md). Extwee can also read and write this format, creating either a collection of stories from the data or writing a collection of internal objects to a file.
51
-
52
- [^1]: Extwee does not include or publish story formats. These can be found in the [Story Format Archive (SFA)](https://github.com/videlais/story-formats-archive).
53
-
54
- [^2]: Twee exists in three versions. The first existed between 2006 to 2009 and was part of Twine 1. The move to Twine 2 in 2009 dropped support and the story compilation tools [Twee2](https://dan-q.github.io/twee2/) and [Tweego](https://www.motoslave.net/tweego/) adopted their own extensions and modifications. Beginning in 2017, work was done to unite the different projects. This resulted in [Twee 3](https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md) in March 2021.
55
-
56
- [^3]: In October 2023, JavaScript Object Notation (JSON) was added as a supported community format for story compilation tools. Extwee is the first tool to support this format.
57
-
58
- ## Format Support
59
-
60
- Extwee supports multiple historical and current Twine-compatible formats.
61
-
62
- | Format | Input | Output |
63
- |----------------------------------------------------------------------------------------------------------------------------------|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
64
- | [Twine 1 HTML (2006 - 2015)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md ) | Yes | Partial support. Twine 1 HTML can be produced, but the `StorySettings` optional passage introduced in Twine 1.4.0 requires external libraries like jQuery not included with Extwee. |
65
- | [Twine 1 TWS (2009 - 2015)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-twsoutput.md ) | Yes | Extwee does not support TWS (Python pickle) output because no current version of Twine or other story compilation tool produces this historical format. |
66
- | [Twine 2 HTML (2015 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md ) | Yes | Yes |
67
- | [Twine 2 Archive HTML (2015 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-archive-spec.md ) | Yes | Yes |
68
- | [Twee 3 (2021 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md ) | Yes | Yes |
69
- | [Twine 2 JSON (2023 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-jsonoutput-doc.md ) | Yes | Yes |
70
- | [Twine 2 Story Format (2015 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md ) | Yes | Yes |
71
-
72
- **Note:** Round-trip translations can present problems because of required fields and properties per format. Some metadata may be added or removed based on the specification being followed.
73
-
74
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
75
-
76
- ## Node and Web API
77
-
78
- The following objects and methods are available in Node.js or browser contexts.
79
-
80
- **Note:** When used in a browser context, all objects and methods are part of the `window.Extwee` global.
81
-
82
- ### Objects
83
-
84
- An object must be created using either the `new` keyword in JavaScript or as the result of parsing data.
85
-
86
- - `StoryFormat`
87
- - `Passage`
88
- - `Story`
89
-
90
- Story and Passage objects can generate multiple output formats: `toTwee()`, `toTwine1HTML()`, `toTwine2HTML()`, and `toJSON()`. Stories cannot be played in a browser without the corresponding compiler combining it with story format data.
91
-
92
- The StoryFormat object supports `toString()` method of producing a tab-separated JSON output and `toJSON()` method of generating JSON output matching the Twine 2 Story Format Specification.
93
-
94
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
95
-
96
- ### Parsers
97
-
98
- Translates output formats such as HTML, Twee, JSON, or JSONP into objects.
99
-
100
- **Note:** Twine 1 story formats exist across multiple files (`header.html` and optional `code.js`). They cannot be parsed into a `StoryFormat` object.
101
-
102
- - `parseTwee()`
103
- - `parseJSON()`
104
- - `parseStoryFormat()`
105
- - `parseTwine1HTML()`
106
- - `parseTwine2HTML()`
107
- - `parseTwine2ArchiveHTML()`
108
-
109
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
110
-
111
- ### Compilers
112
-
113
- Compiles story, story formats, or other data into an archive or playable format.
114
-
115
- - `compileTwine2HTML()`
116
- - `compileTwine1HTML()`
117
- - `compileTwine2ArchiveHTML()`
118
- - `compileStoryFormat()`
119
-
120
- To create playable Twine 1 HTML, an `engine.js` file must be supplied. (See [Story Format Archive](https://github.com/videlais/story-formats-archive/tree/main/official/twine1/engine/1.4.2) for available Twine 1 `engine.js` file.)
121
-
122
- Compilation of a story format adds the necessary function wrapper to convert the JSON output, via `toJSON()`, to JSONP.
123
-
124
- ### Support Functionality
125
-
126
- Multiple Twine formats support using [an IFID](https://ifdb.org/help-ifid) to identify one work from another.
127
-
128
- As part of its API, the Extwee method `generateIFID()` can be used to create a new IFID for a `Story` object or as part of other processes.
129
-
130
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
131
-
132
- ## Web Build Imports
133
-
134
- For users who want to use pre-built, minified versions optimized for browser environments, Extwee provides several web build exports:
135
-
136
- ### Available Web Builds
137
-
138
- - **Core Build**: `import Extwee from 'extwee/web'` - Complete functionality including parsers, compilers, and core utilities
139
- - **Twine 1 HTML**: `import Extwee from 'extwee/web/twine1html'` - Specialized for Twine 1 HTML parsing and compilation
140
- - **Twine 2 Archive HTML**: `import Extwee from 'extwee/web/twine2archive'` - Specialized for Twine 2 Archive HTML parsing and compilation
141
- - **TWS Format**: `import Extwee from 'extwee/web/tws'` - Specialized for TWS (Twine 1 workspace) parsing
142
-
143
- ### Usage Examples
144
-
145
- ```javascript
146
- // Use the full core build
147
- import Extwee from 'extwee/web';
148
- const story = new Extwee.Story();
149
- const ifid = Extwee.generateIFID();
150
-
151
- // Use a specialized build for smaller bundle size
152
- import Extwee from 'extwee/web/twine1html';
153
- const story = Extwee.parseTwine1HTML(htmlContent);
154
- ```
155
-
156
- These web builds are UMD-compatible and can be used with module bundlers like webpack, or loaded directly in browsers. They are optimized and minified for production use.
157
-
158
- **Note:** Web builds include their dependencies bundled, making them suitable for browser environments but larger than the Node.js imports which rely on external dependencies.
159
-
160
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
161
-
162
- ## Documentation
163
-
164
- Extwee has [documentation hosted on GitHub Pages](https://videlais.github.io/extwee/#/).
165
-
166
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
167
-
168
- ## Command-Line Usage
169
-
170
- Extwee supports a command-line interface for four general scenarios.
171
-
172
- **Notes:** As of Extwee 2.2.5, short and long command-line option flags are separated. Short options use one hyphen followed by one character and all long options begin with two hyphens and a name as word.
173
-
174
- ### Compiling Twee 3 + Twine 2 Story Format into Twine 2 HTML
175
-
176
- Compile Twee 3 + StoryFormat into Twine 2 HTML:
177
-
178
- `extwee -c -i <tweeFile> -s <storyFormat> -o <Twine2HTML>`
179
-
180
- ### De-compiling Twine 2 HTML into Twee 3
181
-
182
- De-compile Twine 2 HTML into Twee 3:
183
-
184
- `extwee -d -i <twine2HTML> -o <outputTwee>`
185
-
186
- ### Compiling Twee 3 into Twine 1 HTML
187
-
188
- Enabling Twine 1 mode requires using the `--twine1` long flag.
189
-
190
- Because Twine 1 story formats can be split across files, compilation requires the "engine" from Twine 1 named `engine.js`, the name of the story format, and then its `header.html` template code and the optional but often included `code.js` file.
191
-
192
- (Refer to the [Story Formats Archive](https://github.com/videlais/story-formats-archive) for access to historic `engine.js` and other files.)
193
-
194
- `extwee --twine1 -c -i <tweeFile> -o <Twine1HTML> --engine <engineJS> --name <storyFormatName> --codejs <CodeJS> --header <header>`
195
-
196
- ### De-compiling Twine 1 HTML into Twee 3
197
-
198
- Enabling Twine 1 mode requires using the `--twine1` flag.
199
-
200
- `extwee --twine1 -d -i <twine1HTML> -o <outputTwee>`
201
-
202
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
203
-
204
- ## Config File Usage
205
-
206
- When invoked from its command-line interface using `npx extwee`, it will look for a `extwee.config.json` file in the local directory. If found, and its fields are valid, processing will use the values found in the file.
207
-
208
- Consult the possible options in its [dedicated file](extwee.config.md).
209
-
210
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
211
-
212
- ## Tree Shaking Support
213
-
214
- For [advanced tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) patterns, most formats are broke into `compile.js` and `parse.js` files exporting associated `compile()` and `parse()` functions.
215
-
216
- When using the API, it is possible to only import a single function or object to produce smaller and potentially faster code in projects dependent on Extwee functionality.
217
-
218
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
219
-
220
- ## License
221
-
222
- Distributed under the MIT License. See `LICENSE.txt` for more information.
223
-
224
- <p align="right">(<a href="#readme-top">back to top</a>)</p>
package/docs/_sidebar.md DELETED
@@ -1,19 +0,0 @@
1
- - Installation and General Usage
2
- - [Using NPX (as part of workflow)](/install/npx.md)
3
- - [Using NPM (via API)](/install/npm.md)
4
- - Objects
5
- - [Passage](/objects/passage.md)
6
- - [Story](/objects/story.md)
7
- - [Story Format](/objects/storyformat.md)
8
- - Formats
9
- - [Twee 3](/formats/twee.md)
10
- - [Twine 2 HTML](/formats/twine2HTML.md)
11
- - [Twine 2 JSON](/formats/json.md)
12
- - [Twine 2 Archive HTML](/formats/twine2ArchiveHTML.md)
13
- - [Twine 1 HTML](/formats/twine1HTML.md)
14
- - [Twine 1 TWS](/formats/tws.md)
15
-
16
- - Examples
17
- - [Dynamically Generating Passages](/examples/dynamicPassages.md)
18
- - [Converting Twine 2 JSON into Twee 3](/examples/jsonToTwee.md)
19
- - [Converting Twine 1 TWS into Twee 3](/examples/twsToTwee.md)