Features

A detailed look at what Knot does today. Only SugarCube 2 has full language features; Harlowe, Chapbook, and Snowman are placeholder implementations with the build pipeline working.

Structural understanding, not just regex

Unlike tooling that bolts regular expressions onto a text editor, Knot actually parses your project into passages and the links between them. This structural model lets it answer questions that pattern matching gets wrong:

• "Where is this variable set?" — Knot tracks definitions across passages, not just mentions.
• "Is this passage reachable from Start?" — a graph reachability check, not a string search.
• "Which passages link here?" — reverse navigation through the link graph.
• "Are there any orphan passages?" — passages nothing links to, flagged automatically.

This is the core design principle behind Knot: model the project the way Twine itself models it, and the editor can give you real help instead of approximate help.

Variable tracker

The Variable Tracking panel shows where every variable is set, read, and how it flows across passages. For SugarCube, variable tracking is JavaScript-aware via the oxc parser, so it understands:

• <<set $x to 1>> — SugarCube macro syntax
• <<run $x++>> — inline expressions
• JavaScript inside <<script>> blocks
• Variables passed through <<include>> and similar macros

This means Knot can warn you about uninitialized variables, unused variables, and variables that are read but never set — all in real time as you type.

Passage diagnostics

A dedicated panel inspects any passage's links, variables, macros, and complexity metrics. Real-time diagnostics cover:

Each diagnostic can be configured to error, warning, info, hint, or off in VS Code settings.

Story Map

An interactive graph visualization of your entire project. Nodes are passages, edges are links. The map is built on @xyflow/react with automatic layout via dagre.

• Click any node to jump to that passage in the editor.
• The map updates in real time as you edit — no manual refresh.
• Edge styling reflects link type (regular link, setter link, etc.).

The Story Map is primarily for visualization and navigation at this time. Deeper structural editing from the map — dragging passages to reorganize, creating links visually — is on the roadmap.

Incremental analysis

Knot doesn't re-parse your entire project on every keystroke. Only affected passages are re-parsed, and the graph is updated incrementally. This keeps large projects responsive even as they grow into hundreds of passages and thousands of links.

Integrated build pipeline

Knot's build pipeline is designed to "just work" with zero manual setup:

1. Tweego is auto-downloaded on first build into the extension's global storage. You never need to install it yourself.
2. Story formats are auto-downloaded based on your project's StoryData format and version. The format is cached per version in <globalStorage>/storyformats/<id>@<version>/.
3. The workspace is the source directory — put all your .twee, .js, .css, and asset files directly in the workspace. Story formats live separately in the managed folder, so there's no risk of format.js getting bundled as a passage.
4. The output filename is derived from StoryTitle — if your story is called "The Lost City", the build produces The_Lost_City.html. Falls back to index.html if no StoryTitle passage exists.
5. Build stats are logged — every build prints Passages: N | Words: N to the Knot Build output channel.

Watch mode

Toggle auto-rebuild on save. When Watch is on, every save of a .tw, .twee, .js, or .css file triggers a rebuild in the background. This is the recommended workflow for active development: edit, save, refresh the browser.

Supported story formats

Knot auto-detects the format from your StoryData passage. For non-SugarCube formats, the Language Status indicator shows a ◐ marker indicating the format is not yet fully supported. Bringing Harlowe, Chapbook, and Snowman to full parity is planned — see the roadmap for details.