Message Parser Engine

Relevant source files

The following files were used as context for generating this wiki page:

• app/lib/runtime/message-parser.ts
• app/lib/runtime/message-parser.spec.ts
• app/lib/hooks/useMessageParser.ts
• app/lib/stores/workbench.ts
• app/components/chat/Markdown.tsx
• app/components/chat/Chat.client.tsx

The Message Parser Engine is a critical component of the Bolt architecture responsible for processing streaming text input from AI models. It identifies specific custom XML-like tags—specifically artifacts and actions—within the raw text stream and transforms them into structured data and interactive UI elements. This engine allows the system to differentiate between conversational text and executable technical instructions such as file creation or shell commands.

By utilizing a stateful parsing approach, the engine can handle partial chunks of data as they arrive from the LLM, ensuring a responsive user experience. It integrates deeply with the application's state management to trigger side effects, such as opening the workbench or executing code in a WebContainer environment, as soon as valid tags are detected.

Sources: app/lib/runtime/message-parser.ts, app/lib/hooks/useMessageParser.ts

Core Architecture

The engine is primarily built around the StreamingMessageParser class, which maintains an internal map of message states to support concurrent or sequential parsing of multiple message IDs.

Stateful Parsing Logic

The parser tracks the "depth" of the current stream using a MessageState object. It monitors whether the cursor is currently inside a <boltArtifact> or a <boltAction> tag.

Key Data Structures

The parser relies on specific interfaces to communicate state changes to the rest of the application.

Interface	Purpose	Key Fields
ArtifactCallbackData	Represents a container for a set of related actions.	messageId, id, title
ActionCallbackData	Represents an individual task (shell command or file write).	artifactId, actionId, action
MessageState	Internal tracker for the streaming position and nesting level.	position, insideArtifact, insideAction

Sources: app/lib/runtime/message-parser.ts:16-55

Component Integration

The engine does not operate in isolation; it is connected to the UI and execution layers through React hooks and specialized stores.

useMessageParser Hook

The useMessageParser hook acts as the bridge between the streaming chat interface and the StreamingMessageParser instance. It manages the parsedMessages state, which contains the text that should be visible to the user (with artifact tags stripped out).

Sources: app/lib/hooks/useMessageParser.ts:39-65

Workbench and Store Interaction

When the parser detects tags, it triggers callbacks that interact with the workbenchStore.

1. Artifact Opening: Sets showWorkbench to true and adds the artifact to the global state.
2. Action Completion: When a closing action tag is parsed, the content is sent to the ActionRunner to be executed.

Tag Specifications

The engine recognizes two primary types of tags within the AI's response:

Artifact Tags (<boltArtifact>)

Artifacts serve as logical groupings for actions. They require a title and an id.

• Parsing: The parser extracts attributes using regex and replaces the XML tag in the output stream with a placeholder div with the class __boltArtifact__.
• Rendering: The Markdown component identifies this class and renders an interactive <Artifact /> component instead of raw HTML.

Sources: app/lib/runtime/message-parser.ts:145-170, app/components/chat/Markdown.tsx:28-40

Action Tags (<boltAction>)

Actions define specific operations.

• Types: Currently supports shell and file.
• Attributes: file actions require a filePath attribute.
• Content Handling: For file actions, the parser automatically appends a newline to the content to ensure proper file formatting.

Sources: app/lib/runtime/message-parser.ts:205-228

Parsing Robustness and Validation

The engine includes several mechanisms to ensure stability during malformed or incomplete streaming:

• Early Break: If a chunk ends in the middle of a tag definition (e.g., <boltArti), the parser stops and waits for the next chunk before attempting to process that segment.
• Attribute Extraction: A private #extractAttribute method uses case-insensitive regex to safely pull metadata from tags.
• Output Sanitization: Normal HTML tags like <strong> or <span> are passed through untouched, while Bolt-specific tags are extracted and handled via callbacks.

Sources: app/lib/runtime/message-parser.spec.ts:13-60, app/lib/runtime/message-parser.ts:231-234

Summary

The Message Parser Engine is the primary orchestrator for transforming raw AI text into a functional development environment. By abstracting the complexity of streaming XML parsing, it enables the Bolt platform to react instantly to AI-driven instructions, maintaining a synchronized state between the chat interface and the workbench.

Sources: app/lib/runtime/message-parser.ts, app/lib/hooks/useMessageParser.ts