mdld-parse 0.9.8 → 1.0.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.
Files changed (55) hide show
  1. package/README.md +243 -262
  2. package/dist/index.js +1797 -1324
  3. package/package.json +5 -5
  4. package/dist/.nojekyll +0 -0
  5. package/dist/CNAME +0 -1
  6. package/dist/README.md +0 -431
  7. package/dist/docs/API.md +0 -435
  8. package/dist/docs/Architecture.md +0 -190
  9. package/dist/docs/Guide.md +0 -816
  10. package/dist/docs/LLM-MDLD-Inducer.md +0 -550
  11. package/dist/docs/LiterateRDF.md +0 -472
  12. package/dist/docs/Parser.md +0 -720
  13. package/dist/docs/Performance.md +0 -238
  14. package/dist/docs/Spec-render.md +0 -1439
  15. package/dist/docs/Subject.md +0 -180
  16. package/dist/docs/Syntax.md +0 -463
  17. package/dist/docs/TodoList.md +0 -215
  18. package/dist/docs/Use-Cases.md +0 -354
  19. package/dist/docs/guide-m.md +0 -56
  20. package/dist/docs/index.html +0 -108
  21. package/dist/docs/index.md +0 -56
  22. package/dist/docs/one-page.md +0 -322
  23. package/dist/docs/origin.md +0 -459
  24. package/dist/docs/polarity.md +0 -586
  25. package/dist/docs/primary-subject.md +0 -326
  26. package/dist/docs/statements.md +0 -226
  27. package/dist/docs/tokenization-performance-report.md +0 -164
  28. package/dist/examples/Cookbook.md +0 -32
  29. package/dist/examples/Status-SHACL.md +0 -31
  30. package/dist/examples/demo/index.md +0 -35
  31. package/dist/examples/demo/journal.md +0 -60
  32. package/dist/examples/demo/minimal.md +0 -23
  33. package/dist/examples/demo/project.md +0 -84
  34. package/dist/examples/demo/prov.md +0 -107
  35. package/dist/examples/demo/rdf.md +0 -69
  36. package/dist/examples/demo/recipe.md +0 -50
  37. package/dist/examples/demo/research.md +0 -84
  38. package/dist/examples/demo/shacl.md +0 -161
  39. package/dist/examples/demo/space-mission.md +0 -58
  40. package/dist/examples/demo/tasks.md +0 -175
  41. package/dist/examples/demo/xsd.md +0 -91
  42. package/dist/examples/dogfood.md +0 -288
  43. package/dist/examples/few-shot.md +0 -309
  44. package/dist/examples/graph/rdf-graph.html +0 -473
  45. package/dist/examples/graph/rdf_force_graph_web_component.html +0 -506
  46. package/dist/examples/index.md +0 -45
  47. package/dist/examples/llm-time-workflow.md +0 -173
  48. package/dist/examples/statements.md +0 -43
  49. package/dist/examples/workflow.md +0 -150
  50. package/dist/index.html +0 -3023
  51. package/dist/logo.svg +0 -7
  52. package/dist/spec/Spec-compact.md +0 -368
  53. package/dist/spec/Spec-ultra.md +0 -232
  54. package/dist/spec/Spec.md +0 -1116
  55. package/dist/spec/index.md +0 -46
package/README.md CHANGED
@@ -1,10 +1,39 @@
1
1
  # MD-LD
2
2
 
3
- **Markdown-Linked Data (MD-LD)** — a deterministic, streaming-friendly RDF authoring format that extends Markdown with explicit `{...}` annotations.
3
+ **Markdown-Linked Data** — Human-friendly knowledge graph authoring.
4
+
5
+ Write semantic data in natural Markdown, parse to RDF quads, build deterministic state machines.
4
6
 
5
7
  [![NPM](https://img.shields.io/npm/v/mdld-parse)](https://www.npmjs.com/package/mdld-parse)
6
8
 
7
- [Demo](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
9
+ [Demo](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
10
+
11
+ ## 🎯 What is MD-LD?
12
+
13
+ MD-LD is not just another RDF syntax. It's a **universal semantic writing interface** that removes the intermediary between human text and machine-readable graphs.
14
+
15
+ Traditional systems require:
16
+ ```
17
+ Human → UI → App Logic → Hidden Database → APIs → Exports
18
+ ```
19
+
20
+ MD-LD enables:
21
+ ```
22
+ Human text → Graph immediately
23
+ ```
24
+
25
+ **Core value:** Author and maintain knowledge graphs as plain text with deterministic round-trip safety. No platforms, databases, or proprietary SaaS mediation required.
26
+
27
+ ```markdown
28
+ [ex] <http://example.org/>
29
+
30
+ # Document {=ex:doc .Article label}
31
+
32
+ [Alice] {=ex:alice ?ex:author .prov:Person ex:firstName label}
33
+ [Smith] {ex:lastName}
34
+ ```
35
+
36
+ **Generates RDF quads** that work with n3.js, rdflib, and any RDF/JS-compatible library.
8
37
 
9
38
  ## 🚀 Quick Start
10
39
 
@@ -13,66 +42,106 @@ pnpm install mdld-parse
13
42
  ```
14
43
 
15
44
  ```javascript
16
- import { parse } from 'mdld-parse';
45
+ import { parse, generate, merge } from 'mdld-parse';
17
46
 
18
- const result = parse(`
19
- [ex] <http://example.org/>
47
+ // Parse MDLD to RDF quads
48
+ const result = parse({ text: mdldString });
49
+ console.log(result.quads); // RDF/JS quads
50
+ console.log(result.primary); // Primary metadata (subject, type, label, comment)
51
+ console.log(result.statements); // Elevated statements
52
+ console.log(result.origin); // Provenance tracking
53
+
54
+ // Generate MDLD from quads
55
+ const { text } = generate({ quads: result.quads });
20
56
 
21
- # Document {=ex:doc .ex:Article label}
22
-
23
- [Alice] {?ex:author =ex:alice .prov:Person ex:firstName label}
24
- [Smith] {ex:lastName}`);
25
-
26
- console.log(result.quads);
27
- // RDF/JS quads ready for n3.js, rdflib, etc.
28
- // @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
29
- // @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
30
- // @prefix prov: <http://www.w3.org/ns/prov#>.
31
- // @prefix ex: <http://example.org/>.
32
-
33
- // ex:doc a ex:Article;
34
- // rdfs:label "Document";
35
- // ex:author ex:alice.
36
- // ex:alice a prov:Person;
37
- // rdfs:label "Alice";
38
- // ex:firstName "Alice";
39
- // ex:lastName "Smith".
57
+ // Merge multiple documents (CRDT-style)
58
+ const merged = merge([doc1, doc2, doc3]);
40
59
  ```
41
60
 
42
- ## 📚 Documentation Hub
61
+ ## 💡 Why MD-LD?
43
62
 
44
- - **📖 [Documentation](./docs/index.md)** - Complete documentation with guides and references
45
- - **🎯 [Examples](./examples/index.md)** - Real-world MD-LD examples and use cases
46
- - **📋 [Specification](./spec/index.md)** - Formal specification and test suite
63
+ ### The Problem with Current Systems
47
64
 
48
- ## ✨ Core Features
65
+ Most software today uses graphs internally but hides them behind UIs:
66
+ - **Notion, Slack, Google Docs** — Human interfaces over hidden graphs
67
+ - **CRMs, task apps, note apps** — Proprietary data silos
68
+ - **Social networks** — Platform-controlled knowledge prisons
69
+
70
+ Users cannot access the graph directly. Semantics are hidden. Data is locked in products.
71
+
72
+ ### The MD-LD Solution
73
+
74
+ MD-LD removes the intermediary. Writing becomes publishing. Publishing becomes graph construction.
75
+
76
+ **Key benefits:**
77
+ - **Graph sovereignty** — You own text, graph, provenance, execution, history
78
+ - **No central platform required** — Works offline, in browsers, on servers
79
+ - **Universal semantic substrate** — Agents can read, reason, write, execute, validate
80
+ - **Continuous semantic narrative** — Unifies chat, tasks, notes, emails, calendar, files
81
+ - **Native time dimension** — Every action, statement, correction becomes part of the graph
82
+ - **Decentralized authority** — RFC 4151 tag: URIs enable self-sovereign identity without central registries
49
83
 
50
- - **🔗 Prefix folding** - Build hierarchical namespaces with lightweight IRI authoring
51
- - **📍 Subject declarations** - `{=IRI}` and `{=#fragment}` for context setting
52
- - **🎯 Object IRIs** - `{+IRI}` and `{+#fragment}` for temporary object declarations
53
- - **🔄 Three predicate forms** - `p` (S→L), `?p` (S→O), `!p` (O→S)
54
- - **🏷️ Type declarations** - `.Class` for rdf:type triples
55
- - **📅 Datatypes & language** - `^^xsd:date` and `@en` support
56
- - **🧩 Fragments** - Document structuring with `{=#fragment}`
57
- - **⚡ Polarity system** - Sophisticated diff authoring with `+` and `-` prefixes
58
- - **📍 Origin tracking** - Complete provenance with lean quad-to-source mapping
59
- - **🎯 Elevated statements** - Automatic rdf:Statement pattern detection for "golden" graph extraction
60
- - **🏷️ Primary metadata** - Structured primary object with subject, type, and label for document identity
84
+ ### Real-World Applications
61
85
 
62
- ## 🌟 What is MD-LD?
86
+ #### Personal Knowledge Management
87
+ ```markdown
88
+ [alice] <tag:alice@example.com,2026:>
89
+
90
+ # Meeting Notes {=alice:meeting-2024-01-15 .alice:Meeting}
63
91
 
64
- MD-LD allows you to author RDF graphs directly in Markdown using explicit `{...}` annotations:
92
+ Attendees:
93
+ - **Alice** {+alice:alice ?alice:attendee label}
94
+ - **Bob** {+alice:bob ?alice:attendee label}
95
+
96
+ Action items:
97
+ - **Review proposal** {+alice:task-1 ?alice:actionItem label}
98
+ ```
65
99
 
100
+ #### Developer Documentation
66
101
  ```markdown
67
- [my] <tag:alice@example.com,2026:>
68
- # 2024-07-18 {=my:journal-2024-07-18 .my:Event my:date ^^xsd:date}
69
- ## A good day {label}
70
- Mood: [Happy] {my:mood}
71
- Energy level: [8] {my:energyLevel ^^xsd:integer}
72
- Met [Sam] {+my:sam .my:Person ?my:attendee} on my regular walk at [Central Park] {+my:central-park ?my:location .my:Place label @en} and talked about [Sunny] {my:weather} weather.
102
+ # API Endpoint {=api:/users/:id .api:Endpoint}
103
+
104
+ [GET] {api:method}
105
+ [/users/:id] {api:path}
73
106
  ```
74
107
 
75
- Generates valid RDF triples with complete provenance tracking.
108
+ #### Academic Research
109
+ ```markdown
110
+ # Paper {=alice:paper-semantic-markdown .alice:ScholarlyArticle}
111
+
112
+ [Semantic Web] {label}
113
+ [Alice Johnson] {=alice:alice-johnson ?alice:author}
114
+ [2024-01] {alice:datePublished ^^xsd:gYear}
115
+ ```
116
+
117
+ #### Content Management
118
+ ```markdown
119
+ # Understanding MD-LD {=blog:post-mdld .blog:Post}
120
+
121
+ [MD-LD] {blog:emphasized label} allows you to embed RDF directly in Markdown.
122
+ ```
123
+
124
+ ## 📚 Documentation Hub
125
+
126
+ - **📖 [Documentation](./docs/index.md)** — Complete documentation with guides and references
127
+ - **🎯 [Examples](./examples/index.md)** — Real-world MD-LD examples and use cases
128
+ - **📋 [Specification](./spec/index.md)** — Formal specification and test suite
129
+ - **🔄 [Diff Generation](./docs/diff.md)** — Automatic diff document generation for CRDT workflows
130
+
131
+ ## ✨ Core Features
132
+
133
+ - **🔗 Prefix folding** — Build hierarchical namespaces with CURIE-based IRI authoring
134
+ - **📍 Subject declarations** — `{=IRI}` and `{=#fragment}` for context setting
135
+ - **🎯 Object IRIs** — `{+IRI}` and `{+#fragment}` for temporary object declarations
136
+ - **🔄 Three predicate forms** — `p` (S→L), `?p` (S→O), `!p` (O→S)
137
+ - **🏷️ Type declarations** — `.Class` for rdf:type triples
138
+ - **📅 Datatypes & language** — `^^xsd:date` and `@en` support
139
+ - **🧩 Fragments** — Document structuring with `{=#fragment}`
140
+ - **⚡ Polarity system** — Sophisticated diff authoring with `+` and `-` prefixes
141
+ - **📍 Origin tracking** — Complete provenance with lean quad-to-source mapping
142
+ - **🎯 Elevated statements** — Automatic rdf:Statement pattern detection
143
+ - **🏷️ Primary metadata quartet** — Subject, type, label, comment for document identity
144
+ - **🔄 Round-trip safety** — Deterministic parse ↔ generate cycles
76
145
 
77
146
  ## 📦 Installation
78
147
 
@@ -83,20 +152,19 @@ pnpm install mdld-parse
83
152
  ```
84
153
 
85
154
  ```javascript
86
- import { parse } from 'mdld-parse';
87
-
88
- const markdown = `[ex] <tag:alice@example.org,2026:>
155
+ import { parse, generate, merge } from 'mdld-parse';
89
156
 
90
- # Demo document {=ex:example/doc .prov:Entity label}
157
+ const mdld = `[ex] <http://example.org/>
91
158
 
92
- > A demo document for MD-LD {comment}
93
- [Alice] {+ex:alice ?ex:author .prov:Person label}
94
- `;
159
+ # Document {=ex:doc .Article label}
95
160
 
96
- const result = parse({ text: markdown });
161
+ [Alice] {=ex:alice ?ex:author .prov:Person ex:firstName label}
162
+ [Smith] {ex:lastName}`;
97
163
 
98
- console.log(result.quads);
99
- // RDF/JS quads ready for n3.js, rdflib, etc.
164
+ const result = parse({ text: mdld });
165
+ console.log(result.quads); // RDF/JS quads
166
+ console.log(result.primary); // { subject, type, label, comment }
167
+ console.log(result.statements); // Elevated statements
100
168
  ```
101
169
 
102
170
  ### Browser (ES Modules)
@@ -104,11 +172,12 @@ console.log(result.quads);
104
172
  ```html
105
173
  <script type="module">
106
174
  import { parse } from 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
107
-
108
- const result = parse('[ex] <tag:alice@example.org,2026:>\n\n# Hello {=ex:hello label}');
175
+ const result = parse('[ex] <http://example.org/>\n\n# Hello {=ex:hello label}');
109
176
  </script>
110
177
  ```
111
178
 
179
+ **Bundle size:** 84KB unminified, 19KB gzipped
180
+
112
181
  ## 🧠 Semantic Model
113
182
 
114
183
  MD-LD encodes a directed labeled multigraph where three nodes may be in scope:
@@ -117,7 +186,7 @@ MD-LD encodes a directed labeled multigraph where three nodes may be in scope:
117
186
  - **O** — object resource (IRI from link/image)
118
187
  - **L** — literal value (string + optional datatype/language)
119
188
 
120
- ### Predicate Routing (§8.1)
189
+ ### Predicate Routing
121
190
 
122
191
  Each predicate form determines the graph edge:
123
192
 
@@ -127,23 +196,6 @@ Each predicate form determines the graph edge:
127
196
  | `?p` | S → O | `[NASA] {=ex:nasa ?org}` | object property |
128
197
  | `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
129
198
 
130
- ## 📍 Elevated Statements
131
-
132
- MD-LD automatically detects `rdf:Statement` patterns during parsing and extracts elevated SPO quads for convenient consumption by applications.
133
-
134
- ### Pattern Detection
135
-
136
- When the parser encounters a complete `rdf:Statement` pattern with `rdf:subject`, `rdf:predicate`, and `rdf:object`, it automatically adds the corresponding SPO quad to the `statements` array:
137
-
138
- ```markdown
139
- [ex] <http://example.org/>
140
-
141
- ## Elevated statement {=ex:stmt1 .rdf:Statement}
142
- **Alice** {+ex:alice ?rdf:subject} *knows* {+ex:knows ?rdf:predicate} **Bob** {+ex:bob ?rdf:object}
143
-
144
- Direct statement:**Alice** {=ex:alice} knows **Bob** {?ex:knows +ex:bob}
145
- ```
146
-
147
199
  ## 🎨 Syntax Quick Reference
148
200
 
149
201
  ### Subject Declaration
@@ -152,19 +204,10 @@ Set current subject (emits no quads):
152
204
  ## Apollo 11 {=ex:apollo11}
153
205
  ```
154
206
 
155
- ### Fragment Syntax
156
- Create fragment IRIs relative to current subject:
157
- ```markdown
158
- # Document {=ex:document}
159
- {=#summary}
160
- [Content] {label}
161
- ```
162
- Fragments replace any existing fragment and require a current subject.
163
-
164
207
  ### Type Declaration
165
208
  Emit `rdf:type` triple:
166
209
  ```markdown
167
- ## Apollo 11 {=ex:apollo11 .ex:SpaceMission .ex:Event}
210
+ ## Apollo 11 {=ex:apollo11 .SpaceMission .Event}
168
211
  ```
169
212
 
170
213
  ### Literal Properties
@@ -184,50 +227,47 @@ Links create relationships (use `?` prefix):
184
227
  ```
185
228
 
186
229
  ### Resource Declaration
187
- Declare resources inline with `{=iri}`:
230
+ Declare resources inline with `{+iri}`:
188
231
  ```markdown
189
232
  # Mission {=ex:apollo11}
190
- [Neil Armstrong] {=ex:armstrong ?ex:commander .prov:Person}
233
+ [Neil Armstrong] {+ex:armstrong ?ex:commander .Person}
234
+ ```
235
+
236
+ ### Diff Authoring (Polarity)
237
+ Use `+` and `-` for retractions:
238
+ ```markdown
239
+ # Update value
240
+ [Person] {=ex:person}
241
+ [Alice] {-ex:name}
242
+ [Bob] {ex:name}
243
+
244
+ # Remove triple
245
+ [Person] {=ex:person}
246
+ [Alice] {-ex:friend}
191
247
  ```
192
248
 
193
249
  ## 🔧 API Reference
194
250
 
195
251
  ### `parse({ text, context, dataFactory, graph })`
196
252
 
197
- Parse MD-LD markdown and return RDF quads with lean origin tracking.
253
+ Parse MDLD to RDF quads with lean origin tracking.
198
254
 
199
- **Parameters (named object):**
200
- - `text` (string, required) — MD-LD formatted text
201
- - `context` (object, optional) — Prefix mappings (default: `{ '@vocab': 'http://www.w3.org/2000/01/rdf-schema#', rdf, rdfs, xsd, sh, prov }`)
255
+ **Parameters:**
256
+ - `text` (string, required) — MDLD formatted text
257
+ - `context` (object, optional) — Prefix mappings
202
258
  - `dataFactory` (object, optional) — Custom RDF/JS DataFactory
203
259
  - `graph` (string, optional) — Named graph IRI
204
260
 
205
261
  **Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
206
262
 
207
- - `quads` — Array of RDF/JS Quads (final resolved graph state)
208
- - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
209
- - `statements` — Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
210
- - `origin` — Lean origin tracking object with quadIndex for UI navigation
211
- - `context` — Final context used (includes prefixes)
263
+ - `quads` — RDF/JS Quads (final resolved graph state)
264
+ - `remove` — RDF/JS Quads (external retractions for diff workflows)
265
+ - `statements` — Elevated SPO quads from rdf:Statement patterns
266
+ - `origin` — Lean origin tracking for UI navigation
267
+ - `context` — Final context with prefixes
212
268
  - `primarySubject` — String IRI or null (canonical append identity)
213
- - `primary` — Object containing primary metadata (semantic surface descriptor)
214
- - `md` — Clean Markdown with all MD-LD annotations stripped (round-trip safe)
215
-
216
- **Dual-Layer Architecture:**
217
-
218
- | Layer | Field | Purpose | Use Cases |
219
- |-------|-------|---------|-----------|
220
- | **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
221
- | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
222
-
223
- **Primary Object Structure:**
224
- ```javascript
225
- primary: {
226
- subject: string | null, // First non-fragment subject declaration
227
- type: string | null, // First rdf:type declaration
228
- label: string | null // First rdfs:label literal
229
- }
230
- ```
269
+ - `primary` — Primary metadata quartet: `{ subject, type, label, comment }`
270
+ - `md` — Clean Markdown with annotations stripped
231
271
 
232
272
  ### `merge(docs, options)`
233
273
 
@@ -236,196 +276,137 @@ Merge multiple MDLD documents with diff polarity resolution.
236
276
  **Parameters:**
237
277
  - `docs` (array) — Array of markdown strings or ParseResult objects
238
278
  - `options` (object, optional):
239
- - `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
279
+ - `context` (object) — Prefix mappings
240
280
 
241
- **Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
281
+ **Returns:** `{ quads, remove, statements, origin, context, primarySubjects, primary }`
242
282
 
243
- - `quads` — Array of RDF/JS Quads (final resolved graph state)
244
- - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
283
+ - `quads` — RDF/JS Quads (final resolved graph state)
284
+ - `remove` — RDF/JS Quads (external retractions)
285
+ - `statements` — Elevated statements from all documents
245
286
  - `origin` — Merge origin with document tracking
246
- - `context` — Final context used (includes prefixes)
247
- - `primarySubjects` — Array of string IRIs (canonical append identities, ordered by merge)
248
- - `primary` — Array of primary objects (semantic surface descriptors, ordered by merge)
249
-
250
- **Dual-Layer Architecture:**
251
-
252
- | Layer | Field | Purpose | Use Cases |
253
- |-------|-------|---------|-----------|
254
- | **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
255
- | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
256
-
257
- **Primary Object Array Structure:**
258
- ```javascript
259
- primary: [
260
- {
261
- subject: string | null, // First non-fragment subject declaration
262
- type: string | null, // First rdf:type declaration
263
- label: string | null // First rdfs:label literal
264
- },
265
- // ... one object per document
266
- ]
267
- ```
268
-
269
-
270
- ### `generate({ quads, context, primarySubject })`
271
-
272
- Generate deterministic MDLD from RDF quads with visual styling.
287
+ - `context` — Final context with prefixes
288
+ - `primarySubjects` — Array of string IRIs (canonical identities)
289
+ - `primary` — Array of primary metadata objects
273
290
 
274
- **Parameters (named object):**
275
- - `quads` (array, required) — Array of RDF/JS Quads to convert
276
- - `context` (object, optional) — Prefix mappings (default: `{}`)
277
- - `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.
291
+ **Use case:** CRDT-style state management with append-only documents.
278
292
 
279
- **Returns:** `{ text, context }`
293
+ ### `generate({ quads, context, primarySubject, compactInline, renderReverse, remove })`
280
294
 
281
- **Features:**
282
- - Visual carrier styles based on datatype (code spans for numbers, bold booleans, etc.)
283
- - Label-in-heading: Uses `rdfs:label` in subject headings when available
284
- - Multiple labels: First label in heading, additional labels rendered as literals
285
- - Round-trip safe: All data preserved through parse → generate → parse
286
- - Composable: `generate(parse(text))` extracts semantics; `parse(generate({quads}))` normalizes quads
295
+ Generate deterministic MDLD from RDF quads.
287
296
 
288
- ### `generateNode({ quads, focusIRI, context })`
289
-
290
- Generate node-centric MDLD showing all quads where a specific IRI appears in any position.
291
-
292
- **Parameters (named object):**
293
- - `quads` (array, required) — Array of RDF/JS Quads to search
294
- - `focusIRI` (string, required) — The IRI to center the view on
295
- - `context` (object, optional) — Prefix mappings (default: `{}`)
296
-
297
- **Returns:** `{ text, context }`
298
-
299
- **Behavior (Safety-First):**
300
- - If `focusIRI` is null/undefined: Returns empty text
301
- - If `focusIRI` not in graph: Returns empty text (never falls back to all data)
302
- - If `quads` is empty: Returns empty text
303
-
304
- **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.
305
-
306
- **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.
307
-
308
- ### Composition Patterns
309
-
310
- With the unified named parameter API, `parse()` and `generate()` compose seamlessly through object spreading:
311
-
312
- ```javascript
313
- import { parse, generate, generateNode } from 'mdld-parse';
314
-
315
- // Pattern 1: parse → generate (semantic extraction)
316
- const canonical = generate({ ...parse({ text, context }) });
317
- // text → quads → canonical MDLD (deterministic, visual styling applied)
318
-
319
- // Pattern 2: generate → parse (normalize external RDF)
320
- const normalized = parse({ ...generate({ quads: externalQuads, context }) });
321
- // external quads → MDLD → validated quads (DataFactory-safe, no blank nodes)
322
-
323
- // Pattern 3: parse → generateNode (node-centric exploration)
324
- const nodeView = generateNode({ ...parse({ text }), focusIRI: 'http://example.org/alice' });
325
- // full graph → isolated node view (safe: returns empty if IRI not found)
326
- ```
297
+ **Parameters:**
298
+ - `quads` (array, required) — RDF/JS Quads to convert
299
+ - `context` (object, optional) — Prefix mappings
300
+ - `primarySubject` (string, optional) — IRI to place first in output
301
+ - `compactInline` (boolean, optional) — Inline type/label compaction (default: `false`)
302
+ - `renderReverse` (boolean, optional) — Reverse connections as `!p` (default: `false`)
303
+ - `remove` (array, optional) — RDF/JS Quads to retract (for diff generation)
327
304
 
328
- **Why this works:**
329
- - `parse()` returns `{ quads, context, primarySubject, md, ... }`
330
- - `generate()` accepts `{ quads, context, primarySubject }`
331
- - `generateNode()` accepts `{ quads, context, focusIRI }` (with focusIRI override)
332
- - Perfect shape alignment enables elegant `{ ...spread }` composition
305
+ **Returns:** `{ text, context, compactStats }`
333
306
 
334
- ### The `md` Field — Clean Markdown Extraction
307
+ - `text` — Generated MDLD text
308
+ - `context` — Full context with prefixes
309
+ - `compactStats` — Compaction metrics
335
310
 
336
- Every `parse()` result includes a `md` field containing the original Markdown with all MD-LD annotations stripped:
311
+ **Features:** Visual styling, label-in-heading, round-trip safe, diff generation.
337
312
 
338
- ```javascript
339
- const result = parse({
340
- text: `# Document {=ex:doc .Article}\n[Content] {ex:content}`,
341
- context: { ex: 'http://example.org/' }
342
- });
313
+ ### `generateNode({ quads, focusIRI, context, compactInline, renderReverse })`
343
314
 
344
- console.log(result.md);
345
- // # Document\nContent
315
+ Generate node-centric MDLD for a specific IRI.
346
316
 
347
- // Round-trip safety: re-parsing clean MD produces zero quads
348
- const reparsed = parse({ text: result.md });
349
- console.log(reparsed.quads.length); // 0
350
- ```
317
+ **Parameters:**
318
+ - `quads` (array, required) — RDF/JS Quads to search
319
+ - `focusIRI` (string, required) — IRI to center view on
320
+ - `context` (object, optional) — Prefix mappings
321
+ - `compactInline` (boolean, optional) — Inline compaction (default: `true`)
322
+ - `renderReverse` (boolean, optional) — Reverse connections (default: `true`)
351
323
 
352
- **Behavior:**
353
- - Valid MD-LD annotations (`{=...}`, `{+...}`, `{...}`) are completely removed
354
- - Content from value carriers (`[text]`, `**bold**`, `` `code` ``) is preserved
355
- - Invalid syntax (annotations not at end-of-line) is preserved as visible markers
356
- - Headings, lists, blockquotes, code blocks maintain their structure
357
- - Prefix declarations at start of line are stripped
358
- - Standalone subject declarations (`{=ex:subject}`) are stripped
324
+ **Returns:** `{ text, context, compactStats }`
359
325
 
360
- **Use cases:**
361
- - **Content extraction** — Get readable Markdown without semantic markup
362
- - **Syntax validation** — Remaining `{...}` patterns indicate invalid MD-LD syntax
363
- - **Round-trip testing** — `parse(md).md` should parse to zero quads
364
- - **Preview generation** — Show clean document before publishing
326
+ **Safety:** Returns empty text if focusIRI not found (prevents accidental full database rendering).
365
327
 
366
- ### `locate(quad, origin)`
328
+ ### `updateValue({ text, quad, value, origin })`
367
329
 
368
- Locate the origin entry for a quad using the lean origin system.
330
+ Update carrier text of a literal quad in MDLD text.
369
331
 
370
332
  **Parameters:**
371
- - `quad` (object) — The quad to locate (subject, predicate, object)
372
- - `origin` (object) — Origin object containing quadIndex
333
+ - `text` (string) — Original MDLD text
334
+ - `quad` (object) — Quad to update
335
+ - `value` (string) — New carrier text
336
+ - `origin` (object, optional) — ParseResult.origin
373
337
 
374
- **Returns:** `{ blockId, range, carrierType, subject, predicate, context, value, polarity }` or `null`
338
+ **Returns:** Updated MDLD text (fail-safe)
375
339
 
376
- ### `render(quads, options)`
340
+ **Use case:** Editor applications updating literal values.
377
341
 
378
- Render RDF quads as HTML+RDFa for web display.
342
+ ### `locate(quad, origin)`
379
343
 
380
- **Parameters:**
381
- - `quads` (array) — Array of RDF/JS Quads to render
382
- - `options` (object, optional):
383
- - `context` (object) — Prefix mappings for CURIE shortening
384
- - `baseIRI` (string) — Base IRI for resolving relative references
344
+ Locate quad origin entry for UI navigation.
385
345
 
386
- **Returns:** `{ html, context }`
346
+ **Returns:** `{ blockId, range, valueRange, carrierType, ... }` or `null`
387
347
 
388
348
  ### Utility Functions
389
349
 
390
350
  ```javascript
391
351
  import {
392
352
  DEFAULT_CONTEXT, // Default prefix mappings
393
- DataFactory, // RDF/JS DataFactory instance
394
- hash, // String hashing function
395
- expandIRI, // IRI expansion with context
396
- shortenIRI, // IRI shortening with context
397
- parseSemanticBlock // Parse semantic block syntax
353
+ DataFactory, // RDF/JS DataFactory
354
+ hash, // String hashing
355
+ expandIRI, // IRI expansion
356
+ shortenIRI, // IRI shortening
357
+ parseSemanticBlock // Semantic block parsing
398
358
  } from 'mdld-parse';
399
359
  ```
400
360
 
401
361
  ## 🏗️ Architecture
402
362
 
403
363
  ### Design Principles
404
- - **Zero dependencies** — Pure JavaScript, ~15KB minified
364
+ - **Zero dependencies** — Pure JavaScript, 84KB unminified (19KB gzipped)
405
365
  - **Streaming-first** — Single-pass parsing, O(n) complexity
406
- - **Standards-compliant** — RDF/JS data model
407
- - **Origin tracking** — Full round-trip support with source maps
366
+ - **Character-based tokenization** — 20-28% faster than regex-based approaches
367
+ - **Standards-compliant** — RDF/JS data model, W3C CURIE 1.0 syntax
368
+ - **Deterministic** — Same input always produces same output
408
369
  - **Explicit semantics** — No guessing, inference, or heuristics
409
370
 
371
+ ### Performance Characteristics
372
+ - **Real-time (60fps):** Up to 4,527 quads per frame
373
+ - **Batch processing:** Up to 225,059 quads per second
374
+ - **Memory efficient:** ~640 bytes per quad retained after GC
375
+ - **Streaming-friendly:** Full document never in memory
376
+
410
377
  ### RDF/JS Compatibility
411
- Quads are compatible with:
378
+ Quads work with:
412
379
  - [`n3.js`](https://github.com/rdfjs/N3.js) — Turtle/N-Triples serialization
413
- - [`rdflib.js`](https://github.com/linkeddata/rdflib.js) — RDF store and reasoning
380
+ - [`rdflib.js`](https://github.com/linkeddata/rdflib.js) — RDF stores
414
381
  - [`sparqljs`](https://github.com/RubenVerborgh/SPARQL.js) — SPARQL queries
415
- - [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) — Extended RDF utilities
382
+ - [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) — RDF utilities
416
383
 
417
- ## 🧪 Testing
384
+ ### Standards Compliance
385
+ - **RDF 1.1** — Core RDF concepts
386
+ - **RDFS** — Schema vocabulary
387
+ - **PROV-O** — Provenance ontology
388
+ - **SHACL** — Constraint validation
389
+ - **W3C CURIE 1.0** — Compact URI syntax
418
390
 
419
- The parser includes comprehensive tests covering all spec requirements:
391
+ ## 🧪 Testing
420
392
 
421
393
  ```bash
422
394
  pnpm test
423
395
  ```
424
396
 
425
- Tests validate:
426
- - Subject declaration and context
427
- - All predicate forms (p, ?p, !p)
428
- - Datatypes and language tags
429
- - Explicit list item annotations
430
- - Code blocks and blockquotes
431
- - Round-trip serialization
397
+ Comprehensive test suite covering:
398
+ - Syntax parsing and tokenization
399
+ - Context management and prefix folding
400
+ - Polarity system and retractions
401
+ - Elevated statements detection
402
+ - Primary metadata extraction
403
+ - Round-trip parse/generate cycles
404
+ - Origin tracking and provenance
405
+
406
+ ## 📚 Additional Resources
407
+
408
+ - **[Documentation](./docs/index.md)** — Complete guides and references
409
+ - **[Specification](./spec/index.md)** — Formal specification
410
+ - **[Examples](./examples/index.md)** — Real-world examples
411
+ - **[Grammar](./grammar/mdld.ebnf)** — EBNF grammar specification
412
+ - **[VS Code Extension](https://marketplace.visualstudio.com/)** — Syntax highlighting (coming soon)