mdld-parse 0.9.1 → 0.9.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.md +34 -1
  2. package/dist/.nojekyll +0 -0
  3. package/dist/CNAME +1 -0
  4. package/dist/README.md +425 -0
  5. package/dist/docs/API.md +397 -0
  6. package/dist/docs/Architecture.md +190 -0
  7. package/dist/docs/Guide.md +322 -0
  8. package/dist/docs/LLM-MDLD-Inducer.md +550 -0
  9. package/dist/docs/Parser.md +654 -0
  10. package/dist/docs/Performance.md +238 -0
  11. package/dist/docs/Spec-render.md +1439 -0
  12. package/dist/docs/Subject.md +180 -0
  13. package/dist/docs/Syntax.md +463 -0
  14. package/dist/docs/TodoList.md +215 -0
  15. package/dist/docs/Use-Cases.md +354 -0
  16. package/dist/docs/index.html +108 -0
  17. package/dist/docs/index.md +56 -0
  18. package/dist/docs/origin.md +459 -0
  19. package/dist/docs/polarity.md +586 -0
  20. package/dist/docs/primary-subject.md +199 -0
  21. package/dist/docs/statements.md +226 -0
  22. package/dist/docs/tokenization-performance-report.md +164 -0
  23. package/dist/examples/Cookbook.md +32 -0
  24. package/dist/examples/Status-SHACL.md +33 -0
  25. package/dist/examples/demo/index.md +35 -0
  26. package/dist/examples/demo/journal.md +18 -0
  27. package/dist/examples/demo/minimal.md +11 -0
  28. package/dist/examples/demo/project.md +15 -0
  29. package/dist/examples/demo/recipe.md +31 -0
  30. package/dist/examples/demo/research.md +46 -0
  31. package/dist/examples/demo/space-mission.md +48 -0
  32. package/dist/examples/dogfood.md +288 -0
  33. package/dist/examples/few-shot.md +309 -0
  34. package/dist/examples/graph/rdf-graph.html +473 -0
  35. package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
  36. package/dist/examples/index.md +45 -0
  37. package/dist/examples/llm-time-workflow.md +173 -0
  38. package/dist/examples/prov-o.md +2367 -0
  39. package/dist/examples/rdf.md +827 -0
  40. package/dist/examples/shacl.md +3399 -0
  41. package/dist/examples/statements.md +43 -0
  42. package/dist/examples/workflow.md +150 -0
  43. package/dist/index.html +2827 -0
  44. package/dist/index.js +1548 -0
  45. package/dist/logo.svg +7 -0
  46. package/dist/spec/Spec-compact.md +363 -0
  47. package/dist/spec/Spec-ultra.md +221 -0
  48. package/dist/spec/Spec.md +1068 -0
  49. package/dist/spec/index.md +46 -0
  50. package/package.json +13 -8
  51. package/src/constants.js +0 -31
  52. package/src/generate.js +0 -245
  53. package/src/index.js +0 -13
  54. package/src/locate.js +0 -23
  55. package/src/merge.js +0 -157
  56. package/src/parse.js +0 -765
  57. package/src/render.js +0 -576
  58. package/src/shared.js +0 -577
  59. package/src/utils.js +0 -430
@@ -0,0 +1,1439 @@
1
+ # MD-LD Render Specification
2
+
3
+ **HTML+RDFa Rendering for MD-LD Documents**
4
+
5
+ A deterministic, streaming-friendly renderer that transforms valid MD-LD text into semantically meaningful HTML+RDFa markup ready for browser rendering while maintaining complete provenance and supporting interactive agent experiences.
6
+
7
+ ---
8
+
9
+ ## 1. Design Philosophy
10
+
11
+ ### Core Principles
12
+
13
+ The MD-LD Render follows the same engineering principles as the parser:
14
+
15
+ - **Streaming-first** — Single-pass rendering, O(n) complexity
16
+ - **Zero dependencies** — Pure JavaScript implementation
17
+ - **Semantic fidelity** — Preserves all RDF semantics in HTML+RDFa
18
+ - **Agent empowerment** — Enables interactive knowledge graph authoring
19
+ - **Provenance preservation** — Maintains complete source tracking
20
+ - **Round-trip safety** — HTML ↔ MD-LD ↔ RDF transformation chain
21
+
22
+ ### Architecture Alignment
23
+
24
+ The render mirrors the parser's architecture:
25
+
26
+ 1. **Parser Output** → Render State (single-pass transformation)
27
+ 2. **Token Processing** → Block Rendering (deterministic mapping)
28
+ 3. **Semantic Blocks** → RDFa Attributes (semantic preservation)
29
+ 4. **Origin Tracking** → Interactive Features (agent enablement)
30
+
31
+ ---
32
+
33
+ ## 2. Rendering Pipeline
34
+
35
+ ### Phase 1: Parse Integration
36
+
37
+ ```javascript
38
+ // Reuse parser output for consistency
39
+ const parsed = parse({ text: mdld, context: options.context || {} });
40
+ ```
41
+
42
+ **Input:** Valid MD-LD text
43
+ **Output:** Parser result with quads, origin, context, statements
44
+
45
+ **Key Integration Points:**
46
+ - Use parser's resolved context for IRI expansion
47
+ - Leverage origin tracking for interactive features
48
+ - Preserve quad structure for semantic validation
49
+ - Maintain statement extraction for elevated patterns
50
+
51
+ ### Phase 2: Render State Construction
52
+
53
+ ```javascript
54
+ const state = {
55
+ ctx: parsed.context, // Resolved prefix context
56
+ df: DataFactory, // RDF/JS DataFactory
57
+ baseIRI: options.baseIRI, // Base IRI for resolution
58
+ sourceText: mdld, // Original text for extraction
59
+ output: [], // Accumulated HTML output
60
+ currentSubject: null, // Subject context tracking
61
+ documentSubject: null, // Document-level subject
62
+ blockStack: [], // Nested block context
63
+ carrierStack: [] // Inline carrier context
64
+ };
65
+ ```
66
+
67
+ **State Characteristics:**
68
+ - **Minimal footprint** — Only essential rendering state
69
+ - **Context preservation** — Parser context fully available
70
+ - **Streaming compatible** — Can process incrementally
71
+ - **Interactive ready** — State supports agent interactions
72
+
73
+ ### Phase 3: Block Processing Pipeline
74
+
75
+ ```javascript
76
+ // Sort blocks by source position (deterministic)
77
+ const sortedBlocks = Array.from(parsed.origin.blocks.values())
78
+ .sort((a, b) => a.range.start - b.range.start);
79
+
80
+ // Process blocks by type
81
+ sortedBlocks.forEach(block => renderBlock(block, state));
82
+ ```
83
+
84
+ **Processing Strategy:**
85
+ - **Positional ordering** — Maintains document structure
86
+ - **Type-specific rendering** — Optimized for each carrier type
87
+ - **Context propagation** — Maintains semantic relationships
88
+ - **RDFa enrichment** — Adds semantic markup to HTML
89
+
90
+ ### Phase 4: RDFa Context Wrapping
91
+
92
+ ```javascript
93
+ const wrapped = wrapWithRDFaContext(html, state.ctx);
94
+ ```
95
+
96
+ **Final Output Structure:**
97
+ ```html
98
+ <div prefix="schema: http://schema.org/ ex: http://example.org/"
99
+ vocab="http://www.w3.org/2000/01/rdf-schema#">
100
+ <!-- Rendered content with RDFa attributes -->
101
+ </div>
102
+ ```
103
+
104
+ ---
105
+
106
+ ## 3. Block Rendering System
107
+
108
+ ### 3.1 Carrier Types and Rendering Strategy
109
+
110
+ #### Block-Level Carriers
111
+
112
+ | Carrier Type | Markdown Syntax | HTML Element | RDFa Strategy | Example |
113
+ |--------------|----------------|--------------|---------------|---------|
114
+ | **heading** | `# Heading {...}` | `<h1>`-`<h6>` | `about`, `typeof`, `property` | `# Title {=ex:title .schema:Thing label}` |
115
+ | **paragraph** | `Text {...}` | `<p>` | `about`, `property`, `rel` | `Content {ex:description}` |
116
+ | **list** | `- Item {...}` | `<ul>`/`<li>` | Hierarchical RDFa | `- Item {=ex:item .schema:ListItem name}` |
117
+ | **blockquote** | `> Quote {...}` | `<blockquote>` | `about`, `property` | `> "Quote" {ex:quote}` |
118
+ | **code** | ````code {...}```` | `<pre><code>` | `about`, `typeof` | ````js {=ex:code .ex:SoftwareSourceCode}```` |
119
+ | **standalone** | `{=subject}` | `<div>` | `about`, `typeof` | `{=ex:subject .ex:Type}` |
120
+
121
+ #### Inline Carriers
122
+
123
+ | Carrier Type | Markdown Syntax | HTML Element | RDFa Strategy | Subject Resolution | Example |
124
+ |--------------|----------------|--------------|---------------|------------------|---------|
125
+ | **emphasis** | `*text* {...}` | `<em>` | `property`, `rel` | Current subject | `*important* {ex:emphasis}` |
126
+ | **strong** | `**text** {...}` | `<strong>` | `property`, `rel` | Current subject | `**warning** {ex:alert}` |
127
+ | **code span** | `` `code` {...} `` | `<code>` | `property`, `rel` | Current subject | `` `console.log()` {ex:code}`` |
128
+ | **link** | `[text](url) {...}` | `<a href="url">` | `about`, `property`, `rel` | URL becomes subject | `[NASA](https://nasa.gov) {.schema:Organization label}` |
129
+ | **image** | `![alt](url) {...}` | `<img src="url" alt="alt">` | `about`, `property`, `rel` | URL becomes subject | `![Logo](logo.png) {ex:logo}` |
130
+ | **angle link** | `<url> {...}` | `<a href="url">` | `about`, `property`, `rel` | URL becomes subject | `<https://example.com> {ex:reference}` |
131
+
132
+ #### Link Carrier Special Handling
133
+
134
+ **Markdown Link Syntax `[text](url)`:**
135
+
136
+ 1. **Subject Resolution Priority:**
137
+ - Explicit subject (`{=iri}`) > URL > Current subject
138
+ - When explicit subject present: URL becomes object resource
139
+ - When no explicit subject: URL becomes subject
140
+
141
+ 2. **RDFa Attribute Generation:**
142
+ ```javascript
143
+ // Case 1: Explicit subject with URL
144
+ [Link](https://example.com) {=ex:subject .Type label}
145
+ // Output: <a href="https://example.com" about="ex:subject" typeof="ex:Type" property="rdfs:label">Link</a>
146
+
147
+ // Case 2: URL as subject (no explicit subject)
148
+ [Link](https://example.com) {.Type label}
149
+ // Output: <a href="https://example.com" about="https://example.com" typeof="ex:Type" property="rdfs:label">Link</a>
150
+
151
+ // Case 3: Object property with explicit subject
152
+ [Link](https://example.com) {=ex:subject ?references}
153
+ // Output: <a href="https://example.com" about="ex:subject" rel="ex:references">Link</a>
154
+ ```
155
+
156
+ 3. **Content Extraction:**
157
+ - Link text becomes literal value for `property` predicates
158
+ - URL becomes `href` attribute and potential `about` subject
159
+ - Alt text used for image carriers
160
+
161
+ 4. **RDFa Attribute Mapping:**
162
+ | MD-LD Construct | Subject | RDFa Output |
163
+ |-----------------|---------|-------------|
164
+ | `[text](url) {property}` | Current subject | `property="ex:property"` on `<a>` |
165
+ | `[text](url) {?object}` | Current subject | `rel="ex:object"` on `<a>` |
166
+ | `[text](url) {=subject}` | URL | `about="url"` on `<a>` |
167
+ | `[text](url) {=subject .Type}` | URL | `about="url" typeof="ex:Type"` on `<a>` |
168
+
169
+ ### 3.2 RDFa Attribute Generation
170
+
171
+ #### Subject Resolution
172
+
173
+ ```javascript
174
+ function buildRDFaAttrsFromBlock(block, ctx) {
175
+ const attrs = [];
176
+
177
+ // Subject (about)
178
+ if (block.subject && isValidSubject(block.subject)) {
179
+ const expanded = expandIRI(block.subject, ctx);
180
+ const shortened = shortenIRI(expanded, ctx);
181
+ attrs.push(`about="${escapeHtml(shortened)}"`);
182
+ }
183
+
184
+ // Types (typeof)
185
+ if (block.types?.length > 0) {
186
+ const types = block.types.map(t =>
187
+ shortenIRI(expandIRI(typeof t === 'string' ? t : t.iri, ctx), ctx)
188
+ ).join(' ');
189
+ attrs.push(`typeof="${escapeHtml(types)}"`);
190
+ }
191
+
192
+ // Predicates (property/rel/rev)
193
+ if (block.predicates?.length > 0) {
194
+ const { literalProps, objectProps, reverseProps } = categorizePredicates(block.predicates);
195
+
196
+ if (literalProps.length > 0) attrs.push(`property="${literalProps.join(' ')}"`);
197
+ if (objectProps.length > 0) attrs.push(`rel="${objectProps.join(' ')}"`);
198
+ if (reverseProps.length > 0) attrs.push(`rev="${reverseProps.join(' ')}"`);
199
+ }
200
+
201
+ return attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
202
+ }
203
+ ```
204
+
205
+ #### Predicate Categorization
206
+
207
+ | Predicate Form | RDFa Attribute | Direction | Example |
208
+ |----------------|----------------|-----------|---------|
209
+ | `p` (literal) | `property` | Subject → Literal | `property="rdfs:label"` |
210
+ | `?p` (object) | `rel` | Subject → Object | `rel="schema:knows"` |
211
+ | `!p` (reverse) | `rev` | Object → Subject | `rev="schema:member"` |
212
+
213
+ ### 3.3 Content Extraction Strategy
214
+
215
+ #### Source Text Preservation
216
+
217
+ ```javascript
218
+ function renderBlockContent(block, state) {
219
+ if (block.range && state.sourceText) {
220
+ let text = state.sourceText.substring(block.range.start, block.range.end);
221
+
222
+ // Remove MD-LD annotations, preserve content
223
+ if (block.attrsRange) {
224
+ const beforeAttrs = text.substring(0, block.attrsRange.start - block.range.start);
225
+ const afterAttrs = text.substring(block.attrsRange.end - block.range.start);
226
+ text = beforeAttrs + afterAttrs;
227
+ }
228
+
229
+ // Type-specific content cleaning
230
+ text = cleanContentByType(text, block.carrierType);
231
+
232
+ state.output.push(escapeHtml(text.trim()));
233
+ }
234
+ }
235
+ ```
236
+
237
+ #### Content Cleaning Rules
238
+
239
+ | Carrier Type | Cleaning Strategy | Input → Output |
240
+ |--------------|------------------|----------------|
241
+ | **heading** | Remove leading `#` markers and trim | `# Title {props}` → `Title` |
242
+ | **paragraph** | Remove annotations only, preserve text | `Text {prop}` → `Text` |
243
+ | **list** | Remove list markers (`-`, `*`, `+`, `1.`) | `- Item {prop}` → `Item` |
244
+ | **blockquote** | Remove leading `>` marker | `> Quote {prop}` → `Quote` |
245
+ | **code** | Preserve code content exactly | ```code {prop}```` → `code` |
246
+ | **emphasis** | Remove emphasis markers | `*text* {prop}` → `text` |
247
+ | **strong** | Remove strong markers | `**text** {prop}` → `text` |
248
+ | **code span** | Remove backticks | `` `code` {prop}` `` → `code` |
249
+ | **link** | Preserve link text, remove URL from content | `[Text](url) {prop}` → `Text` |
250
+ | **image** | Use alt text, remove URL from content | `![Alt](url) {prop}` → `Alt` |
251
+ | **angle link** | Use URL as both href and content | `<url> {prop}` → `url` |
252
+
253
+ #### Comprehensive Carrier Reference
254
+
255
+ **Block-Level Carriers (structural elements):**
256
+
257
+ 1. **Headings** - `#` through `######` prefix
258
+ - Syntax: `# Heading Text {=ex:subject .Type property}`
259
+ - HTML: `<h1>` to `<h6>`
260
+ - Content: Text after `#` markers
261
+
262
+ 2. **Paragraphs** - Text blocks with annotations
263
+ - Syntax: `Paragraph content {ex:property}`
264
+ - HTML: `<p>`
265
+ - Content: Full text minus annotations
266
+
267
+ 3. **List Items** - Markdown list markers
268
+ - Syntax: `- Item {=ex:item .Type name}`
269
+ - HTML: `<ul><li>`
270
+ - Content: Text after list marker
271
+
272
+ 4. **Blockquotes** - Lines starting with `>`
273
+ - Syntax: `> Quote text {ex:quote}`
274
+ - HTML: `<blockquote>`
275
+ - Content: Text after `>` marker
276
+
277
+ 5. **Code Blocks** - Fenced code blocks
278
+ - Syntax: ````language {=ex:code .Type}````
279
+ - HTML: `<pre><code class="language-X">`
280
+ - Content: Entire code block content
281
+
282
+ 6. **Standalone Subjects** - Subject declarations
283
+ - Syntax: `{=ex:subject .Type}` (on separate line)
284
+ - HTML: `<div>`
285
+ - Content: Empty (subject declaration only)
286
+
287
+ **Inline Carriers (within blocks):**
288
+
289
+ 1. **Emphasis** - `*text*` or `_text_`
290
+ - Syntax: `*emphasized* {ex:property}`
291
+ - HTML: `<em>`
292
+ - Content: Text within emphasis markers
293
+
294
+ 2. **Strong** - `**text**` or `__text__`
295
+ - Syntax: `**strong** {ex:property}`
296
+ - HTML: `<strong>`
297
+ - Content: Text within strong markers
298
+
299
+ 3. **Code Spans** - Backtick-enclosed code
300
+ - Syntax: `` `code` {ex:property} ``
301
+ - HTML: `<code>`
302
+ - Content: Text within backticks
303
+
304
+ 4. **Links** - `[text](url)` syntax
305
+ - Syntax: `[Link Text](https://example.com) {ex:property}`
306
+ - HTML: `<a href="https://example.com">`
307
+ - Content: Link text (between brackets)
308
+ - Subject Resolution: URL becomes subject unless explicit subject provided
309
+
310
+ 5. **Images** - `![alt](url)` syntax
311
+ - Syntax: `![Alt Text](image.png) {ex:property}`
312
+ - HTML: `<img src="image.png" alt="Alt Text">`
313
+ - Content: Alt text (after `!`)
314
+ - Subject Resolution: Image URL becomes subject unless explicit subject
315
+
316
+ 6. **Angle Links** - `<url>` syntax
317
+ - Syntax: `<https://example.com> {ex:property}`
318
+ - HTML: `<a href="https://example.com">`
319
+ - Content: URL itself
320
+ - Subject Resolution: URL becomes subject
321
+
322
+ **Carrier Detection Priority:**
323
+
324
+ 1. **Block carriers** are detected first during tokenization
325
+ 2. **Inline carriers** are extracted within block content
326
+ 3. **Links and images** have special subject resolution rules
327
+ 4. **Annotations** attach to the nearest valid carrier
328
+ 5. **Invalid carriers** generate no RDF output (graceful failure)
329
+
330
+ ---
331
+
332
+ ## 4. List Rendering System
333
+
334
+ ### 4.1 The Nested List Challenge
335
+
336
+ **The Core Problem:**
337
+ CommonMark nested lists require hierarchical HTML structure (`<ul><li><ul><li>...`) but streaming single-pass processing makes this challenging because:
338
+
339
+ 1. **Forward Context Needed** - To know when to close `<ul>` tags, we need to see future lines
340
+ 2. **Indentation Tracking** - Must maintain stack of nesting levels across the entire document
341
+ 3. **RDFa Preservation** - Each list item needs its semantic attributes preserved
342
+
343
+ **Streaming-Compatible Solution:**
344
+
345
+ We can preserve visual nesting while maintaining single-pass rendering through **level tracking with deferred closing**:
346
+
347
+ ### 4.2 Streaming List Processing Strategy
348
+
349
+ ```javascript
350
+ function processListItemsStreaming(listBlocks, state) {
351
+ let html = '';
352
+ let currentLevel = 0;
353
+ let openTags = []; // Track open <ul> and <li> tags
354
+
355
+ // Process blocks in order (single pass)
356
+ for (const block of listBlocks) {
357
+ const indent = getIndentLevel(block, state.sourceText);
358
+ const targetLevel = Math.floor(indent / 2); // 2 spaces per level
359
+
360
+ // Close tags when going up the hierarchy
361
+ while (currentLevel > targetLevel) {
362
+ if (openTags.pop() === 'li') {
363
+ html += '</li>';
364
+ } else {
365
+ html += '</ul>';
366
+ }
367
+ currentLevel--;
368
+ }
369
+
370
+ // Open tags when going down the hierarchy
371
+ while (currentLevel < targetLevel) {
372
+ html += '<ul>';
373
+ openTags.push('ul');
374
+ currentLevel++;
375
+ }
376
+
377
+ // Close previous li if we're at same level
378
+ if (openTags[openTags.length - 1] === 'li') {
379
+ html += '</li>';
380
+ openTags.pop();
381
+ }
382
+
383
+ // Render current list item
384
+ const attrs = buildRDFaAttrsFromBlock(block, state.ctx);
385
+ const content = extractListContent(block, state.sourceText);
386
+ html += `<li${attrs}>${escapeHtml(content)}`;
387
+ openTags.push('li');
388
+ }
389
+
390
+ // Close all remaining tags
391
+ while (openTags.length > 0) {
392
+ const tag = openTags.pop();
393
+ html += `</${tag}>`;
394
+ }
395
+
396
+ return html;
397
+ }
398
+ ```
399
+
400
+ ### 4.3 Indentation-Based Level Detection
401
+
402
+ ```javascript
403
+ function getIndentLevel(block, sourceText) {
404
+ if (!block.range || !sourceText) return 0;
405
+
406
+ const text = sourceText.substring(block.range.start, block.range.end);
407
+ const indentMatch = text.match(/^(\s*)/);
408
+ const indentSpaces = indentMatch ? indentMatch[1].length : 0;
409
+
410
+ // CommonMark: 4 spaces or 1 tab = one level
411
+ // We'll use 2 spaces for better readability (configurable)
412
+ return Math.floor(indentSpaces / 2);
413
+ }
414
+ ```
415
+
416
+ ### 4.4 Content Extraction with Nesting Preservation
417
+
418
+ ```javascript
419
+ function extractListContent(block, sourceText) {
420
+ if (!block.range || !sourceText) return '';
421
+
422
+ let text = sourceText.substring(block.range.start, block.range.end);
423
+
424
+ // Remove list marker (-, *, +, or 1. 2. etc.)
425
+ text = text.replace(/^(\s*[-*+]|\s*\d+\.)\s+/, '');
426
+
427
+ // Remove MD-LD annotations
428
+ if (block.attrsRange) {
429
+ const beforeAttrs = text.substring(0, block.attrsRange.start - block.range.start);
430
+ const afterAttrs = text.substring(block.attrsRange.end - block.range.start);
431
+ text = beforeAttrs + afterAttrs;
432
+ }
433
+
434
+ return text.trim();
435
+ }
436
+ ```
437
+
438
+ ### 4.5 Complete List Rendering Pipeline
439
+
440
+ ```javascript
441
+ function renderListsWithRDFa(listBlocks, state) {
442
+ // Group consecutive list blocks (maintains document structure)
443
+ const listGroups = groupConsecutiveListBlocks(listBlocks, state.sourceText);
444
+
445
+ let html = '';
446
+
447
+ for (const group of listGroups) {
448
+ // Extract list anchor text (paragraph before list)
449
+ const anchorText = extractListAnchorText(group.blocks[0], state.sourceText);
450
+ if (anchorText) {
451
+ html += `<p>${escapeHtml(anchorText)}</p>`;
452
+ }
453
+
454
+ // Process list items with streaming-compatible nesting
455
+ html += processListItemsStreaming(group.blocks, state);
456
+ }
457
+
458
+ return html;
459
+ }
460
+
461
+ function groupConsecutiveListBlocks(listBlocks, sourceText) {
462
+ const groups = [];
463
+ let currentGroup = null;
464
+ let lastPosition = -1;
465
+
466
+ for (const block of listBlocks) {
467
+ if (!block.range) continue;
468
+
469
+ // Check if this is consecutive with previous block
470
+ const isConsecutive = lastPosition >= 0 &&
471
+ (block.range.start - lastPosition) <= (sourceText.substring(lastPosition, block.range.start).match(/\n/g) || []).length * 2 + 10;
472
+
473
+ if (!isConsecutive || !currentGroup) {
474
+ if (currentGroup) groups.push(currentGroup);
475
+ currentGroup = { blocks: [block] };
476
+ } else {
477
+ currentGroup.blocks.push(block);
478
+ }
479
+
480
+ lastPosition = block.range.end;
481
+ }
482
+
483
+ if (currentGroup) groups.push(currentGroup);
484
+ return groups;
485
+ }
486
+ ```
487
+
488
+ ### 4.6 Streaming Complexity Analysis
489
+
490
+ | Operation | Complexity | Streaming Compatible |
491
+ |-----------|-------------|-------------------|
492
+ | **Indentation Detection** | O(1) per block | ✅ Yes |
493
+ | **Level Tracking** | O(1) per block | ✅ Yes |
494
+ | **Tag Stack Management** | O(1) per block | ✅ Yes |
495
+ | **Content Extraction** | O(1) per block | ✅ Yes |
496
+ | **Deferred Closing** | O(1) per block | ✅ Yes |
497
+
498
+ **Key Insight:** We never need to look ahead - we maintain a stack of open tags and close them when indentation decreases, which is detectable in the current line.
499
+
500
+ ### 4.7 Example: Nested List Processing
501
+
502
+ **Input MD-LD:**
503
+ ```md
504
+ Items {=ex:items .ex:Collection}
505
+ - Top Level 1 {=ex:item1 .ex:Item name}
506
+ - Top Level 2 {=ex:item2 .ex:Item name}
507
+ - Nested 1 {=ex:nested1 .ex:Item name ?hasPart}
508
+ - Nested 2 {=ex:nested2 .ex:Item name ?hasPart}
509
+ - Deep Nested {=ex:deep .ex:Item name ?hasPart}
510
+ - Top Level 3 {=ex:item3 .ex:Item name}
511
+ ```
512
+
513
+ **Streaming Processing Steps:**
514
+ ```javascript
515
+ // Block 1: "Top Level 1" (indent 0, level 0)
516
+ currentLevel = 0, targetLevel = 0
517
+ html += '<li about="ex:item1" typeof="ex:Item" property="rdfs:label">Top Level 1</li>'
518
+
519
+ // Block 2: "Top Level 2" (indent 0, level 0)
520
+ currentLevel = 0, targetLevel = 0
521
+ html += '</li><li about="ex:item2" typeof="ex:Item" property="rdfs:label">Top Level 2</li>'
522
+
523
+ // Block 3: "Nested 1" (indent 2, level 1)
524
+ currentLevel = 0, targetLevel = 1
525
+ html += '<ul><li about="ex:nested1" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Nested 1</li>'
526
+
527
+ // Block 4: "Nested 2" (indent 2, level 1)
528
+ currentLevel = 1, targetLevel = 1
529
+ html += '</li><li about="ex:nested2" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Nested 2</li>'
530
+
531
+ // Block 5: "Deep Nested" (indent 4, level 2)
532
+ currentLevel = 1, targetLevel = 2
533
+ html += '<ul><li about="ex:deep" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Deep Nested</li>'
534
+
535
+ // Block 6: "Top Level 3" (indent 0, level 0)
536
+ currentLevel = 2, targetLevel = 0
537
+ html += '</li></ul></ul></li><li about="ex:item3" typeof="ex:Item" property="rdfs:label">Top Level 3</li>'
538
+ ```
539
+
540
+ **Final HTML Output:**
541
+ ```html
542
+ <p>Items</p>
543
+ <ul>
544
+ <li about="ex:item1" typeof="ex:Item" property="rdfs:label">Top Level 1</li>
545
+ <li about="ex:item2" typeof="ex:Item" property="rdfs:label">Top Level 2
546
+ <ul>
547
+ <li about="ex:nested1" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Nested 1</li>
548
+ <li about="ex:nested2" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Nested 2
549
+ <ul>
550
+ <li about="ex:deep" typeof="ex:Item" property="rdfs:label" rel="ex:hasPart">Deep Nested</li>
551
+ </ul>
552
+ </li>
553
+ </ul>
554
+ </li>
555
+ <li about="ex:item3" typeof="ex:Item" property="rdfs:label">Top Level 3</li>
556
+ </ul>
557
+ ```
558
+
559
+ ### 4.8 Advantages of This Approach
560
+
561
+ 1. **True Single-Pass** - No look-ahead needed, stack-based closing
562
+ 2. **Memory Efficient** - Only track current open tags, not entire document structure
563
+ 3. **Semantic Preservation** - All RDFa attributes maintained correctly
564
+ 4. **CommonMark Compliant** - Proper nesting structure preserved
565
+ 5. **Streaming Ready** - Can process large lists incrementally
566
+
567
+ ### 4.9 Edge Cases Handled
568
+
569
+ - **Mixed Indentation** - Tabs and spaces handled uniformly
570
+ - **Inconsistent Nesting** - Graceful handling of malformed lists
571
+ - **Empty List Items** - Proper `<li></li>` generation
572
+ - **Deep Nesting** - No limit on nesting depth (stack-based)
573
+ - **Interspersed Non-List** - List groups properly separated
574
+
575
+ This approach achieves the perfect balance: preserving CommonMark's visual nesting while maintaining the streaming single-pass constraint that's core to MD-LD's architecture.
576
+
577
+ ### 4.10 Advanced List Processing
578
+
579
+ To achieve full CommonMark compliance, the renderer must handle sophisticated list behaviors while maintaining streaming compatibility.
580
+
581
+ #### 4.10.1 Tight vs Loose Lists
582
+
583
+ **CommonMark Rules:**
584
+ - **Tight List**: No blank lines between list items → `<p>` tags omitted
585
+ - **Loose List**: Blank lines between list items → `<p>` tags included
586
+
587
+ **Streaming Detection Strategy:**
588
+ ```javascript
589
+ function detectListTightness(listBlocks, sourceText) {
590
+ let isTight = true;
591
+ let lastEnd = -1;
592
+
593
+ for (let i = 0; i < listBlocks.length; i++) {
594
+ const block = listBlocks[i];
595
+ if (!block.range) continue;
596
+
597
+ if (lastEnd >= 0) {
598
+ // Check for blank line between items
599
+ const between = sourceText.substring(lastEnd, block.range.start);
600
+ const blankLineCount = (between.match(/\n\s*\n/g) || []).length;
601
+
602
+ if (blankLineCount > 0) {
603
+ isTight = false;
604
+ break; // Once loose, always loose
605
+ }
606
+ }
607
+
608
+ lastEnd = block.range.end;
609
+ }
610
+
611
+ return isTight;
612
+ }
613
+ ```
614
+
615
+ **Rendering Implementation:**
616
+ ```javascript
617
+ function renderListItemContent(block, isTight, state) {
618
+ const content = extractListContent(block, state.sourceText);
619
+ const attrs = buildRDFaAttrsFromBlock(block, state.ctx);
620
+
621
+ if (isTight) {
622
+ // Tight: no paragraph wrapper
623
+ return `<li${attrs}>${escapeHtml(content)}</li>`;
624
+ } else {
625
+ // Loose: wrap in paragraph
626
+ return `<li${attrs}><p>${escapeHtml(content)}</p></li>`;
627
+ }
628
+ }
629
+ ```
630
+
631
+ #### 4.10.2 List Interruption
632
+
633
+ **CommonMark Rule:** Lists can interrupt paragraphs without blank lines when:
634
+ 1. List item starts at the same indentation level as paragraph text
635
+ 2. List item marker is followed by required whitespace
636
+
637
+ **Streaming Detection:**
638
+ ```javascript
639
+ function detectListInterruption(block, precedingBlock, sourceText) {
640
+ if (!precedingBlock || precedingBlock.type !== 'para') return false;
641
+
642
+ // Check if list item immediately follows paragraph
643
+ const between = sourceText.substring(precedingBlock.range.end, block.range.start);
644
+ const hasBlankLine = between.match(/\n\s*\n/);
645
+
646
+ if (hasBlankLine) return false; // Not an interruption
647
+
648
+ // Check indentation alignment
649
+ const paragraphIndent = getTextIndent(precedingBlock, sourceText);
650
+ const listIndent = getIndentLevel(block, sourceText);
651
+
652
+ return listIndent <= paragraphIndent + 4; // Within 4 spaces = interruption
653
+ }
654
+ ```
655
+
656
+ **Rendering Strategy:**
657
+ ```javascript
658
+ function renderInterruptedList(listBlocks, precedingBlock, state) {
659
+ let html = '';
660
+
661
+ // Handle paragraph continuation after list
662
+ if (precedingBlock && precedingBlock.type === 'para') {
663
+ // Render paragraph content up to interruption point
664
+ const interruptionPoint = findInterruptionPoint(precedingBlock, listBlocks[0], state.sourceText);
665
+ const beforeContent = state.sourceText.substring(precedingBlock.range.start, interruptionPoint);
666
+
667
+ html += `<p>${escapeHtml(beforeContent)}</p>`;
668
+ html += processListItemsStreaming(listBlocks, state);
669
+
670
+ // Check for paragraph continuation after list
671
+ const afterContent = extractParagraphAfterList(precedingBlock, listBlocks, state.sourceText);
672
+ if (afterContent) {
673
+ html += `<p>${escapeHtml(afterContent)}</p>`;
674
+ }
675
+ }
676
+
677
+ return html;
678
+ }
679
+ ```
680
+
681
+ #### 4.10.3 Mixed List Markers
682
+
683
+ **CommonMark Rules:**
684
+ - Changing bullet types (-, +, *) starts new list
685
+ - Changing ordered delimiters (1., 1.) starts new list
686
+ - Same marker type continues current list
687
+
688
+ **Streaming Detection:**
689
+ ```javascript
690
+ function getListMarker(block, sourceText) {
691
+ if (!block.range) return null;
692
+
693
+ const text = sourceText.substring(block.range.start, block.range.end);
694
+ const markerMatch = text.match(/^(\s*)([-*+]|\d+\[\.|\])\s+/);
695
+
696
+ if (!markerMatch) return null;
697
+
698
+ return {
699
+ type: markerMatch[2].startsWith('-') ? 'dash' :
700
+ markerMatch[2].startsWith('*') ? 'asterisk' :
701
+ markerMatch[2].startsWith('+') ? 'plus' : 'ordered',
702
+ marker: markerMatch[2],
703
+ indent: markerMatch[1].length
704
+ };
705
+ }
706
+
707
+ function shouldStartNewList(currentMarker, previousMarker) {
708
+ if (!previousMarker) return false;
709
+
710
+ // Different marker types = new list
711
+ if (currentMarker.type !== previousMarker.type) return true;
712
+
713
+ // Ordered markers with different delimiters = new list
714
+ if (currentMarker.type === 'ordered' &&
715
+ currentMarker.marker !== previousMarker.marker) return true;
716
+
717
+ return false;
718
+ }
719
+ ```
720
+
721
+ **Grouping Strategy:**
722
+ ```javascript
723
+ function groupByMarkerType(listBlocks, sourceText) {
724
+ const groups = [];
725
+ let currentGroup = null;
726
+ let lastMarker = null;
727
+
728
+ for (const block of listBlocks) {
729
+ const marker = getListMarker(block, sourceText);
730
+
731
+ if (!marker || shouldStartNewList(marker, lastMarker)) {
732
+ if (currentGroup) groups.push(currentGroup);
733
+ currentGroup = {
734
+ blocks: [block],
735
+ markerType: marker?.type || 'unknown',
736
+ marker: marker?.marker
737
+ };
738
+ } else {
739
+ currentGroup.blocks.push(block);
740
+ }
741
+
742
+ lastMarker = marker;
743
+ }
744
+
745
+ if (currentGroup) groups.push(currentGroup);
746
+ return groups;
747
+ }
748
+ ```
749
+
750
+ #### 4.10.4 Lazy Continuation
751
+
752
+ **CommonMark Rule:** List items can span multiple lines with:
753
+ - At least one space indentation for continuation
754
+ - Content aligned with first non-whitespace character of first line
755
+
756
+ **Streaming Detection:**
757
+ ```javascript
758
+ function detectLazyContinuation(listBlocks, sourceText) {
759
+ const continuationBlocks = [];
760
+
761
+ for (let i = 0; i < listBlocks.length; i++) {
762
+ const block = listBlocks[i];
763
+ const nextBlock = listBlocks[i + 1];
764
+
765
+ if (!nextBlock) break;
766
+
767
+ // Check if next block is a continuation
768
+ const currentIndent = getIndentLevel(block, sourceText);
769
+ const nextIndent = getIndentLevel(nextBlock, sourceText);
770
+
771
+ // Continuation: indented but not enough to be nested
772
+ if (nextIndent > currentIndent && nextIndent <= currentIndent + 3) {
773
+ continuationBlocks.push({
774
+ parent: block,
775
+ continuation: nextBlock,
776
+ level: currentIndent
777
+ });
778
+ }
779
+ }
780
+
781
+ return continuationBlocks;
782
+ }
783
+ ```
784
+
785
+ **Rendering Implementation:**
786
+ ```javascript
787
+ function renderListWithContinuations(listBlocks, state) {
788
+ const continuations = detectLazyContinuation(listBlocks, state.sourceText);
789
+ const processedBlocks = new Set();
790
+
791
+ let html = '';
792
+
793
+ for (const block of listBlocks) {
794
+ if (processedBlocks.has(block)) continue;
795
+
796
+ // Find all continuations for this block
797
+ const blockContinuations = continuations
798
+ .filter(c => c.parent === block)
799
+ .map(c => c.continuation);
800
+
801
+ // Combine content from main block and continuations
802
+ let combinedContent = extractListContent(block, state.sourceText);
803
+ for (const continuation of blockContinuations) {
804
+ combinedContent += ' ' + extractListContent(continuation, state.sourceText);
805
+ processedBlocks.add(continuation);
806
+ }
807
+
808
+ const attrs = buildRDFaAttrsFromBlock(block, state.ctx);
809
+ html += `<li${attrs}><p>${escapeHtml(combinedContent)}</p></li>`;
810
+ processedBlocks.add(block);
811
+ }
812
+
813
+ return html;
814
+ }
815
+ ```
816
+
817
+ #### 4.10.5 Complete Advanced List Pipeline
818
+
819
+ ```javascript
820
+ function renderAdvancedListsWithRDFa(listBlocks, state) {
821
+ // Step 1: Group by marker type
822
+ const markerGroups = groupByMarkerType(listBlocks, state.sourceText);
823
+
824
+ let html = '';
825
+
826
+ for (const group of markerGroups) {
827
+ // Step 2: Detect tight vs loose
828
+ const isTight = detectListTightness(group.blocks, state.sourceText);
829
+
830
+ // Step 3: Detect and handle continuations
831
+ const hasContinuations = detectLazyContinuation(group.blocks, state.sourceText).length > 0;
832
+
833
+ // Step 4: Render with appropriate strategy
834
+ if (hasContinuations) {
835
+ html += renderListWithContinuations(group.blocks, state);
836
+ } else {
837
+ html += processListItemsStreaming(group.blocks, state, isTight);
838
+ }
839
+ }
840
+
841
+ return html;
842
+ }
843
+ ```
844
+
845
+ #### 4.10.6 Streaming Complexity Analysis
846
+
847
+ | Feature | Complexity | Streaming Compatible | Memory Impact |
848
+ |---------|-------------|-------------------|---------------|
849
+ | **Tight/Loose Detection** | O(n) | ✅ Yes | O(1) |
850
+ | **List Interruption** | O(1) per block | ✅ Yes | O(1) |
851
+ | **Mixed Markers** | O(1) per block | ✅ Yes | O(1) |
852
+ | **Lazy Continuation** | O(n) per group | ✅ Yes | O(k) where k = continuations |
853
+ | **Combined Pipeline** | O(n) total | ✅ Yes | O(n) minimal |
854
+
855
+ #### 4.10.7 Example: Advanced List Processing
856
+
857
+ **Input MD-LD:**
858
+ ```md
859
+ Paragraph that gets interrupted by a list.
860
+
861
+ - First item {=ex:item1}
862
+ - Second item {=ex:item2}
863
+ with lazy continuation {ex:continuation}
864
+
865
+ * Different marker starts new list {=ex:other1}
866
+ * Another item {=ex:other2}
867
+
868
+ Back to paragraph content.
869
+ ```
870
+
871
+ **Processing Steps:**
872
+ 1. **Detect interruption** - List immediately follows paragraph
873
+ 2. **Group by markers** - `-` items separate from `*` items
874
+ 3. **Detect tightness** - No blank lines = tight list
875
+ 4. **Detect continuations** - "with lazy continuation" spans lines
876
+ 5. **Render with proper structure** - Maintain semantic attributes
877
+
878
+ **HTML Output:**
879
+ ```html
880
+ <p>Paragraph that gets interrupted by a list.</p>
881
+ <ul>
882
+ <li about="ex:item1" property="rdfs:label">First item</li>
883
+ <li about="ex:item2" property="rdfs:label"><p>Second item with lazy continuation</p></li>
884
+ </ul>
885
+ <ul>
886
+ <li about="ex:other1" property="rdfs:label">Different marker starts new list</li>
887
+ <li about="ex:other2" property="rdfs:label">Another item</li>
888
+ </ul>
889
+ <p>Back to paragraph content.</p>
890
+ ```
891
+
892
+ These advanced features ensure full CommonMark compliance while maintaining the streaming single-pass architecture that makes MD-LD efficient and predictable.
893
+
894
+ ---
895
+
896
+ ## 5. Context Management
897
+
898
+ ### 5.1 Prefix Declaration Generation
899
+
900
+ ```javascript
901
+ function generatePrefixDeclarations(ctx) {
902
+ const prefixes = [];
903
+
904
+ for (const [prefix, iri] of Object.entries(ctx)) {
905
+ if (prefix !== '@vocab') {
906
+ prefixes.push(`${prefix}: ${iri}`);
907
+ }
908
+ }
909
+
910
+ return prefixes.length > 0 ? ` prefix="${prefixes.join(' ')}"` : '';
911
+ }
912
+ ```
913
+
914
+ ### 5.2 Vocabulary Declaration
915
+
916
+ ```javascript
917
+ function generateVocabDeclaration(ctx) {
918
+ return ctx['@vocab'] ? ` vocab="${ctx['@vocab']}"` : '';
919
+ }
920
+ ```
921
+
922
+ ### 5.3 RDFa Context Wrapper
923
+
924
+ ```javascript
925
+ function wrapWithRDFaContext(html, ctx) {
926
+ const prefixDecl = generatePrefixDeclarations(ctx);
927
+ const vocabDecl = generateVocabDeclaration(ctx);
928
+
929
+ return `<div${prefixDecl}${vocabDecl}>${html}</div>`;
930
+ }
931
+ ```
932
+
933
+ ---
934
+
935
+ ## 6. Interactive Features
936
+
937
+ ### 6.1 Data Attributes for Agent Interaction
938
+
939
+ ```javascript
940
+ function buildDataAttributes(block) {
941
+ const attrs = [];
942
+
943
+ // Block identification
944
+ if (block.id) attrs.push(`data-block-id="${block.id}"`);
945
+
946
+ // Source tracking
947
+ if (block.range) {
948
+ attrs.push(`data-range-start="${block.range.start}"`);
949
+ attrs.push(`data-range-end="${block.range.end}"`);
950
+ }
951
+
952
+ // Semantic metadata
953
+ if (block.subject) attrs.push(`data-subject="${block.subject}"`);
954
+ if (block.types?.length) attrs.push(`data-types="${block.types.join(',')}"`);
955
+
956
+ return attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
957
+ }
958
+ ```
959
+
960
+ ### 6.2 Hover and Click Targets
961
+
962
+ ```javascript
963
+ // Enhanced block rendering with interaction support
964
+ function renderInteractiveBlock(block, state) {
965
+ const rdfaAttrs = buildRDFaAttrsFromBlock(block, state.ctx);
966
+ const dataAttrs = buildDataAttributes(block);
967
+
968
+ state.output.push(`<${tag}${rdfaAttrs}${dataAttrs}>`);
969
+ renderBlockContent(block, state);
970
+ state.output.push(`</${tag}>`);
971
+ }
972
+ ```
973
+
974
+ ### 6.3 Provenance Preservation
975
+
976
+ ```javascript
977
+ // Origin tracking in rendered output
978
+ function addOriginMetadata(block, state) {
979
+ if (block.id && state.origin.quadIndex) {
980
+ const relatedQuads = Array.from(state.origin.quadIndex.entries())
981
+ .filter(([key, entry]) => entry.blockId === block.id);
982
+
983
+ if (relatedQuads.length > 0) {
984
+ state.output.push(`<!-- Origin: ${block.id}, Quads: ${relatedQuads.length} -->`);
985
+ }
986
+ }
987
+ }
988
+ ```
989
+
990
+ ---
991
+
992
+ ## 7. Performance Characteristics
993
+
994
+ ### 7.1 Complexity Analysis
995
+
996
+ | Operation | Complexity | Description |
997
+ |-----------|-------------|-------------|
998
+ | **Parse Integration** | O(1) | Direct reuse of parser output |
999
+ | **Block Sorting** | O(n log n) | One-time sort by position |
1000
+ | **Block Rendering** | O(n) | Single pass through blocks |
1001
+ | **List Processing** | O(n) | Linear scan of list items |
1002
+ | **Context Generation** | O(p) | p = number of prefixes |
1003
+
1004
+ ### 7.2 Memory Usage
1005
+
1006
+ | Component | Memory Pattern | Cleanup Strategy |
1007
+ |-----------|----------------|------------------|
1008
+ | **Render State** | Fixed overhead | Automatic GC |
1009
+ | **Block Array** | O(n) growth | Released after render |
1010
+ | **Output Buffer** | O(n) growth | Converted to string |
1011
+ | **Context Cache** | Reused from parser | No additional allocation |
1012
+
1013
+ ### 7.3 Streaming Compatibility
1014
+
1015
+ ```javascript
1016
+ // Future streaming interface design
1017
+ function renderStream(mdldStream, options) {
1018
+ return new TransformStream({
1019
+ transform(chunk, controller) {
1020
+ const parsed = parse(chunk.toString(), options);
1021
+ const rendered = renderBlocks(parsed.origin.blocks, buildState(parsed, options));
1022
+ controller.enqueue(wrapWithRDFaContext(rendered, parsed.context));
1023
+ }
1024
+ });
1025
+ }
1026
+ ```
1027
+
1028
+ ---
1029
+
1030
+ ## 8. Error Handling
1031
+
1032
+ ### 8.1 Graceful Degradation
1033
+
1034
+ ```javascript
1035
+ function safeRenderBlock(block, state) {
1036
+ try {
1037
+ renderBlock(block, state);
1038
+ } catch (error) {
1039
+ // Fallback rendering
1040
+ state.output.push(`<div class="mdld-error">`);
1041
+ state.output.push(escapeHtml(state.sourceText.substring(
1042
+ block.range.start, block.range.end
1043
+ )));
1044
+ state.output.push(`</div>`);
1045
+
1046
+ // Log error for debugging
1047
+ console.warn('Render error:', error, block);
1048
+ }
1049
+ }
1050
+ ```
1051
+
1052
+ ### 8.2 Validation Strategy
1053
+
1054
+ ```javascript
1055
+ function validateRenderInput(parsed) {
1056
+ const errors = [];
1057
+
1058
+ if (!parsed.quads) errors.push('Missing quads array');
1059
+ if (!parsed.origin) errors.push('Missing origin data');
1060
+ if (!parsed.context) errors.push('Missing context object');
1061
+
1062
+ return {
1063
+ valid: errors.length === 0,
1064
+ errors
1065
+ };
1066
+ }
1067
+ ```
1068
+
1069
+ ---
1070
+
1071
+ ## 9. Output Specification
1072
+
1073
+ ### 9.1 HTML Structure
1074
+
1075
+ ```html
1076
+ <!DOCTYPE html>
1077
+ <html>
1078
+ <head>
1079
+ <title>MD-LD Rendered Document</title>
1080
+ </head>
1081
+ <body>
1082
+ <div prefix="schema: http://schema.org/ ex: http://example.org/"
1083
+ vocab="http://www.w3.org/2000/01/rdf-schema#">
1084
+
1085
+ <!-- Rendered content with RDFa markup -->
1086
+ <h1 about="ex:document" typeof="schema:Article" property="rdfs:label">
1087
+ Document Title
1088
+ </h1>
1089
+
1090
+ <p about="ex:document">
1091
+ Content with <span about="ex:entity" typeof="schema:Person"
1092
+ property="rdfs:label">linked entities</span>.
1093
+ </p>
1094
+
1095
+ <ul>
1096
+ <li about="ex:item1" typeof="schema:ListItem" property="rdfs:label">
1097
+ List Item 1
1098
+ </li>
1099
+ <li about="ex:item2" typeof="schema:ListItem" property="rdfs:label">
1100
+ List Item 2
1101
+ </li>
1102
+ </ul>
1103
+
1104
+ </div>
1105
+ </body>
1106
+ </html>
1107
+ ```
1108
+
1109
+ ### 9.2 RDFa Attribute Mapping
1110
+
1111
+ | MD-LD Construct | RDFa Output | Example |
1112
+ |-----------------|-------------|---------|
1113
+ | `{=ex:subject}` | `about="ex:subject"` | Subject declaration |
1114
+ | `{.Type}` | `typeof="ex:Type"` | Type assertion |
1115
+ | `{property}` | `property="ex:property"` | Literal property |
1116
+ | `{?object}` | `rel="ex:object"` | Object property |
1117
+ | `{!reverse}` | `rev="ex:reverse"` | Reverse property |
1118
+
1119
+ ### 9.3 Return Value Structure
1120
+
1121
+ ```javascript
1122
+ const renderResult = {
1123
+ html: '<div prefix="...">...</div>', // Complete HTML output
1124
+ context: { // Final resolved context
1125
+ '@vocab': 'http://www.w3.org/2000/01/rdf-schema#',
1126
+ 'schema': 'http://schema.org/',
1127
+ 'ex': 'http://example.org/'
1128
+ },
1129
+ metadata: {
1130
+ blockCount: 42, // Number of rendered blocks
1131
+ quadCount: 156, // Number of RDF triples
1132
+ renderTime: 1672531200000, // Render timestamp
1133
+ listGroups: 3, // Number of list groups
1134
+ interactiveBlocks: 28 // Blocks with data attributes
1135
+ },
1136
+ origin: parsed.origin, // Complete provenance data
1137
+ statements: parsed.statements // Elevated statements
1138
+ };
1139
+ ```
1140
+
1141
+ ---
1142
+
1143
+ ## 10. Extensibility Points
1144
+
1145
+ ### 10.1 Custom Block Renderers
1146
+
1147
+ ```javascript
1148
+ const CUSTOM_RENDERERS = {
1149
+ 'custom-block': (block, state) => {
1150
+ const attrs = buildRDFaAttrsFromBlock(block, state.ctx);
1151
+ state.output.push(`<section${attrs}>`);
1152
+ renderBlockContent(block, state);
1153
+ state.output.push(`</section>`);
1154
+ }
1155
+ };
1156
+ ```
1157
+
1158
+ ### 10.2 Attribute Transformers
1159
+
1160
+ ```javascript
1161
+ const ATTR_TRANSFORMERS = {
1162
+ 'custom-attr': (value, block, ctx) => {
1163
+ // Custom attribute transformation logic
1164
+ return transformValue(value, ctx);
1165
+ }
1166
+ };
1167
+ ```
1168
+
1169
+ ### 10.3 Content Processors
1170
+
1171
+ ```javascript
1172
+ const CONTENT_PROCESSORS = {
1173
+ 'custom-content': (text, block, state) => {
1174
+ // Custom content processing (e.g., markdown parsing)
1175
+ return processMarkdown(text);
1176
+ }
1177
+ };
1178
+ ```
1179
+
1180
+ ---
1181
+
1182
+ ## 11. Browser Compatibility
1183
+
1184
+ ### 11.1 Modern Browser Support
1185
+
1186
+ - **ES6+ Modules** — `import/export` syntax
1187
+ - **Map/Set** — Efficient data structures
1188
+ - **Template Literals** — String interpolation
1189
+ - **Arrow Functions** — Concise syntax
1190
+ - **Destructuring** — Object/array unpacking
1191
+
1192
+ ### 11.2 CDN Usage
1193
+
1194
+ ```html
1195
+ <!-- Direct browser usage -->
1196
+ <script type="module">
1197
+ import { render } from 'https://cdn.jsdelivr.net/npm/mdld-parse/render.js';
1198
+
1199
+ const mdld = '# Title {=ex:title .schema:Thing label}';
1200
+ const result = render(mdld);
1201
+ document.body.innerHTML = result.html;
1202
+ </script>
1203
+ ```
1204
+
1205
+ ---
1206
+
1207
+ ## 12. Security Considerations
1208
+
1209
+ ### 12.1 Input Sanitization
1210
+
1211
+ ```javascript
1212
+ function sanitizeRenderInput(mdld) {
1213
+ // Remove potentially dangerous content
1214
+ return mdld
1215
+ .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
1216
+ .replace(/javascript:/gi, '')
1217
+ .replace(/on\w+\s*=/gi, '');
1218
+ }
1219
+ ```
1220
+
1221
+ ### 12.2 Output Escaping
1222
+
1223
+ ```javascript
1224
+ function escapeHtml(text) {
1225
+ const map = {
1226
+ '&': '&amp;',
1227
+ '<': '&lt;',
1228
+ '>': '&gt;',
1229
+ '"': '&quot;',
1230
+ "'": '&#x27;',
1231
+ '/': '&#x2F;'
1232
+ };
1233
+ return String(text || '').replace(/[&<>"'/]/g, m => map[m]);
1234
+ }
1235
+ ```
1236
+
1237
+ ### 12.3 IRI Validation
1238
+
1239
+ ```javascript
1240
+ function validateIRI(iri) {
1241
+ // Basic IRI validation
1242
+ return iri &&
1243
+ typeof iri === 'string' &&
1244
+ !iri.includes('javascript:') &&
1245
+ !iri.includes('data:') &&
1246
+ /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(iri);
1247
+ }
1248
+ ```
1249
+
1250
+ ---
1251
+
1252
+ ## 13. Testing Strategy
1253
+
1254
+ ### 13.1 Unit Test Coverage
1255
+
1256
+ ```javascript
1257
+ describe('MD-LD Render', () => {
1258
+ test('renders heading with RDFa', () => {
1259
+ const mdld = '# Title {=ex:title .schema:Thing label}';
1260
+ const result = render(mdld);
1261
+
1262
+ expect(result.html).toContain('<h1 about="ex:title" typeof="schema:Thing" property="rdfs:label">');
1263
+ expect(result.html).toContain('Title');
1264
+ expect(result.html).toContain('</h1>');
1265
+ });
1266
+
1267
+ test('preserves list hierarchy', () => {
1268
+ const mdld = `- Item 1 {=ex:item1}\n - Subitem {=ex:sub}`;
1269
+ const result = render(mdld);
1270
+
1271
+ expect(result.html).toContain('<ul>');
1272
+ expect(result.html).toContain('<li about="ex:item1">');
1273
+ expect(result.html).toContain('<ul>');
1274
+ expect(result.html).toContain('<li about="ex:sub">');
1275
+ });
1276
+ });
1277
+ ```
1278
+
1279
+ ### 13.2 Integration Tests
1280
+
1281
+ ```javascript
1282
+ test('round-trip preservation', () => {
1283
+ const mdld = '# Test {=tag:me@example.org,2026:test .prov:Entity label}';
1284
+ const parsed = parse({text: mdld});
1285
+ const rendered = render(mdld);
1286
+
1287
+ // Verify RDF semantics preserved
1288
+ expect(parsed.quads).toHaveLength(2); // type + label
1289
+ expect(rendered.html).toContain('about="ex:test"');
1290
+ expect(rendered.html).toContain('typeof="ex:Type"');
1291
+ expect(rendered.html).toContain('property="rdfs:label"');
1292
+ });
1293
+ ```
1294
+
1295
+ ### 13.3 Performance Tests
1296
+
1297
+ ```javascript
1298
+ test('rendering performance', () => {
1299
+ const largeMdld = generateLargeDocument(10000); // 10K tokens
1300
+ const start = performance.now();
1301
+
1302
+ const result = render(largeMdld);
1303
+
1304
+ const duration = performance.now() - start;
1305
+ expect(duration).toBeLessThan(1000); // < 1 second
1306
+ expect(result.html).toBeDefined();
1307
+ });
1308
+ ```
1309
+
1310
+ ---
1311
+
1312
+ ## 14. Conformance Requirements
1313
+
1314
+ ### 14.1 Required Behaviors
1315
+
1316
+ A conformant MD-LD renderer MUST:
1317
+
1318
+ 1. **Preserve All Semantics** — Every RDF triple must be represented in HTML+RDFa
1319
+ 2. **Maintain Document Structure** — HTML structure must reflect Markdown hierarchy
1320
+ 3. **Generate Valid RDFa** — All RDFa attributes must be syntactically correct
1321
+ 4. **Handle All Carrier Types** — Support every MD-LD value carrier
1322
+ 5. **Preserve Provenance** — Maintain complete origin tracking information
1323
+ 6. **Support Interactive Features** — Enable agent interaction through data attributes
1324
+
1325
+ ### 14.2 Optional Features
1326
+
1327
+ These features are RECOMMENDED but not required:
1328
+
1329
+ 1. **Syntax Highlighting** — Enhanced code block rendering
1330
+ 2. **Markdown Extensions** — Tables, footnotes, etc.
1331
+ 3. **Custom Themes** — CSS class generation
1332
+ 4. **Progressive Enhancement** — Graceful degradation without JavaScript
1333
+ 5. **Server-Side Rendering** — Node.js compatibility
1334
+
1335
+ ### 14.3 Validation Criteria
1336
+
1337
+ ```javascript
1338
+ function validateConformance(renderResult, originalParsed) {
1339
+ const errors = [];
1340
+
1341
+ // Check semantic preservation
1342
+ if (renderResult.metadata.quadCount !== originalParsed.quads.length) {
1343
+ errors.push('Quad count mismatch');
1344
+ }
1345
+
1346
+ // Check RDFa validity
1347
+ if (!isValidRDFa(renderResult.html)) {
1348
+ errors.push('Invalid RDFa markup');
1349
+ }
1350
+
1351
+ // Check structure preservation
1352
+ if (!hasValidHTMLStructure(renderResult.html)) {
1353
+ errors.push('Invalid HTML structure');
1354
+ }
1355
+
1356
+ return {
1357
+ conformant: errors.length === 0,
1358
+ errors
1359
+ };
1360
+ }
1361
+ ```
1362
+
1363
+ ---
1364
+
1365
+ ## 15. Implementation Guidelines
1366
+
1367
+ ### 15.1 Performance Optimization
1368
+
1369
+ 1. **Reuse Parser Output** — Leverage existing parsing work
1370
+ 2. **Minimize String Operations** — Use efficient concatenation
1371
+ 3. **Cache IRI Expansions** — Avoid repeated resolution
1372
+ 4. **Batch Attribute Generation** — Group RDFa attribute creation
1373
+ 5. **Optimize List Processing** — Single pass through list items
1374
+
1375
+ ### 15.2 Code Organization
1376
+
1377
+ ```javascript
1378
+ // Main render function
1379
+ export function render(mdld, options) { /* ... */ }
1380
+
1381
+ // Core rendering pipeline
1382
+ function buildRenderState(parsed, options, mdld) { /* ... */ }
1383
+ function renderBlocks(blocks, state) { /* ... */ }
1384
+ function renderBlock(block, state) { /* ... */ }
1385
+
1386
+ // Specialized renderers
1387
+ function renderListsWithRDFa(listBlocks, state) { /* ... */ }
1388
+ function renderInteractiveBlock(block, state) { /* ... */ }
1389
+
1390
+ // Utilities
1391
+ function buildRDFaAttrsFromBlock(block, ctx) { /* ... */ }
1392
+ function wrapWithRDFaContext(html, ctx) { /* ... */ }
1393
+ function escapeHtml(text) { /* ... */ }
1394
+ ```
1395
+
1396
+ ### 15.3 Development Workflow
1397
+
1398
+ 1. **Parser Integration** — Start with parser output
1399
+ 2. **Basic Rendering** — Implement core block types
1400
+ 3. **RDFa Generation** — Add semantic attributes
1401
+ 4. **List Processing** — Handle hierarchical lists
1402
+ 5. **Interactive Features** — Add data attributes
1403
+ 6. **Performance Optimization** — Profile and optimize
1404
+ 7. **Testing** — Comprehensive test coverage
1405
+ 8. **Documentation** — Maintain this specification
1406
+
1407
+ ---
1408
+
1409
+ ## 16. Future Enhancements
1410
+
1411
+ ### 16.2 Component-Based Rendering
1412
+
1413
+ ```javascript
1414
+ // Future: Custom render components
1415
+ const components = {
1416
+ 'timeline': renderTimeline,
1417
+ 'graph': renderGraph,
1418
+ 'table': renderTable
1419
+ };
1420
+
1421
+ function renderWithComponents(mdld, options) {
1422
+ // Component-based rendering system
1423
+ }
1424
+ ```
1425
+
1426
+ ### 16.3 Enhanced Interactivity
1427
+
1428
+ ```javascript
1429
+ // Future: Advanced agent features
1430
+ function addAgentFeatures(html, parsed) {
1431
+ // Hover tooltips, click-to-edit, drag-drop
1432
+ // Real-time collaboration features
1433
+ // Visual graph overlays
1434
+ }
1435
+ ```
1436
+
1437
+ ---
1438
+
1439
+ This specification provides a comprehensive foundation for implementing the MD-LD Render function that maintains the same engineering excellence as the parser while enabling powerful interactive knowledge graph authoring experiences in the browser.