Skip to content

v2.4.0 (September 2026)

Latest
Latest

Choose a tag to compare

View all tags
@videlais videlais released this 27 Sep 04:08
v2.4.0
bf66e03
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

What started as an overdue maintenance update for September 2026 shifted into needing to update to Babel 8, which then triggered other updates across GitHub runners and actions.

As part of reviewing several files, I also noticed that the JSDocs lines were missing or not correct in some places (from my work years ago). This was then re-written, which was when the toJSON() issue was found that is now an outstanding bug for a future update to fix. The update to the JSDocs lines also meant a review of the TypeScript definitions, which itself caused even more changes.

Because of the toJSON() issue, I'm now thinking about a 3.0 version and moving the entire project to TypeScript, which would have more easily caught the type issues in the documentation and potentially even the toJSON() problem.

Added

  • toJSONString() on Story, Passage, and StoryFormat, returning the same JSON string as toJSON(). Prefer it wherever JSON text is needed.

Changed

  • Moved the Babel toolchain to Babel 8 (@babel/core and @babel/preset-env 8.x, babel-plugin-polyfill-corejs3 1.x).
  • Development now requires Node 22.18+ or 24.11+ (a Babel 8 requirement). The published package still supports Node 18.18+.
  • GitHub CI test matrix now covers Node 24.x and 26.x (removed 22.x and 23.x).
  • Release binaries now embed Node 24 (previously Node 22).
  • Updated GitHub Actions to their latest major versions (checkout, setup-node, upload-artifact, download-artifact, codecov-action, action-gh-release).
  • npm test now rebuilds the CLI bundle first so bundle equivalence tests never run against a stale build.
  • Expanded and corrected JSDoc across src/: @throws on all setters and parse/compile functions, clearer property descriptions, and @example blocks for the main parse and compile functions.
  • TypeScript definitions are more precise:
    • Story.passages and Story.getPassagesByTag() now use Passage[] (previously any[]).
    • Passage.tags now uses string[] (previously any[]).
    • Story.tagColors now uses Record<string, string> (previously object).
    • Story.metadata and Passage.metadata now use Record<string, unknown> (previously object).
    • Web parser internals no longer produce any types.
  • ESLint now warns on missing JSDoc blocks, missing @throws, and descriptions that only repeat a name (src/ only).
  • Monthly dependency updates.

Deprecated

  • Relying on toJSON() returning a string. It is documented as unsafe to pass to JSON.stringify() and is planned to return an object in 3.0 (#799). Use toJSONString() for JSON text.

Fixed

  • compileStoryFormat() double-encoded its JSON, so the generated format.js passed a string instead of an object to window.storyFormat() and could not be read back by parseStoryFormat(). StoryFormat.toString() had the same problem. Both now output plain JSON, with new regression tests. (#797)
  • Codecov coverage uploads, which had been skipped on every CI run since Node 20.x was removed from the matrix, and were missing the newer token-based upload authentication.
  • Release workflow's Intel macOS build moved from the retired macos-13 runner to macos-15-intel.
  • Inaccurate JSDoc:
    • Config/parser listed the wrong returned fields.
    • StoryFormat.toJSON() was documented as returning an object instead of a string.
    • Twine2HTML/parse listed errors it does not throw.
    • isFile()/isDirectory() used non-JSDoc comments, so their types were missing.

What's Changed

  • Chore(deps-dev): Bump webpack from 5.108.1 to 5.108.3 by @dependabot[bot] in #775
  • Chore(deps-dev): Bump eslint-plugin-jest from 29.15.3 to 29.15.4 by @dependabot[bot] in #778
  • Chore(deps-dev): Bump typescript-eslint from 8.62.0 to 8.62.1 by @dependabot[bot] in #776
  • Chore(deps-dev): Bump fast-uri from 3.1.2 to 3.1.4 by @dependabot[bot] in #779
  • Chore(deps-dev): Bump @types/node from 26.1.1 to 26.1.2 by @dependabot[bot] in #782
  • Chore(deps): Bump node-html-parser from 9.0.0 to 9.0.1 by @dependabot[bot] in #783
  • Chore(deps-dev): Bump typescript-eslint from 8.64.0 to 8.65.0 by @dependabot[bot] in #781
  • Chore(deps-dev): Bump fast-uri from 3.1.4 to 3.1.5 by @dependabot[bot] in #786
  • Chore(deps-dev): Bump globals from 17.7.0 to 17.8.0 by @dependabot[bot] in #784
  • Chore(deps-dev): Bump eslint-plugin-jest from 29.15.4 to 29.16.0 by @dependabot[bot] in #785
  • Chore(deps): Bump brace-expansion by @dependabot[bot] in #787
  • Chore(deps-dev): Bump webpack-cli from 7.2.2 to 7.2.3 by @dependabot[bot] in #791
  • Chore(deps-dev): Bump eslint-plugin-jest from 29.16.2 to 29.16.5 by @dependabot[bot] in #789
  • Chore(deps-dev): Bump browserslist from 4.28.4 to 4.28.8 by @dependabot[bot] in #794
  • Chore(deps-dev): Bump eslint-plugin-jsdoc from 63.3.3 to 64.2.1 by @dependabot[bot] in #790
  • Chore(deps-dev): Bump babel-plugin-polyfill-corejs3 from 0.6.0 to 1.0.0 by @dependabot[bot] in #792
  • Chore(deps-dev): Bump @inquirer/prompts from 8.6.0 to 8.7.0 by @dependabot[bot] in #793
  • Chore(deps-dev): Bump webpack from 5.109.2 to 5.110.1 by @dependabot[bot] in #788
  • Chore(deps): Bump js-yaml from 3.15.1 to 3.15.2 by @dependabot[bot] in #795
  • Updating to babel 8 by @videlais in #796
  • Release 2.4.0: Babel 8, CI updates, JSDoc/types overhaul, and compileStoryFormat() fix by @videlais in #798

Full Changelog: v2.3.18...v2.4.0

What's Changed

  • Chore(deps-dev): Bump webpack from 5.108.1 to 5.108.3 by @dependabot[bot] in #775
  • Chore(deps-dev): Bump eslint-plugin-jest from 29.15.3 to 29.15.4 by @dependabot[bot] in #778
  • Chore(deps-dev): Bump typescript-eslint from 8.62.0 to 8.62.1 by @dependabot[bot] in #776
  • Chore(deps-dev): Bump fast-uri from 3.1.2 to 3.1.4 by @dependabot[bot] in #779
  • Chore(deps-dev): Bump @types/node from 26.1.1 to 26.1.2 by @dependabot[bot] in #782
  • Chore(deps): Bump node-html-parser from 9.0.0 to 9.0.1 by @dependabot[bot] in #783
  • Chore(deps-dev): Bump typescript-eslint from 8.64.0 to 8.65.0 by @dependabot[bot] in #781
  • Chore(deps-dev): Bump fast-uri from 3.1.4 to 3.1.5 by @dependabot[bot] in #786
  • Chore(deps-dev): Bump globals from 17.7.0 to 17.8.0 by @dependabot[bot] in #784
  • Chore(deps-dev): Bump eslint-plugin-jest from 29.15.4 to 29.16.0 by @dependabot[bot] in #785
  • Chore(deps): Bump brace-expansion by @dependabot[bot] in #787
  • Chore(deps-dev): Bump webpack-cli from 7.2.2 to 7.2.3 by @dependabot[bot] in #791
  • Chore(deps-dev): Bump eslint-plugin-jest from 29.16.2 to 29.16.5 by @dependabot[bot] in #789
  • Chore(deps-dev): Bump browserslist from 4.28.4 to 4.28.8 by @dependabot[bot] in #794
  • Chore(deps-dev): Bump eslint-plugin-jsdoc from 63.3.3 to 64.2.1 by @dependabot[bot] in #790
  • Chore(deps-dev): Bump babel-plugin-polyfill-corejs3 from 0.6.0 to 1.0.0 by @dependabot[bot] in #792
  • Chore(deps-dev): Bump @inquirer/prompts from 8.6.0 to 8.7.0 by @dependabot[bot] in #793
  • Chore(deps-dev): Bump webpack from 5.109.2 to 5.110.1 by @dependabot[bot] in #788
  • Chore(deps): Bump js-yaml from 3.15.1 to 3.15.2 by @dependabot[bot] in #795
  • Updating to babel 8 by @videlais in #796
  • Release 2.4.0: Babel 8, CI updates, JSDoc/types overhaul, and compileStoryFormat() fix by @videlais in #798

Full Changelog: v2.3.18...v2.4.0

Contributors

videlais and dependabot
Assets 7
Loading