Add nestedListsWithoutBlankLine lever; make blocksInterruptParagraphs interrupt consistently in lists (#207)

* feat: add nestedListsWithoutBlankLine flag to BlockParser

* feat: granular list nesting via allowsImmediateNestedBlock gate

* feat: add withNestedListsWithoutBlankLine converter factory

* docs: clarify DjotConverter docblocks for nestedListsWithoutBlankLine

* test: composition and regression guards for granular list nesting

* docs: document nestedListsWithoutBlankLine and expanded blocksInterruptParagraphs

* docs: lead optional-modes docs with granular list-nesting levers

* docs: make nestedBlocksInLists deprecation coherent; track lone-marker todo

* fix: apply lone-marker lookahead to in-list interruption; define significantNewlines via granular levers

* docs: align parser-options/api with lone-marker lookahead and significantNewlines rewiring

Author: dereuromark

docs/guide/parser-options.md

@@ -16,7 +16,7 @@ $converter = new DjotConverter();
 $converter = new DjotConverter(
     xhtml: true,
     blocksInterruptParagraphs: true,
-    nestedBlocksInLists: true,
+    nestedListsWithoutBlankLine: true,
 );
 ```
 
@@ -36,7 +36,7 @@ use Djot\Renderer\HtmlRenderer;
 
 // Full control via create()
 $converter = DjotConverter::create(
-    new BlockParser(blocksInterruptParagraphs: true, nestedBlocksInLists: true),
+    new BlockParser(blocksInterruptParagraphs: true, nestedListsWithoutBlankLine: true),
     new HtmlRenderer(xhtml: true),
 );
 ```
@@ -105,7 +105,7 @@ Note: Use `\` at end of line for hard breaks (always renders as `<br>`) regardle
 
 ::: warning Deprecated
 `significantNewlines` is now a convenience shorthand equal to enabling both
-`blocksInterruptParagraphs` and `nestedBlocksInLists` together. It is
+`blocksInterruptParagraphs` and `nestedListsWithoutBlankLine` together. It is
 deprecated in favor of the two granular levers. Migrate as shown below.
 
 ```php
@@ -115,7 +115,7 @@ $converter = DjotConverter::withSignificantNewlines();
 // Equivalent (preferred):
 $converter = new DjotConverter(
     blocksInterruptParagraphs: true,
-    nestedBlocksInLists: true,
+    nestedListsWithoutBlankLine: true,
 );
 ```
 :::
@@ -282,7 +282,7 @@ use Djot\Renderer\SoftBreakMode;
 // Significant newlines with safe mode for user-generated content
 $converter = new DjotConverter(
     safeMode: new SafeMode(),
-    significantNewlines: true, // deprecated: prefer blocksInterruptParagraphs + nestedBlocksInLists
+    significantNewlines: true, // deprecated: prefer blocksInterruptParagraphs + nestedListsWithoutBlankLine
     softBreakMode: SoftBreakMode::Break, // Optional: visible line breaks
 );
 ```
@@ -361,13 +361,13 @@ Output:
 | Nested blocks in list items without a blank line               | No      | **Yes**               | Yes                   |
 | Block elements interrupt top-level paragraphs                  | No      | No                    | Yes                   |
 
-Note: `significantNewlines` is deprecated; it enables both `blocksInterruptParagraphs` and `nestedBlocksInLists`. Prefer setting the two granular levers directly.
+Note: `significantNewlines` is deprecated; it enables both `blocksInterruptParagraphs` and `nestedListsWithoutBlankLine`. Prefer setting the two granular levers directly. (`nestedBlocksInLists` is a separate, also-deprecated broad lever - it is no longer what `significantNewlines` sets.)
 
 ## Block Interrupts Paragraphs Mode
 
-`blocksInterruptParagraphs` is the complementary counterpart to [Nested Blocks in Lists](#nested-blocks-in-lists-mode) mode. It allows top-level block elements — lists, blockquotes, headings, tables, thematic breaks, and code/div/comment fences — to interrupt a paragraph without a preceding blank line. It does **not** enable nesting inside list items (that is `nestedBlocksInLists`).
+`blocksInterruptParagraphs` allows top-level block elements - lists, blockquotes, headings, tables, thematic breaks, and code/div/comment fences - to interrupt a paragraph without a preceding blank line. It **also** interrupts a list item's lead paragraph, so an indented non-list block (blockquote, heading, fenced code, or thematic break) nests inside the open item without a blank line. It does **not** nest a sublist inside a list item - that requires [Nested Lists Without Blank Line](#nested-lists-without-blank-line-mode) mode.
 
-Use it when you want markdown-like top-level interruption but otherwise spec-compliant djot: indented content inside a list item still requires a blank line.
+Use it when you want markdown-like top-level interruption and non-list nesting in list items, but otherwise spec-compliant djot: a sublist under a list item still requires a blank line.
 
 ### Enabling Block Interrupts Paragraphs Mode
 
@@ -408,19 +408,41 @@ two
 </ul>
 ```
 
-But indented content inside a list item does **not** nest (this is what differs from significant newlines mode):
+A non-list block also nests inside a list item without a blank line. For example, a blockquote under the item:
 
 ```php
 $converter = DjotConverter::withBlocksInterruptParagraphs();
-$result = $converter->convert("- a\n  - b");
+$result = $converter->convert("- Item\n  > a\n  > b");
 ```
 
 Output:
 ```html
 <ul>
 <li>
-a
-- b
+Item
+<blockquote>
+<p>a
+b</p>
+</blockquote>
+</li>
+</ul>
+```
+
+In-list interruption uses the **same** lone-marker lookahead as the top-level path: an ambiguous single-line marker (`>` comparison, `|`, a lone bullet) stays literal, while unambiguous openers (`#`, fenced code, `:::`, `---`) and real multi-line blocks nest. So `- Item\n  > quote` (a single `>` line) keeps `> quote` as literal text, exactly as `Foo\n> quote` does at the top level.
+
+A sublist does **not** nest with this flag alone (that requires [Nested Lists Without Blank Line](#nested-lists-without-blank-line-mode) mode):
+
+```php
+$converter = DjotConverter::withBlocksInterruptParagraphs();
+$result = $converter->convert("- Item\n  - sub");
+```
+
+Output:
+```html
+<ul>
+<li>
+Item
+- sub
 </li>
 </ul>
 ```
@@ -430,6 +452,83 @@ a
 | Behavior                                                       | Default | `blocksInterruptParagraphs` | `significantNewlines` |
 |----------------------------------------------------------------|---------|-----------------------------|-----------------------|
 | Block elements interrupt top-level paragraphs                  | No      | **Yes**                     | Yes                   |
-| Nested blocks in list items without a blank line               | No      | No                          | Yes                   |
+| Non-list block nests in list item without a blank line         | No      | **Yes**                     | Yes                   |
+| Sublist nests in list item without a blank line                | No      | No                          | Yes                   |
+
+The two granular levers are independent. `blocksInterruptParagraphs` alone does not nest sublists; `nestedListsWithoutBlankLine` alone does not interrupt top-level paragraphs or nest non-list blocks. `significantNewlines` enables both simultaneously.
+
+## Nested Lists Without Blank Line Mode
+
+`nestedListsWithoutBlankLine` lets a sublist nest inside a list item without a blank line, while leaving everything else at the spec default. It nests **only** sublists: a non-list block (blockquote, heading, thematic break) under the item stays literal, and top-level paragraphs are **not** interrupted.
+
+Use it when you want markdown-like nested lists but otherwise spec-compliant djot: top-level paragraphs still require a blank line before any block, and only sublists nest in list items.
+
+### Enabling Nested Lists Without Blank Line Mode
+
+```php
+use Djot\DjotConverter;
+use Djot\Parser\BlockParser;
+
+// Method 1: Factory method
+$converter = DjotConverter::withNestedListsWithoutBlankLine();
+
+// Method 2: Constructor parameter
+$converter = new DjotConverter(nestedListsWithoutBlankLine: true);
+
+// Method 3: Directly on the parser
+$parser = new BlockParser(nestedListsWithoutBlankLine: true);
+$parser->setNestedListsWithoutBlankLine(true);
+```
+
+### Behavior
+
+A sublist nests inside the open list item, even without a blank line:
+
+```php
+$converter = DjotConverter::withNestedListsWithoutBlankLine();
+$result = $converter->convert("- Item\n  - Nested one\n  - Nested two");
+```
+
+Output:
+```html
+<ul>
+<li>
+Item
+<ul>
+<li>
+Nested one
+</li>
+<li>
+Nested two
+</li>
+</ul>
+</li>
+</ul>
+```
+
+But a non-list block (such as a blockquote) under the item stays literal - it does **not** nest with this flag (that is `blocksInterruptParagraphs`):
+
+```php
+$converter = DjotConverter::withNestedListsWithoutBlankLine();
+$result = $converter->convert("- Item\n  > quote");
+```
+
+Output:
+```html
+<ul>
+<li>
+Item
+&gt; quote
+</li>
+</ul>
+```
+
+### nestedListsWithoutBlankLine vs blocksInterruptParagraphs
+
+| Behavior                                               | Default | `nestedListsWithoutBlankLine` | `blocksInterruptParagraphs` | both |
+|--------------------------------------------------------|---------|-------------------------------|-----------------------------|------|
+| Sublist nests in list item without a blank line        | No      | **Yes**                       | No                          | Yes  |
+| Non-list block nests in list item without a blank line | No      | No                            | **Yes**                     | Yes  |
+| Block elements interrupt top-level paragraphs          | No      | No                            | Yes                         | Yes  |
 
-The two granular levers are independent. `blocksInterruptParagraphs` alone does not nest list items; `nestedBlocksInLists` alone does not interrupt top-level paragraphs. `significantNewlines` enables both simultaneously.
+Note: `blocksInterruptParagraphs` + `nestedListsWithoutBlankLine` together equal the deprecated `significantNewlines`; the deprecated `nestedBlocksInLists` enables the two in-list rows (sublist + non-list block) without top-level interruption.

docs/guide/syntax.md

@@ -533,15 +533,15 @@ A list is loose if *any* item is separated by a blank line. One blank line makes
   - Nested item B
 ```
 
-With `significantNewlines` mode enabled, nested lists can appear immediately without a blank line:
+With `nestedListsWithoutBlankLine` mode enabled, nested lists can appear immediately without a blank line:
 
 ```djot
 - Parent item
   - Nested item A
   - Nested item B
 ```
 
-See the [API Reference](/reference/api#significant-newlines-mode) for more on `significantNewlines` mode.
+See the [Parser Options guide](/guide/parser-options#nested-lists-without-blank-line-mode) for more on `nestedListsWithoutBlankLine` mode.
 
 ### Definition Lists
 

docs/reference/api.md

@@ -27,6 +27,7 @@ public function __construct(
     ?RendererInterface $renderer = null,
     bool $nestedBlocksInLists = false,
     bool $blocksInterruptParagraphs = false,
+    bool $nestedListsWithoutBlankLine = false,
 )
 ```
 
@@ -35,19 +36,20 @@ public function __construct(
 - `$strict`: When `true`, throws `ParseException` on parse errors (see [Error Handling](#error-handling)).
 - `$safeMode`: When `true` or a `SafeMode` instance, enables XSS protection (see [Safe Mode](#safe-mode)).
 - `$profile`: A `Profile` instance for feature restriction (see [Profiles](/guide/profiles)).
-- `$significantNewlines`: **Deprecated.** Convenience shorthand for `blocksInterruptParagraphs: true, nestedBlocksInLists: true`. Prefer the two granular levers. See [Significant Newlines Mode](#significant-newlines-mode).
+- `$significantNewlines`: **Deprecated.** Convenience shorthand for `blocksInterruptParagraphs: true, nestedListsWithoutBlankLine: true`. Prefer the two granular levers. See [Significant Newlines Mode](#significant-newlines-mode).
 - `$softBreakMode`: Override how soft breaks are rendered. When `null`, uses the renderer's default (newline for HTML).
 - `$roundTripMode`: When `true`, adds round-trip metadata for Djot→HTML→Djot workflows (HTML renderer only).
-- `$parser`: Optional pre-configured parser. When provided, inline parser constructor flags such as `warnings`, `strict`, `significantNewlines` (deprecated), `nestedBlocksInLists`, and `blocksInterruptParagraphs` are ignored.
+- `$parser`: Optional pre-configured parser. When provided, inline parser constructor flags such as `warnings`, `strict`, `significantNewlines` (deprecated), `nestedBlocksInLists`, `blocksInterruptParagraphs`, and `nestedListsWithoutBlankLine` are ignored.
 - `$renderer`: Optional pre-configured renderer. When provided, inline renderer constructor flags such as `xhtml`, `safeMode`, `softBreakMode`, and `roundTripMode` are ignored.
-- `$nestedBlocksInLists`: When `true`, indentation alone introduces nested blocks inside list items without a blank line, while top-level paragraph interruption stays spec-compliant (see [Nested Blocks in Lists Mode](/guide/parser-options#nested-blocks-in-lists-mode)). Implied by `$significantNewlines`.
-- `$blocksInterruptParagraphs`: When `true`, top-level block elements (lists, blockquotes, headings, tables, thematic breaks, and code/div/comment fences) can interrupt a paragraph without a preceding blank line, while list-item nesting stays spec-compliant (see [Block Interrupts Paragraphs Mode](/guide/parser-options#block-interrupts-paragraphs-mode)). Implied by `$significantNewlines`.
+- `$nestedBlocksInLists`: **Deprecated.** When `true`, indentation alone introduces nested blocks of **any** type inside list items without a blank line (broad, eager - no lone-marker lookahead), while top-level paragraph interruption stays spec-compliant (see [Nested Blocks in Lists Mode](/guide/parser-options#nested-blocks-in-lists-mode)). Prefer `$blocksInterruptParagraphs` + `$nestedListsWithoutBlankLine`. No longer implied by `$significantNewlines`.
+- `$blocksInterruptParagraphs`: When `true`, top-level block elements (lists, blockquotes, headings, tables, thematic breaks, and code/div/comment fences) can interrupt a paragraph without a preceding blank line. It **also** interrupts a list item's lead paragraph, so an indented non-list block nests inside the item without a blank line, using the **same** lone-marker lookahead as the top level: unambiguous openers (`#`, fenced code, `:::`, `---`) and real multi-line blocks nest, while a single ambiguous marker line (`>`, `|`) stays literal. It does not nest sublists (see [Block Interrupts Paragraphs Mode](/guide/parser-options#block-interrupts-paragraphs-mode)). Implied by `$significantNewlines`.
+- `$nestedListsWithoutBlankLine`: When `true`, a sublist nests inside a list item without a blank line. Only sublists nest; non-list blocks under the item stay literal and top-level paragraph interruption is unaffected (see [Nested Lists Without Blank Line Mode](/guide/parser-options#nested-lists-without-blank-line-mode)). Implied by `$significantNewlines`.
 
 ### Factory Methods
 
 #### withSignificantNewlines()
 
-> **Deprecated.** Prefer using `new DjotConverter(blocksInterruptParagraphs: true, nestedBlocksInLists: true)` or the two dedicated factory methods. See [Significant Newlines Mode](/guide/parser-options#significant-newlines-mode).
+> **Deprecated.** Prefer using `new DjotConverter(blocksInterruptParagraphs: true, nestedListsWithoutBlankLine: true)` or the two dedicated factory methods. See [Significant Newlines Mode](/guide/parser-options#significant-newlines-mode).
 
 ```php
 public static function withSignificantNewlines(
@@ -61,7 +63,7 @@ public static function withSignificantNewlines(
 ): self
 ```
 
-Creates a converter with significant newlines mode enabled (equivalent to `blocksInterruptParagraphs: true` + `nestedBlocksInLists: true`). See [Significant Newlines Mode](/guide/parser-options#significant-newlines-mode).
+Creates a converter with significant newlines mode enabled (equivalent to `blocksInterruptParagraphs: true` + `nestedListsWithoutBlankLine: true`). See [Significant Newlines Mode](/guide/parser-options#significant-newlines-mode).
 
 #### withNestedBlocksInLists()
 
@@ -93,7 +95,23 @@ public static function withBlocksInterruptParagraphs(
 ): self
 ```
 
-Creates a converter that allows top-level block elements (lists, blockquotes, headings, tables, thematic breaks, and code/div/comment fences) to interrupt a paragraph without a preceding blank line, while list-item nesting stays spec-compliant. See [Block Interrupts Paragraphs Mode](/guide/parser-options#block-interrupts-paragraphs-mode).
+Creates a converter that allows top-level block elements (lists, blockquotes, headings, tables, thematic breaks, and code/div/comment fences) to interrupt a paragraph without a preceding blank line, and nests indented non-list blocks inside list items without a blank line. Sublist nesting stays spec-compliant. See [Block Interrupts Paragraphs Mode](/guide/parser-options#block-interrupts-paragraphs-mode).
+
+#### withNestedListsWithoutBlankLine()
+
+```php
+public static function withNestedListsWithoutBlankLine(
+    bool $xhtml = false,
+    bool $warnings = false,
+    bool $strict = false,
+    bool|SafeMode|null $safeMode = null,
+    ?Profile $profile = null,
+    ?SoftBreakMode $softBreakMode = null,
+    bool $roundTripMode = false,
+): self
+```
+
+Creates a converter that nests a sublist inside a list item without requiring a blank line. Only sublists nest; non-list blocks under the item stay literal and top-level paragraph interruption stays at the spec default. See [Nested Lists Without Blank Line Mode](/guide/parser-options#nested-lists-without-blank-line-mode).
 
 ### Methods
 
@@ -540,6 +558,7 @@ $parser = new BlockParser(
     significantNewlines: false,
     nestedBlocksInLists: false,
     blocksInterruptParagraphs: false,
+    nestedListsWithoutBlankLine: false,
 );
 $document = $parser->parse($djotString);
 
@@ -556,10 +575,16 @@ $isEnabled = $parser->getSignificantNewlines();
 $parser->setNestedBlocksInLists(true);
 $isEnabled = $parser->getNestedBlocksInLists();
 
-// Enable/disable top-level paragraph interruption only
+// Enable/disable top-level paragraph interruption and non-list
+// block nesting in list items
 // (significant newlines mode enables this implicitly)
 $parser->setBlocksInterruptParagraphs(true);
 $isEnabled = $parser->getBlocksInterruptParagraphs();
+
+// Enable/disable sublist nesting in list items only
+// (significant newlines mode enables this implicitly)
+$parser->setNestedListsWithoutBlankLine(true);
+$isEnabled = $parser->getNestedListsWithoutBlankLine();
 ```
 
 #### Custom Block Patterns
@@ -913,7 +938,7 @@ $node->addClass(string $class): void
 ## Significant Newlines Mode
 
 > **Deprecated.** `significantNewlines` is a convenience shorthand for
-> `blocksInterruptParagraphs: true` + `nestedBlocksInLists: true`.
+> `blocksInterruptParagraphs: true` + `nestedListsWithoutBlankLine: true`.
 > Prefer the two granular levers or their factory methods.
 
 An optional parsing mode for chat messages, comments, and quick notes where markdown-like behavior is more intuitive.
@@ -930,7 +955,7 @@ $converter = new DjotConverter(significantNewlines: true);
 // Preferred: use the two granular levers
 $converter = new DjotConverter(
     blocksInterruptParagraphs: true,
-    nestedBlocksInLists: true,
+    nestedListsWithoutBlankLine: true,
 );
 
 // Via parser directly (deprecated)