fix(docs): [SITE-04] preserve structural chunks and clarify settings

scripts/documentation/README.md

@@ -67,6 +67,11 @@ timer is cleared and rejected HTTP bodies are cancelled.
 Code, inline code, HTML, links and structural Markdown tokens must survive.
 Fenced blocks and directives are restored from local originals, not model text.
 An invalid result is rejected instead of heuristically inserting code fences.
+Chunking keeps each table, list (including nested items), and blockquote together;
+joining translated chunks must not insert paragraph breaks inside those structures.
+A structural block larger than the requested chunk limit fails explicitly instead
+of being split or silently exceeding the limit. Split that source block into
+independent sections, or choose a larger limit when calling the chunking helper.
 Unusual Markdown or a chunk boundary may be rejected; inspect the retained
 draft and improve protection rather than weakening validation. This is not a
 Markdown sanitizer or proof that prose preserves meaning.

scripts/documentation/markdown.ts

@@ -124,9 +124,23 @@ export function splitTranslation(masked: string, limit = 4000): string[] {
     Number.isInteger(limit) && limit >= 128,
     'Invalid translation chunk limit',
   )
+  const lines = masked.split('\n')
+  const structuralEnds = new Map<number, number>()
+  for (const token of parser.parse(masked, {})) {
+    if (token.map && ['table_open', 'bullet_list_open', 'ordered_list_open', 'blockquote_open'].includes(token.type)) {
+      const [start, end] = token.map
+      structuralEnds.set(start, Math.max(end, structuralEnds.get(start) || 0))
+    }
+  }
   const chunks: string[] = []
   let current = ''
-  for (let line of masked.split('\n')) {
+  for (let index = 0; index < lines.length; index++) {
+    const end = structuralEnds.get(index)
+    let line = end ? lines.slice(index, end).join('\n') : lines[index]!
+    if (end) {
+      assert(line.length <= limit, 'Markdown structural block exceeds translation chunk limit; split the source block or increase the limit')
+      index = end - 1
+    }
     while (line.length > limit) {
       if (current.trim())
         chunks.push(current)