Migration to 1.3

The 1.3 release keeps 1.2.x APIs compiling, but the recommended rendering path has changed. Review the deprecated parser switches and behavior changes before upgrading production chat screens. Removal of the deprecated APIs is planned for 2.0.0.

Requirements

gpt_markdown 1.3 requires Flutter 3.32 or newer and Dart 3.7 or newer. There is no new runtime dependency. Existing 1.2.x code should compile, but output, selection, semantics, and golden images can change.

Leave the legacy parser

plusparse is now the default parser. Delete incremental rather than setting it to true. Do not pass components or inlineComponents, even as empty lists: any of those arguments selects the legacy regex parser. That path does not use the incremental segment cache, span-level reveal, block components, or lazy sliver rendering.

parser.dart

// 1.3 uses plusparse by default.
// Remove the deprecated routing switches:
GptMarkdown(
  reply,
  // incremental: true,       // delete this
  // components: [...],       // use blockComponents instead
  // inlineComponents: [...], // use inlinePatterns or inlineDirectives
)

// These deprecated arguments still compile until 2.0.0, but they select
// the legacy regex parser and disable segment caching and lazy rendering.

Migrate custom blocks

Replace BlockMd and the old global component list with MarkdownBlockComponent in blockComponents. Use FencedBlockSyntax for fenced containers or implement MarkdownBlockSyntax for another block grammar. The syntax parser stays pure and the builder receives an immutable node, so the parsed document can be cached.

custom_block.dart

// Before: a regex component selected the legacy parser.
class CalloutMd extends BlockMd {
  @override
  String get expString => r':::callout\\n([\\s\\S]*?)\\n:::';
  // ...
}

GptMarkdown(text, components: [CalloutMd(), ...MarkdownComponent.globalComponents]);

// After: syntax is pure Dart and rendering is a separate builder.
GptMarkdown(
  text,
  blockComponents: [
    MarkdownBlockComponent(
      syntax: const FencedBlockSyntax(
        type: 'callout',
        opening: ':::callout',
      ),
      builder: (context, node, config) => CalloutBox(body: node.body),
    ),
  ],
)

Migrate custom inline syntax

Replace InlineMd with InlinePattern for text matched in the parsed document. Use InlineDirective when the parser must not inspect a delimited region, such as a server-provided JSON payload. Patterns match the whole document, so prefer lookarounds over ^ and $. Keep pattern and component instances stable across rebuilds.

inline_syntax.dart

// Before: InlineMd receives only the matched text.
class ShoutMd extends InlineMd {
  @override
  RegExp get exp => RegExp(r'!![A-Za-z]+!!');
  // ...
}

// After: InlinePattern keeps the match and resolved surrounding style.
GptMarkdown(
  text,
  inlinePatterns: [
    InlinePattern(
      pattern: RegExp(r'!![A-Za-z]+!!'),
      builder: (context, match, style) => TextSpan(
        text: match[0]!.replaceAll('!!', '').toUpperCase(),
        style: style.copyWith(fontWeight: FontWeight.bold),
      ),
    ),
  ],
)

// For a region the parser must not inspect, use InlineDirective instead.

Update inline builders

Prefer span-returning builders for inline content. inlineLinkBuilder receivesLinkBuildDetails, while inlineSourceTagBuilder receivesSourceTagBuildDetails. The deprecated widget builders remain available for compatibility, but WidgetSpan output cannot wrap across lines, is less selectable, and can disappear when nested inside a link label on iOS.

inline_builders.dart

// New span-returning builders keep inline content wrappable,
// selectable, and aligned with the surrounding baseline.
GptMarkdown(
  reply,
  inlineLinkBuilder: (details) => details.defaultSpan(),
  inlineSourceTagBuilder: (details) => details.defaultSpan(),
  inlineCodeBuilder: (context, code, style, codeStyle) => CodeTextSpan(
    text: code,
    style: style,
    codeStyle: codeStyle,
  ),
)

// linkBuilder, sourceTagBuilder, and highlightBuilder still compile,
// but return WidgetSpan-based output and are deprecated until 2.0.0.

Use SliverGptMarkdown for long documents

Ordinary GptMarkdown remains the compact, eager widget and is the only path with character reveal. For a long answer in its own scrollable viewport, move to SliverGptMarkdown. It eagerly segments the source but delays built-in AST, span, and widget construction until the viewport requests each segment. It composes with other slivers and has no independent scroll controller.

long_document.dart

// Before: the whole long document is built inside one scroll child.
SingleChildScrollView(
  child: GptMarkdown(document),
)

// After: offscreen segments wait for the viewport.
SelectionArea(
  child: CustomScrollView(
    slivers: [
      SliverGptMarkdown(
        document,
        config: const GptMarkdownConfig(
          style: TextStyle(fontSize: 16),
        ),
      ),
    ],
  ),
)

// SliverGptMarkdown shows source updates immediately. Character reveal stays
// on GptMarkdown. Selection covers mounted content, and a very large table,
// list, paragraph, or fence remains one segment.

Passing deprecated component lists forces a single SliverToBoxAdapter and disables viewport laziness. Keep modern component lists stable, and remember that selection includes only mounted content.

Complete deprecation migration reference

Nothing below is removed in 1.3.0; removal is planned for 2.0.0. This is the complete migration map for the deprecated public surface.

Widget arguments

Deprecated	Use instead	Migration note
incremental	Delete it	plusparse is already the default; false selects the legacy parser.
components	blockComponents	Move inline entries to inlinePatterns or inlineDirectives.
inlineComponents	inlinePatterns / inlineDirectives	Use directives for opaque delimited payloads.

Extension points and registration

Deprecated	Use instead	Migration note
InlineMd	InlinePattern / InlineDirective	Choose InlineDirective when Markdown parsing must be blocked.
BlockMd	MarkdownBlockComponent + MarkdownBlockSyntax	FencedBlockSyntax handles :::name containers.
MarkdownComponent.globalComponents	blockComponents	Do not spread the legacy registry.
MarkdownComponent.inlineComponents	inlinePatterns	Do not spread the legacy registry.
MdWidget	GptMarkdown	Direct use loses segment caching, span reveal, and lazy sliver rendering.

Builders, typedefs, and link widget

Deprecated	Use instead	Migration note
linkBuilder / LinkBuilder	inlineLinkBuilder / InlineLinkBuilder	Return an InlineSpan from LinkBuildDetails.
sourceTagBuilder / SourceTagBuilder	inlineSourceTagBuilder / InlineSourceTagBuilder	Use SourceTagBuildDetails.
highlightBuilder / HighlightBuilder	inlineCodeBuilder / InlineCodeBuilder	Use inlineCodeStyle when only appearance changes.
LinkButton	inlineLinkBuilder or LinkTextSpan	The package no longer builds LinkButton.
LinkSpanBuilder	No replacement	Only deprecated LinkButton used it.

Built-in regex components: no direct replacement

These were internals of the deprecated regex pipeline. Remove direct references; the modern parser handles each construct itself.

InlineDirectiveMd

Inline directives

IndentMd

Indented content

HTag

Headings

NewLines

Blank-line separation

HrLine

Horizontal rules

CheckBoxMd

Task-list items

RadioButtonMd

Radio options

BlockQuote

Block quotes

UnOrderedList

Unordered lists

OrderedList

Ordered lists

HighlightedText

Inline code

BoldMd

Bold

StrikeMd

Strikethrough

ItalicMd

Italic

LatexMathMultiLine

Display math

LatexMath

Inline math

SourceTag

Citation chips

ATagMd

Links

ImageMd

Images

TableMd

Tables

CodeBlockMd

Fenced code

UnderLineMd

Underline

Not deprecated: MarkdownComponent, MarkdownComponent.generate, MarkdownScope, and AutolinkMd.

Behavior changes to review

Links are text spans

Links now wrap mid-label, remain selectable and copyable, reveal per character, and align to the text baseline. Plain-text snapshots and link goldens change because toPlainText now includes link labels.

RTL and text scaling are corrected

Block alignment follows text direction. Paragraph and widget scaling is resolved once, fixing double-scaled nested lists, quotes, tables, checkboxes, and code blocks.

Malformed syntax stays visible

Malformed links and unclaimed custom matches render as literal source text instead of disappearing. Case-insensitive patterns and top-level alternation are also handled correctly.

Modern blocks can render lazily

GptMarkdown still renders the full document at mount. Use SliverGptMarkdown in a CustomScrollView when viewport-lazy block rendering is required.

Streaming has two independent axes

Character reveal and block entrance animation are separate. blockAnimation can use none, fadeIn, growIn, slideUp, or scaleIn; isStreaming must become false for completed, failed, and historical messages.

Accessibility settles after streaming

While a live reply is rebuilding, semantics intentionally collapse to one node. Structure reopens after a quiet period and reveal completion; selection is stable after the content settles.

Update tests and release checks

Update link goldens and assertions that expect LinkButton or a WidgetSpan. Test both parser paths when maintaining legacy compatibility, but make the modern path the release path. Pump streaming state changes rather than relying only onpumpAndSettle, and assert semantics and selection after the quiet period.

migration_test.dart

// Link labels are now LinkTextSpan, not LinkButton widgets.
expect(find.byType(LinkButton), findsNothing);

// RichText subclasses need a widget predicate.
final richText = find.byWidgetPredicate((widget) => widget is RichText);

// Test the streaming lifecycle explicitly.
await tester.pumpWidget(GptMarkdown(reply, isStreaming: true));
await tester.pump(const Duration(milliseconds: 16));
await tester.pumpWidget(GptMarkdown(reply, isStreaming: false));
// Then pump until the reveal settles before asserting selection or semantics.

Run package tests

Include docs snippets, example tests, parser tests, streaming tests, and Linux goldens.

Check app lifecycle

Set isStreaming: false on completion, errors, and loaded history messages.

Measure before launch

The published branch benchmarks are macOS profile measurements, not universal FPS or latency guarantees.

Performance evidence is qualified

The branch documentation reports lower median UI and raster work for several cold and streaming fixtures, plus lower first-viewport work with SliverGptMarkdown. Those results compare complete package revisions and were recorded on macOS. Mobile, web, RTL, scroll-through, selection, and very large individual blocks still need representative measurements before they become launch acceptance criteria.

Review inline syntax