mdld-parse 0.8.4 β†’ 0.9.0

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.
package/README.md CHANGED
@@ -87,7 +87,8 @@ import { parse } from 'mdld-parse';
87
87
  const markdown = `# Document {=ex:doc .Article}
88
88
  [Alice] {author}`;
89
89
 
90
- const result = parse(markdown, {
90
+ const result = parse({
91
+ text: markdown,
91
92
  context: { ex: 'http://example.org/' }
92
93
  });
93
94
 
@@ -188,18 +189,20 @@ Declare resources inline with `{=iri}`:
188
189
 
189
190
  ## πŸ”§ API Reference
190
191
 
191
- ### `parse(markdown, options)`
192
+ ### `parse({ text, context, dataFactory, graph })`
192
193
 
193
194
  Parse MD-LD markdown and return RDF quads with lean origin tracking.
194
195
 
195
- **Parameters:**
196
- - `markdown` (string) β€” MD-LD formatted text
197
- - `options` (object, optional):
198
- - `context` (object) β€” Prefix mappings (default: `{ '@vocab': 'http://www.w3.org/2000/01/rdf-schema#', rdf, rdfs, xsd, sh, prov }`)
199
- - `dataFactory` (object) β€” Custom RDF/JS DataFactory
196
+ **Parameters (named object):**
197
+ - `text` (string, required) β€” MD-LD formatted text
198
+ - `context` (object, optional) β€” Prefix mappings (default: `{ '@vocab': 'http://www.w3.org/2000/01/rdf-schema#', rdf, rdfs, xsd, sh, prov }`)
199
+ - `dataFactory` (object, optional) β€” Custom RDF/JS DataFactory
200
+ - `graph` (string, optional) β€” Named graph IRI
200
201
 
201
202
  **Returns:** `{ quads, remove, statements, origin, context, primarySubject }`
202
203
 
204
+ > **Legacy:** `parse(text, options)` still works for backward compatibility
205
+
203
206
  - `quads` β€” Array of RDF/JS Quads (final resolved graph state)
204
207
  - `remove` β€” Array of RDF/JS Quads (external retractions targeting prior state)
205
208
  - `statements` β€” Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
@@ -224,17 +227,70 @@ Merge multiple MDLD documents with diff polarity resolution.
224
227
  - `context` β€” Final merged context
225
228
  - `primarySubjects` β€” Array of string IRIs (primary subjects from each document, in merge order)
226
229
 
227
- ### `generate(quads, context, primarySubject)`
230
+ ### `generate({ quads, context, primarySubject })`
228
231
 
229
- Generate deterministic MDLD from RDF quads.
232
+ Generate deterministic MDLD from RDF quads with visual styling.
230
233
 
231
- **Parameters:**
232
- - `quads` (array) β€” Array of RDF/JS Quads to convert
234
+ **Parameters (named object):**
235
+ - `quads` (array, required) β€” Array of RDF/JS Quads to convert
236
+ - `context` (object, optional) β€” Prefix mappings (default: `{}`)
237
+ - `primarySubject` (string, optional) β€” String IRI to place first in output (ensures round-trip safety). If not provided, falls back to the first subject from quads.
238
+
239
+ **Returns:** `{ text, context }`
240
+
241
+ **Features:**
242
+ - Visual carrier styles based on datatype (code spans for numbers, bold booleans, etc.)
243
+ - Label-in-heading: Uses `rdfs:label` in subject headings when available
244
+ - Multiple labels: First label in heading, additional labels rendered as literals
245
+ - Round-trip safe: All data preserved through parse β†’ generate β†’ parse
246
+ - Composable: `generate(parse(text))` extracts semantics; `parse(generate({quads}))` normalizes quads
247
+
248
+ ### `generateNode({ quads, focusIRI, context })`
249
+
250
+ Generate node-centric MDLD showing all quads where a specific IRI appears in any position.
251
+
252
+ **Parameters (named object):**
253
+ - `quads` (array, required) β€” Array of RDF/JS Quads to search
254
+ - `focusIRI` (string, required) β€” The IRI to center the view on
233
255
  - `context` (object, optional) β€” Prefix mappings (default: `{}`)
234
- - `primarySubject` (string, optional) β€” String IRI to place first in output (ensures round-trip safety)
235
256
 
236
257
  **Returns:** `{ text, context }`
237
258
 
259
+ **Behavior (Safety-First):**
260
+ - If `focusIRI` is null/undefined: Returns empty text
261
+ - If `focusIRI` not in graph: Returns empty text (never falls back to all data)
262
+ - If `quads` is empty: Returns empty text
263
+
264
+ **Safety rationale:** Prevents accidental rendering of entire databases on misspelled IRIsβ€”critical for production use with LLM cost per token. Explicit emptiness signals "not found" to the caller.
265
+
266
+ **Use case:** Perfect for exploring a specific node and all its relationshipsβ€”where it appears as subject, object, predicate, type, or datatype. Creates an exhaustive view of everything related to the focus IRI. Ideal for node-centric knowledge graph explorers.
267
+
268
+ ### Composition Patterns
269
+
270
+ With the unified named parameter API, `parse()` and `generate()` compose seamlessly through object spreading:
271
+
272
+ ```javascript
273
+ import { parse, generate, generateNode } from 'mdld-parse';
274
+
275
+ // Pattern 1: parse β†’ generate (semantic extraction)
276
+ const canonical = generate({ ...parse({ text, context }) });
277
+ // text β†’ quads β†’ canonical MDLD (deterministic, visual styling applied)
278
+
279
+ // Pattern 2: generate β†’ parse (normalize external RDF)
280
+ const normalized = parse({ ...generate({ quads: externalQuads, context }) });
281
+ // external quads β†’ MDLD β†’ validated quads (DataFactory-safe, no blank nodes)
282
+
283
+ // Pattern 3: parse β†’ generateNode (node-centric exploration)
284
+ const nodeView = generateNode({ ...parse({ text }), focusIRI: 'http://example.org/alice' });
285
+ // full graph β†’ isolated node view (safe: returns empty if IRI not found)
286
+ ```
287
+
288
+ **Why this works:**
289
+ - `parse()` returns `{ quads, context, primarySubject, ... }`
290
+ - `generate()` accepts `{ quads, context, primarySubject }`
291
+ - `generateNode()` accepts `{ quads, context, focusIRI }` (with focusIRI override)
292
+ - Perfect shape alignment enables elegant `{ ...spread }` composition
293
+
238
294
  ### `locate(quad, origin)`
239
295
 
240
296
  Locate the origin entry for a quad using the lean origin system.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mdld-parse",
3
- "version": "0.8.4",
3
+ "version": "0.9.0",
4
4
  "description": "A standards-compliant parser for **MD-LD (Markdown-Linked Data)** β€” a human-friendly RDF authoring format that extends Markdown with semantic annotations.",
5
5
  "type": "module",
6
6
  "main": "index.js",
package/src/generate.js CHANGED
@@ -37,14 +37,46 @@ export function extractLocalName(iri, ctx = {}) {
37
37
  * Input: RDF quads + context + optional primarySubject (string IRI)
38
38
  * Output: MDLD text
39
39
  */
40
- export function generate(quads, context = {}, primarySubject = null) {
40
+ export function generate({ quads, context = {}, primarySubject = null }) {
41
41
  const fullContext = { ...DEFAULT_CONTEXT, ...context };
42
42
 
43
43
  const normalizedQuads = normalizeAndSortQuads(quads);
44
44
 
45
45
  const subjectGroups = groupQuadsBySubject(normalizedQuads);
46
46
 
47
- const { text } = buildDeterministicMDLD(subjectGroups, fullContext, primarySubject);
47
+ // Fallback: if no primarySubject provided, use first subject from quads
48
+ let effectivePrimary = primarySubject;
49
+ if (!effectivePrimary && normalizedQuads.length > 0) {
50
+ effectivePrimary = normalizedQuads[0].subject.value;
51
+ }
52
+
53
+ const { text } = buildDeterministicMDLD(subjectGroups, fullContext, effectivePrimary);
54
+
55
+ return { text, context: fullContext };
56
+ }
57
+
58
+ /**
59
+ * Generate node-centric MDLD showing all quads where a specific IRI appears
60
+ * in any position: subject, object, predicate, type, or datatype.
61
+ * Perfect for exploring individual nodes and their complete relationship graph.
62
+ */
63
+ export function generateNode({ quads, focusIRI, context = {} }) {
64
+ // Validate: must have quads and a focus IRI
65
+ if (!quads?.length || !focusIRI) {
66
+ return { text: '', context: { ...DEFAULT_CONTEXT, ...context } };
67
+ }
68
+
69
+ const fullContext = { ...DEFAULT_CONTEXT, ...context };
70
+ const normalizedQuads = normalizeAndSortQuads(quads);
71
+ const nodeGroups = groupQuadsByNode(normalizedQuads);
72
+
73
+ // SAFETY: If focusIRI not in graph, return empty - NEVER fall back to all data
74
+ // This prevents accidental rendering of entire databases on misspelled IRIs
75
+ if (!nodeGroups.has(focusIRI)) {
76
+ return { text: '', context: fullContext };
77
+ }
78
+
79
+ const { text } = buildDeterministicMDLD(nodeGroups, fullContext, focusIRI);
48
80
 
49
81
  return { text, context: fullContext };
50
82
  }
@@ -86,6 +118,42 @@ function groupQuadsBySubject(quads) {
86
118
  return groups;
87
119
  }
88
120
 
121
+ function groupQuadsByNode(quads) {
122
+ const groups = new Map();
123
+ const RDFS_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
124
+
125
+ const ensure = (key) => {
126
+ if (!groups.has(key)) groups.set(key, []);
127
+ return groups.get(key);
128
+ };
129
+
130
+ for (const quad of quads) {
131
+ const { subject, predicate, object } = quad;
132
+
133
+ // 1. Subject (direct properties)
134
+ ensure(subject.value).push(quad);
135
+
136
+ // 2. Object (reverse relations - where this IRI is pointed to)
137
+ if (object.termType === 'NamedNode') {
138
+ ensure(object.value).push(quad);
139
+ }
140
+
141
+ // 3. Predicate (where this IRI is used as a property)
142
+ ensure(predicate.value).push(quad);
143
+
144
+ // 4. Type (instances - where this IRI is the class/type)
145
+ if (predicate.value === RDFS_TYPE && object.termType === 'NamedNode') {
146
+ ensure(object.value).push(quad);
147
+ }
148
+
149
+ // 5. Datatype (literals using this as their type)
150
+ if (object.termType === 'Literal' && object.datatype) {
151
+ ensure(object.datatype.value || object.datatype).push(quad);
152
+ }
153
+ }
154
+ return groups;
155
+ }
156
+
89
157
  function buildDeterministicMDLD(subjectGroups, context, primarySubject = null) {
90
158
  let text = '';
91
159
  const usedPrefixes = collectUsedPrefixes(subjectGroups, context);
@@ -117,6 +185,9 @@ function buildDeterministicMDLD(subjectGroups, context, primarySubject = null) {
117
185
 
118
186
  for (const subjectIRI of orderedSubjects) {
119
187
  const subjectQuads = subjectGroups.get(subjectIRI);
188
+ // Skip if subject not found in groups (e.g., primarySubject provided but no quads for it)
189
+ if (!subjectQuads) continue;
190
+
120
191
  const shortSubject = shortenIRI(subjectIRI, context);
121
192
 
122
193
  // Separate types, literals, and objects using shared utility
package/src/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  export { parse } from './parse.js';
2
2
  export { merge } from './merge.js';
3
- export { generate } from './generate.js';
3
+ export { generate, generateNode } from './generate.js';
4
4
  export { locate } from './locate.js';
5
5
  export { render } from './render.js';
6
6
  export { DEFAULT_CONTEXT } from './constants.js';
package/src/merge.js CHANGED
@@ -20,7 +20,8 @@ function quadKey(quad) {
20
20
  */
21
21
  function normalizeInput(input, options, docContext) {
22
22
  if (typeof input === 'string') {
23
- return parse(input, {
23
+ return parse({
24
+ text: input,
24
25
  ...options,
25
26
  context: { ...docContext, ...options.context }
26
27
  });
package/src/parse.js CHANGED
@@ -45,11 +45,19 @@ import {
45
45
  } from './shared.js';
46
46
 
47
47
 
48
- export function parse(text, options = {}) {
48
+ export function parse(firstArg, secondArg = {}) {
49
+ // Dual-mode API: backward compatible with (text, options) and new ({ text, context, ... })
50
+ const isNamedParams = typeof firstArg === 'object' && firstArg !== null && 'text' in firstArg;
51
+
52
+ const text = isNamedParams ? firstArg.text : firstArg;
53
+ const options = isNamedParams
54
+ ? { context: firstArg.context, dataFactory: firstArg.dataFactory, graph: firstArg.graph }
55
+ : secondArg;
56
+
49
57
  const state = {
50
58
  ctx: { ...DEFAULT_CONTEXT, ...(options.context || {}) },
51
59
  df: options.dataFactory || DataFactory,
52
- graph: DataFactory.namedNode(options.graph) || DataFactory.defaultGraph(),
60
+ graph: options.graph ? DataFactory.namedNode(options.graph) : DataFactory.defaultGraph(),
53
61
  quads: [],
54
62
  quadBuffer: new Map(),
55
63
  removeSet: new Set(),
@@ -300,6 +308,9 @@ function createBlockEntry(token, state) {
300
308
  const blockId = token._blockId || hash(`${token.type}:${token.range?.[0]}:${token.range?.[1]}`);
301
309
  token._blockId = blockId; // Store for later reference
302
310
 
311
+ // Extract inline carriers first to enable clean text extraction
312
+ const carriers = getCarriers(token);
313
+
303
314
  const cleanText = extractCleanText(token);
304
315
 
305
316
  const blockEntry = {
@@ -316,6 +327,29 @@ function createBlockEntry(token, state) {
316
327
  quadKeys: [] // Will be populated during quad emission
317
328
  };
318
329
 
330
+ // Process carriers and add to block
331
+ for (const carrier of carriers) {
332
+ const carrierInfo = {
333
+ type: carrier.type,
334
+ range: carrier.range,
335
+ text: carrier.text,
336
+ subject: null,
337
+ predicates: [],
338
+ sem: null
339
+ };
340
+
341
+ // Extract carrier-specific semantics
342
+ if (carrier.attrs) {
343
+ const carrierSem = parseSemCached(carrier.attrs);
344
+ carrierInfo.sem = carrierSem; // Store full semantics
345
+ carrierInfo.predicates = carrierSem.predicates || [];
346
+ carrierInfo.subject = carrierSem.subject;
347
+ carrierInfo.types = carrierSem.types || [];
348
+ }
349
+
350
+ blockEntry.carriers.push(carrierInfo);
351
+ }
352
+
319
353
  // Store block and add to document structure
320
354
  state.origin.blocks.set(blockId, blockEntry);
321
355
  state.origin.documentStructure.push(blockEntry);
@@ -368,9 +402,10 @@ function enrichBlockFromAnnotation(blockEntry, sem, carrier, state) {
368
402
  // Extract carrier-specific semantics
369
403
  if (carrier.attrs) {
370
404
  const carrierSem = parseSemCached(carrier.attrs);
371
- if (carrierSem.types) {
372
- carrierInfo.predicates = carrierSem.predicates || [];
373
- }
405
+ carrierInfo.sem = carrierSem; // Store full semantics
406
+ carrierInfo.predicates = carrierSem.predicates || [];
407
+ carrierInfo.subject = carrierSem.subject;
408
+ carrierInfo.types = carrierSem.types || [];
374
409
  }
375
410
 
376
411
  blockEntry.carriers.push(carrierInfo);
package/src/render.js CHANGED
@@ -19,15 +19,15 @@ import { DEFAULT_CONTEXT } from './constants.js';
19
19
  * @param {Object} options - Rendering options
20
20
  * @param {Object} options.context - Additional context prefixes
21
21
  * @param {string} options.baseIRI - Base IRI for relative URLs
22
- * @param {boolean} options.validate - Enable validation
22
+ * @param {boolean} options.strict - Enable strict quad-RDFa correspondence checking
23
23
  * @param {boolean} options.pretty - Pretty print output
24
- * @returns {Object} Render result with HTML and metadata
24
+ * @returns {Object} Render result with HTML, metadata, and optional quad mapping
25
25
  */
26
26
  export function render(mdld, options = {}) {
27
27
  // Phase 1: Parse MD-LD (reuse parser)
28
- const parsed = parse(mdld, { context: options.context || {} });
28
+ const parsed = parse({ text: mdld, context: options.context || {} });
29
29
 
30
- // Phase 2: Build render state
30
+ // Phase 2: Build render state (includes quads for validation)
31
31
  const state = buildRenderState(parsed, options, mdld);
32
32
 
33
33
  // Phase 3: Render blocks to HTML
@@ -36,15 +36,27 @@ export function render(mdld, options = {}) {
36
36
  // Phase 4: Wrap with RDFa context
37
37
  const wrapped = wrapWithRDFaContext(html, state.ctx);
38
38
 
39
- return {
39
+ const result = {
40
40
  html: wrapped,
41
41
  context: state.ctx,
42
42
  metadata: {
43
43
  blockCount: parsed.origin.blocks.size,
44
44
  quadCount: parsed.quads.length,
45
+ renderedRDFaCount: state.renderedRDFaCount || 0,
45
46
  renderTime: Date.now()
46
47
  }
47
48
  };
49
+
50
+ // Add quad mapping if requested
51
+ if (options.strict) {
52
+ result.quadMap = state.quadMap || [];
53
+ result.validation = {
54
+ allQuadsRendered: (state.quadMap || []).length === parsed.quads.length,
55
+ orphanedQuads: identifyOrphanedQuads(parsed.quads, state.quadMap || [])
56
+ };
57
+ }
58
+
59
+ return result;
48
60
  }
49
61
 
50
62
  /**
@@ -63,10 +75,39 @@ function buildRenderState(parsed, options, mdld) {
63
75
  currentSubject: null,
64
76
  documentSubject: null,
65
77
  blockStack: [],
66
- carrierStack: []
78
+ carrierStack: [],
79
+ // Quad tracking for 1-1 correspondence
80
+ quads: parsed.quads,
81
+ quadMap: options.strict ? [] : null, // Maps rendered RDFa to quads
82
+ renderedRDFaCount: 0,
83
+ strict: options.strict || false
67
84
  };
68
85
  }
69
86
 
87
+ /**
88
+ * Helper: Check if a quad exists in the quads array
89
+ */
90
+ function quadExists(quads, subject, predicate, object) {
91
+ return quads.some(q =>
92
+ q.subject.equals(subject) &&
93
+ q.predicate.equals(predicate) &&
94
+ q.object.equals(object)
95
+ );
96
+ }
97
+
98
+ /**
99
+ * Helper: Identify quads that weren't rendered
100
+ */
101
+ function identifyOrphanedQuads(allQuads, renderedQuads) {
102
+ const renderedKeys = new Set(renderedQuads.map(qm =>
103
+ `${qm.subject.value}|${qm.predicate.value}|${qm.object.value}`
104
+ ));
105
+
106
+ return allQuads.filter(q =>
107
+ !renderedKeys.has(`${q.subject.value}|${q.predicate.value}|${q.object.value}`)
108
+ );
109
+ }
110
+
70
111
  /**
71
112
  * Render blocks to HTML with RDFa annotations
72
113
  */
@@ -311,6 +352,11 @@ function parseMarkdownList(markdownList, blocks, state) {
311
352
  * Render a single block
312
353
  */
313
354
  function renderBlock(block, state) {
355
+ // Update current subject context
356
+ if (block.subject && block.subject !== 'RESET') {
357
+ state.currentSubject = block.subject;
358
+ }
359
+
314
360
  const attrs = buildRDFaAttrsFromBlock(block, state.ctx);
315
361
 
316
362
  switch (block.type || block.carrierType) {
@@ -354,29 +400,234 @@ function renderBlock(block, state) {
354
400
  }
355
401
 
356
402
  /**
357
- * Render block content with inline carriers
403
+ * Render block content with inline carriers using position-based lookup
358
404
  */
359
405
  function renderBlockContent(block, state) {
360
- // Extract text from source using range information
361
- if (block.range && state.sourceText) {
362
- let text = state.sourceText.substring(block.range.start, block.range.end);
363
-
364
- // Remove semantic block annotations from the text
365
- if (block.attrsRange) {
366
- const beforeAttrs = text.substring(0, block.attrsRange.start - block.range.start);
367
- const afterAttrs = text.substring(block.attrsRange.end - block.range.start);
368
- text = beforeAttrs + afterAttrs;
406
+ if (!block.text || !block.carriers || block.carriers.length === 0) {
407
+ state.output.push(escapeHtml(block.text || ''));
408
+ return;
409
+ }
410
+
411
+ // Build position map: for each carrier, find where it appears in cleaned text
412
+ const carrierMap = buildCarrierPositionMap(block.text, block.carriers);
413
+
414
+ // Render text with carriers inserted at correct positions
415
+ const html = renderTextWithCarriers(block.text, carrierMap, state);
416
+ state.output.push(html);
417
+ }
418
+
419
+ /**
420
+ * Build a map of carrier positions in the cleaned text
421
+ * Returns array of {pos, carrier} sorted by position
422
+ */
423
+ function buildCarrierPositionMap(cleanedText, carriers) {
424
+ const positionMap = [];
425
+
426
+ for (const carrier of carriers) {
427
+ if (!carrier.text) continue;
428
+
429
+ // Find where this carrier text appears in the cleaned text
430
+ let searchPos = 0;
431
+ let foundPos = cleanedText.indexOf(carrier.text, searchPos);
432
+
433
+ // If found, record this position
434
+ if (foundPos !== -1) {
435
+ // Check if we already have this position (avoid duplicates)
436
+ const exists = positionMap.some(m => m.pos === foundPos && m.carrier === carrier);
437
+ if (!exists) {
438
+ positionMap.push({
439
+ pos: foundPos,
440
+ carrier: carrier,
441
+ length: carrier.text.length
442
+ });
443
+ }
369
444
  }
445
+ }
370
446
 
371
- // For headings, extract text content from the heading
372
- if (block.carrierType === 'heading') {
373
- // Remove heading markers (#) and trim
374
- const content = text.replace(/^#+\s*/, '').trim();
375
- state.output.push(escapeHtml(content));
376
- } else {
377
- state.output.push(escapeHtml(text.trim()));
447
+ // Sort by position to process in order
448
+ return positionMap.sort((a, b) => a.pos - b.pos);
449
+ }
450
+
451
+ /**
452
+ * Render text with carriers inserted at mapped positions
453
+ */
454
+ function renderTextWithCarriers(text, carrierMap, state) {
455
+ if (carrierMap.length === 0) {
456
+ return escapeHtml(text);
457
+ }
458
+
459
+ let html = '';
460
+ let pos = 0;
461
+
462
+ for (const mapping of carrierMap) {
463
+ // Add text before carrier
464
+ if (mapping.pos > pos) {
465
+ html += escapeHtml(text.substring(pos, mapping.pos));
378
466
  }
467
+
468
+ // Render carrier with RDFa
469
+ html += renderCarrier(mapping.carrier, state);
470
+
471
+ // Move position past carrier
472
+ pos = mapping.pos + mapping.length;
473
+ }
474
+
475
+ // Add remaining text
476
+ if (pos < text.length) {
477
+ html += escapeHtml(text.substring(pos));
379
478
  }
479
+
480
+ return html;
481
+ }
482
+
483
+ /**
484
+ * Parse inline markdown using carrier positions instead of regex
485
+ * This is more reliable since we have exact position data from parsing
486
+ */
487
+ function parseInlineMarkdown(text, carriers, blockRange, state) {
488
+ if (carriers.length === 0) {
489
+ return escapeHtml(text);
490
+ }
491
+
492
+ let html = '';
493
+ let pos = 0;
494
+
495
+ // Sort carriers by their position in the cleaned text
496
+ // Need to map from source range to cleaned text position
497
+ const sortedCarriers = carriers
498
+ .map(carrier => ({
499
+ ...carrier,
500
+ cleanedStart: estimateCleanedPosition(carrier, blockRange)
501
+ }))
502
+ .filter(c => c.cleanedStart !== -1)
503
+ .sort((a, b) => a.cleanedStart - b.cleanedStart);
504
+
505
+ for (const carrier of sortedCarriers) {
506
+ const start = carrier.cleanedStart;
507
+ const end = start + carrier.text.length;
508
+
509
+ // Add text before the carrier
510
+ if (start > pos) {
511
+ html += escapeHtml(text.substring(pos, start));
512
+ }
513
+
514
+ // Render the carrier with RDFa
515
+ html += renderCarrier(carrier, state);
516
+
517
+ pos = end;
518
+ }
519
+
520
+ // Add remaining text
521
+ if (pos < text.length) {
522
+ html += escapeHtml(text.substring(pos));
523
+ }
524
+
525
+ return html;
526
+ }
527
+
528
+ /**
529
+ * Estimate where a carrier appears in the cleaned text
530
+ * This is approximate but avoids complex offset tracking
531
+ */
532
+ function estimateCleanedPosition(carrier, blockRange) {
533
+ // For now, assume carrier.text is still searchable in the cleaned output
534
+ // This works because we preserve word content, just remove annotations
535
+ // A more robust version would track offsets during text cleaning
536
+ if (!carrier.text) return -1;
537
+ return carrier.cleanedStart !== undefined ? carrier.cleanedStart : -1;
538
+ }
539
+
540
+ /**
541
+ * Render a single carrier with RDFa and markdown formatting
542
+ */
543
+ function renderCarrier(carrier, state) {
544
+ const rdfaAttrs = buildRDFaAttrsFromCarrier(carrier, null, state);
545
+
546
+ // Render based on carrier type
547
+ switch (carrier.type) {
548
+ case 'emphasis':
549
+ return `<em${rdfaAttrs}>${escapeHtml(carrier.text)}</em>`;
550
+ case 'strong':
551
+ return `<strong${rdfaAttrs}>${escapeHtml(carrier.text)}</strong>`;
552
+ case 'code':
553
+ return `<code${rdfaAttrs}>${escapeHtml(carrier.text)}</code>`;
554
+ case 'link':
555
+ return `<a href="${escapeHtml(carrier.url || '')}"${rdfaAttrs}>${escapeHtml(carrier.text)}</a>`;
556
+ default:
557
+ return escapeHtml(carrier.text);
558
+ }
559
+ }
560
+
561
+ /**
562
+ * Build RDFa attributes from carrier with optional quad validation
563
+ */
564
+ function buildRDFaAttrsFromCarrier(carrier, state) {
565
+ const attrs = [];
566
+ const trackableQuads = [];
567
+
568
+ // Resolve subject for the carrier
569
+ let subject = carrier.subject || state.currentSubject;
570
+
571
+ // No subject = no RDFa (dangling annotation)
572
+ if (!subject || subject === 'RESET' || subject.startsWith('=#') || subject.startsWith('+')) {
573
+ return '';
574
+ }
575
+
576
+ // Subject is valid, add about attribute
577
+ const expanded = expandIRI(subject, state.ctx);
578
+ const subjectNode = state.df.namedNode(expanded);
579
+ const shortened = shortenIRI(expanded, state.ctx);
580
+ attrs.push(`about="${escapeHtml(shortened)}"`);
581
+
582
+ // Types
583
+ if (carrier.types && carrier.types.length > 0) {
584
+ const types = carrier.types.map(t => {
585
+ const iri = typeof t === 'string' ? t : t.iri;
586
+ const expanded = expandIRI(iri, state.ctx);
587
+ const typeNode = state.df.namedNode(expanded);
588
+
589
+ // Track type quads in strict mode
590
+ if (state.strict && state.quads) {
591
+ const rdfType = state.df.namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type');
592
+ if (quadExists(state.quads, subjectNode, rdfType, typeNode)) {
593
+ trackableQuads.push({ subject: subjectNode, predicate: rdfType, object: typeNode });
594
+ }
595
+ }
596
+
597
+ return shortenIRI(expanded, state.ctx);
598
+ }).join(' ');
599
+ attrs.push(`typeof="${escapeHtml(types)}"`);
600
+ }
601
+
602
+ // Predicates
603
+ if (carrier.predicates && carrier.predicates.length > 0) {
604
+ const { literalProps, objectProps, reverseProps } = processPredicates(carrier.predicates, state.ctx);
605
+
606
+ if (literalProps.length > 0) {
607
+ // Track literal property quads
608
+ if (state.strict && state.quads && carrier.text) {
609
+ literalProps.forEach(prop => {
610
+ const predNode = state.df.namedNode(expandIRI(prop, state.ctx));
611
+ const objNode = state.df.literal(carrier.text);
612
+ });
613
+ }
614
+ attrs.push(`property="${escapeHtml(literalProps.join(' '))}"`);
615
+ }
616
+ if (objectProps.length > 0) {
617
+ attrs.push(`rel="${escapeHtml(objectProps.join(' '))}"`);
618
+ }
619
+ if (reverseProps.length > 0) {
620
+ attrs.push(`rev="${escapeHtml(reverseProps.join(' '))}"`);
621
+ }
622
+ }
623
+
624
+ // Track rendered RDFa in strict mode
625
+ if (state.strict && trackableQuads.length > 0) {
626
+ state.quadMap.push(...trackableQuads);
627
+ state.renderedRDFaCount += trackableQuads.length;
628
+ }
629
+
630
+ return attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
380
631
  }
381
632
 
382
633
  /**
package/src/shared.js CHANGED
@@ -213,7 +213,7 @@ export function calcCarrierRanges(match, baseOffset, matchStart) {
213
213
  const attrsEnd = attrsStart + match[2].length + 2; // +2 for { and }
214
214
  return {
215
215
  valueRange: [valueStart, valueEnd],
216
- attrsRange: [attrsStart + 1, attrsEnd - 1], // Exclude braces
216
+ attrsRange: [attrsStart, attrsEnd], // Include braces
217
217
  range: [baseOffset + matchStart, attrsEnd],
218
218
  pos: matchStart + match[0].length // pos should be relative to current text, not document
219
219
  };
@@ -225,13 +225,27 @@ export function extractCleanText(token) {
225
225
 
226
226
  let text = token.text;
227
227
 
228
- // Remove semantic annotations
228
+ // Remove block-level semantic annotations
229
229
  if (token.attrsRange) {
230
230
  const beforeAttrs = text.substring(0, token.attrsRange[0] - (token.range?.[0] || 0));
231
231
  const afterAttrs = text.substring(token.attrsRange[1] - (token.range?.[0] || 0));
232
232
  text = beforeAttrs + afterAttrs;
233
233
  }
234
234
 
235
+ // Remove inline carrier annotations
236
+ const carriers = token._carriers || [];
237
+ const inlineRanges = carriers
238
+ .filter(carrier => carrier.attrsRange)
239
+ .map(carrier => carrier.attrsRange.map(pos => pos - (token.range?.[0] || 0)))
240
+ .filter(([start, end]) => start >= 0 && end <= text.length)
241
+ .sort((a, b) => b[0] - a[0]);
242
+
243
+ for (const [relativeStart, relativeEnd] of inlineRanges) {
244
+ const before = text.substring(0, relativeStart);
245
+ const after = text.substring(relativeEnd);
246
+ text = before + after;
247
+ }
248
+
235
249
  // Clean based on token type
236
250
  switch (token.type) {
237
251
  case 'heading':