@estiva-app/protocol 0.6.0 → 0.8.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.
@@ -0,0 +1,77 @@
1
+ /**
2
+ * One tree, whichever content model the body is in — SPEC §13.5.
3
+ *
4
+ * §13.5 asks for a renderer *"safe by construction"*, and the safety is not in
5
+ * a component: it is in never handing an app a string it has to interpret.
6
+ * What this module produces is a fully resolved tree — marks decided, blocks
7
+ * decided, nothing left to parse and nothing to interpolate — so the app's only
8
+ * remaining job is to create elements and set text. An app that maps this tree
9
+ * cannot accidentally render markup, because there is no markup in it.
10
+ *
11
+ * ## Why a tree rather than a shared component
12
+ *
13
+ * Not because the apps use different frameworks — Ship and Peek are both React
14
+ * and already share `@estiva-app/ui`, so a component was possible. Because
15
+ * **how rich text looks is the consumer's**, which is the same rule RFC 0.4
16
+ * §13.1 states for projections — *the owner defines the projection, the
17
+ * consumer decides how it looks* — and SPEC §10's line about apps sharing the
18
+ * wire and never the interpretation. A shared component would make Ship and
19
+ * Peek look alike by construction, which is not a property anybody asked for.
20
+ *
21
+ * So: one parse, one resolution, two designs.
22
+ *
23
+ * ## The three formats, including the one nobody has written yet
24
+ *
25
+ * `toRenderTree` takes the format from `contentFormatOf` in
26
+ * `@estiva-app/interop` — the tag, never the body (§13.4). `'unknown'` is the
27
+ * interesting one: a format declared after this code was written becomes a
28
+ * single unmarked paragraph of the raw value, which §13.5 says is conformant.
29
+ * Handling it here rather than in each consumer is what stops one app deciding
30
+ * to guess.
31
+ */
32
+ import { type InlineMark } from './content.js';
33
+ /** A run of text and the marks on it. Nothing here needs escaping; it is text. */
34
+ export interface RenderInline {
35
+ text: string;
36
+ marks: InlineMark[];
37
+ }
38
+ /**
39
+ * A resolved block.
40
+ *
41
+ * **A `\n` inside `inline` text is a line break**, in both content models — it
42
+ * is how a marker-text paragraph carries its lines, and it keeps a consumer
43
+ * from needing two rules. Splitting on it is the consumer's whole obligation.
44
+ */
45
+ export interface RenderBlock {
46
+ type: 'paragraph' | 'heading' | 'bulletList' | 'orderedList' | 'listItem' | 'blockquote' | 'codeBlock' | 'table' | 'horizontalRule' | 'attachment' | 'widget' | 'unknown';
47
+ /** The block's address, from a block document. Marker text has no addressable
48
+ * sub-unit (§13.1), so it is absent — which is the difference that matters. */
49
+ id?: string;
50
+ level?: 1 | 2 | 3;
51
+ language?: string;
52
+ attrs?: Record<string, unknown>;
53
+ /** What the document actually called it, when `type` is `'unknown'`. */
54
+ typeName?: string;
55
+ inline?: RenderInline[];
56
+ children?: RenderBlock[];
57
+ }
58
+ /** The content models a body can be in — `contentFormatOf`'s three values. */
59
+ export type RenderFormat = 'marker' | 'blocks' | 'unknown';
60
+ /**
61
+ * The body, resolved.
62
+ *
63
+ * `format` comes from the event's `content-format` tag — `contentFormatOf` in
64
+ * `@estiva-app/interop`. Do not infer it from `value`: §13.4 forbids it, and a
65
+ * legacy description that happens to begin with `{` is the case that proves
66
+ * why.
67
+ *
68
+ * A body in an unparseable state never throws here. A `'blocks'` value that is
69
+ * not a document degrades to one unmarked paragraph — the same outcome as
70
+ * `'unknown'` — because a reader that throws renders nothing at all, and a
71
+ * description that is present is better shown as its own text than as an empty
72
+ * field.
73
+ */
74
+ export declare function toRenderTree(value: string, format: RenderFormat): RenderBlock[];
75
+ /** Every character a reader would see, for previews and search. */
76
+ export declare function renderTreeText(blocks: readonly RenderBlock[]): string;
77
+ //# sourceMappingURL=render.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAEL,KAAK,UAAU,EAIhB,MAAM,cAAc,CAAA;AAGrB,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,UAAU,EAAE,CAAA;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EACA,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,aAAa,GAAG,UAAU,GACnE,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,gBAAgB,GACvD,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAA;IACvC;oFACgF;IAChF,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;IACvB,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;CACzB;AAED,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;AAyF1D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,WAAW,EAAE,CAY/E;AAMD,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CASrE"}
package/dist/render.js ADDED
@@ -0,0 +1,162 @@
1
+ /**
2
+ * One tree, whichever content model the body is in — SPEC §13.5.
3
+ *
4
+ * §13.5 asks for a renderer *"safe by construction"*, and the safety is not in
5
+ * a component: it is in never handing an app a string it has to interpret.
6
+ * What this module produces is a fully resolved tree — marks decided, blocks
7
+ * decided, nothing left to parse and nothing to interpolate — so the app's only
8
+ * remaining job is to create elements and set text. An app that maps this tree
9
+ * cannot accidentally render markup, because there is no markup in it.
10
+ *
11
+ * ## Why a tree rather than a shared component
12
+ *
13
+ * Not because the apps use different frameworks — Ship and Peek are both React
14
+ * and already share `@estiva-app/ui`, so a component was possible. Because
15
+ * **how rich text looks is the consumer's**, which is the same rule RFC 0.4
16
+ * §13.1 states for projections — *the owner defines the projection, the
17
+ * consumer decides how it looks* — and SPEC §10's line about apps sharing the
18
+ * wire and never the interpretation. A shared component would make Ship and
19
+ * Peek look alike by construction, which is not a property anybody asked for.
20
+ *
21
+ * So: one parse, one resolution, two designs.
22
+ *
23
+ * ## The three formats, including the one nobody has written yet
24
+ *
25
+ * `toRenderTree` takes the format from `contentFormatOf` in
26
+ * `@estiva-app/interop` — the tag, never the body (§13.4). `'unknown'` is the
27
+ * interesting one: a format declared after this code was written becomes a
28
+ * single unmarked paragraph of the raw value, which §13.5 says is conformant.
29
+ * Handling it here rather than in each consumer is what stops one app deciding
30
+ * to guess.
31
+ */
32
+ import { parseBodySegments, parseInlineMarks, } from './content.js';
33
+ import { parseBlockDocument, inlineTextOf } from './blocks.js';
34
+ const KNOWN = new Set([
35
+ 'paragraph', 'heading', 'bulletList', 'orderedList', 'listItem',
36
+ 'blockquote', 'codeBlock', 'table', 'horizontalRule', 'attachment', 'widget',
37
+ ]);
38
+ const marksOf = (span) => {
39
+ const out = [];
40
+ if (span.bold)
41
+ out.push('bold');
42
+ if (span.italic)
43
+ out.push('italic');
44
+ if (span.underline)
45
+ out.push('underline');
46
+ if (span.code)
47
+ out.push('code');
48
+ return out;
49
+ };
50
+ const inlineFromMarkers = (text) => parseInlineMarks(text).map((s) => ({ text: s.text, marks: marksOf(s) }));
51
+ /** One inline run per line, joined by the `\n` the interface documents. */
52
+ const inlineFromLines = (lines) => inlineFromMarkers(lines.join('\n'));
53
+ function blockFromSegment(seg) {
54
+ switch (seg.type) {
55
+ case 'heading':
56
+ return { type: 'heading', level: seg.level, inline: inlineFromMarkers(seg.text) };
57
+ case 'bullet':
58
+ return {
59
+ type: 'bulletList',
60
+ children: seg.items.map((item) => ({ type: 'listItem', inline: inlineFromMarkers(item) })),
61
+ };
62
+ case 'numbered':
63
+ return {
64
+ type: 'orderedList',
65
+ children: seg.items.map((item) => ({ type: 'listItem', inline: inlineFromMarkers(item) })),
66
+ };
67
+ case 'quote':
68
+ return { type: 'blockquote', inline: inlineFromLines(seg.lines) };
69
+ case 'code':
70
+ // A fence is literal by definition — its content is never mark-parsed.
71
+ return {
72
+ type: 'codeBlock',
73
+ ...(seg.language ? { language: seg.language } : {}),
74
+ inline: [{ text: seg.lines.join('\n'), marks: [] }],
75
+ };
76
+ case 'text':
77
+ return { type: 'paragraph', inline: inlineFromLines(seg.lines) };
78
+ }
79
+ }
80
+ const isInlineRun = (content) => Array.isArray(content) && content.every((n) => typeof n === 'object' && n !== null && n.type === 'text');
81
+ function blockFromDocument(block) {
82
+ const known = KNOWN.has(block.type);
83
+ const out = {
84
+ type: (known ? block.type : 'unknown'),
85
+ id: block.id,
86
+ ...(known ? {} : { typeName: block.type }),
87
+ ...(block.attrs ? { attrs: block.attrs } : {}),
88
+ };
89
+ const level = block.attrs?.level;
90
+ if (block.type === 'heading' && (level === 1 || level === 2 || level === 3))
91
+ out.level = level;
92
+ const language = block.attrs?.language;
93
+ if (block.type === 'codeBlock' && typeof language === 'string')
94
+ out.language = language;
95
+ if (Array.isArray(block.content)) {
96
+ if (isInlineRun(block.content)) {
97
+ out.inline = block.content.map((node) => ({
98
+ text: node.text,
99
+ marks: (node.marks ?? []).map((m) => m.type),
100
+ }));
101
+ }
102
+ else {
103
+ out.children = block.content.map(blockFromDocument);
104
+ }
105
+ }
106
+ /*
107
+ §13.3: a reader MUST render an unknown block's inline text and MUST NOT drop
108
+ it. A later version could nest content in a shape this code cannot walk, so
109
+ the fallback reads the text by shape rather than trusting the walk above to
110
+ have found it.
111
+ */
112
+ if (!known && !out.inline && !out.children) {
113
+ const text = inlineTextOf(block);
114
+ if (text)
115
+ out.inline = [{ text, marks: [] }];
116
+ }
117
+ return out;
118
+ }
119
+ /**
120
+ * The body, resolved.
121
+ *
122
+ * `format` comes from the event's `content-format` tag — `contentFormatOf` in
123
+ * `@estiva-app/interop`. Do not infer it from `value`: §13.4 forbids it, and a
124
+ * legacy description that happens to begin with `{` is the case that proves
125
+ * why.
126
+ *
127
+ * A body in an unparseable state never throws here. A `'blocks'` value that is
128
+ * not a document degrades to one unmarked paragraph — the same outcome as
129
+ * `'unknown'` — because a reader that throws renders nothing at all, and a
130
+ * description that is present is better shown as its own text than as an empty
131
+ * field.
132
+ */
133
+ export function toRenderTree(value, format) {
134
+ if (format === 'unknown')
135
+ return plainParagraph(value);
136
+ if (format === 'blocks') {
137
+ let doc;
138
+ try {
139
+ doc = parseBlockDocument(value);
140
+ }
141
+ catch {
142
+ return plainParagraph(value);
143
+ }
144
+ return doc.content.map(blockFromDocument);
145
+ }
146
+ return parseBodySegments(value).map(blockFromSegment);
147
+ }
148
+ function plainParagraph(value) {
149
+ return value === '' ? [] : [{ type: 'paragraph', inline: [{ text: value, marks: [] }] }];
150
+ }
151
+ /** Every character a reader would see, for previews and search. */
152
+ export function renderTreeText(blocks) {
153
+ return blocks
154
+ .map((b) => {
155
+ const own = (b.inline ?? []).map((i) => i.text).join('');
156
+ const kids = b.children ? renderTreeText(b.children) : '';
157
+ return [own, kids].filter((s) => s !== '').join('\n');
158
+ })
159
+ .filter((s) => s !== '')
160
+ .join('\n');
161
+ }
162
+ //# sourceMappingURL=render.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/protocol",
3
- "version": "0.6.0",
3
+ "version": "0.8.0",
4
4
  "description": "The Estiva wire format: Buzz-shaped Nostr event builders, NIP-01 ids, NIP-19 naddr, NIP-98 HTTP auth, and the relay clients. Speaks the protocol; interprets nothing.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/blocks.ts ADDED
@@ -0,0 +1,276 @@
1
+ /**
2
+ * The rich text field — SPEC §13.3.
3
+ *
4
+ * A message is marker text (`content.ts`); a rich text field is this: a tree of
5
+ * blocks, each with an id, serialised as JSON. **The id is the entire reason
6
+ * this model is JSON rather than text.** A comment anchors to `<object address>
7
+ * + <block id>`, which is what RFC 0.4 §6 was waiting for, and an implementation
8
+ * that mints ids at render time has built a tree that is not addressable — the
9
+ * anchor has nothing to bind to and nobody finds out until it silently drifts.
10
+ *
11
+ * ## What is deliberately not here
12
+ *
13
+ * **The `content-format` tag.** SPEC §13.4's read rule already lives in
14
+ * `@estiva-app/interop` as `contentFormatOf`, alongside `CONTENT_FORMAT_TAG`
15
+ * and `BLOCK_DOCUMENT_FORMAT`, because it is a question about an *event and its
16
+ * slot* rather than about a document. Defining the same wire string here would
17
+ * be a second copy of exactly the kind this package exists to prevent, so this
18
+ * module never names it: a document does not know its own tag, and the reader
19
+ * that does is one layer up.
20
+ *
21
+ * **Rendering.** §13.5's safe renderer is RIC-6's, where Ship is the consumer
22
+ * that needs it. What this module owes a renderer is {@link inlineTextOf}, so
23
+ * an unknown block type can be drawn as its own text rather than dropped.
24
+ */
25
+ import { bytesToHex, randomBytes } from '@noble/hashes/utils'
26
+ import { type InlineTextNode, inlineNodesToText } from './content.js'
27
+
28
+ /**
29
+ * The block types §13.3 names.
30
+ *
31
+ * **Open, not closed.** An unknown type is not an error at any point in this
32
+ * module — §13.3 requires a reader to render its inline text and forbids
33
+ * dropping it silently, which is the same fallback discipline §7.5 applies to
34
+ * widgets and for the same reason: consumers upgrade at different times, and a
35
+ * block that vanishes is indistinguishable from one you may not read.
36
+ */
37
+ export const KNOWN_BLOCK_TYPES = [
38
+ 'paragraph',
39
+ 'heading',
40
+ 'bulletList',
41
+ 'orderedList',
42
+ 'listItem',
43
+ 'blockquote',
44
+ 'codeBlock',
45
+ 'table',
46
+ 'horizontalRule',
47
+ 'attachment',
48
+ 'widget',
49
+ ] as const
50
+
51
+ export type KnownBlockType = (typeof KNOWN_BLOCK_TYPES)[number]
52
+
53
+ export interface Block {
54
+ /** A {@link KnownBlockType}, or anything a later version publishes. */
55
+ type: string
56
+ /** Unique within the document, and stable across edits that do not replace it. */
57
+ id: string
58
+ attrs?: Record<string, unknown>
59
+ /** Inline runs, or child blocks. A leaf like `horizontalRule` has neither. */
60
+ content?: InlineTextNode[] | Block[]
61
+ }
62
+
63
+ export interface BlockDocument {
64
+ type: 'doc'
65
+ content: Block[]
66
+ }
67
+
68
+ /** Thrown by {@link parseBlockDocument}; `problems` is {@link validateBlockDocument}'s list. */
69
+ export class BlockDocumentError extends Error {
70
+ readonly problems: string[]
71
+ constructor(problems: string[]) {
72
+ super(`not a block document: ${problems.join('; ')}`)
73
+ this.name = 'BlockDocumentError'
74
+ this.problems = problems
75
+ }
76
+ }
77
+
78
+ const isObject = (v: unknown): v is Record<string, unknown> =>
79
+ typeof v === 'object' && v !== null && !Array.isArray(v)
80
+
81
+ const isInlineRun = (content: unknown): content is InlineTextNode[] =>
82
+ Array.isArray(content) && content.every((n) => isObject(n) && n.type === 'text')
83
+
84
+ /**
85
+ * Every way a value fails to be a block document, rather than the first.
86
+ *
87
+ * A validator that stops at the first problem makes fixing a document a
88
+ * sequence of round trips, and this one is read by authors of *other* apps.
89
+ */
90
+ export function validateBlockDocument(value: unknown): string[] {
91
+ const problems: string[] = []
92
+ if (!isObject(value)) return ['root is not an object']
93
+ if (value.type !== 'doc') problems.push(`root type is ${JSON.stringify(value.type)}, expected "doc"`)
94
+ if (!Array.isArray(value.content)) {
95
+ problems.push('root has no content array')
96
+ return problems
97
+ }
98
+
99
+ const seen = new Set<string>()
100
+ const walk = (blocks: unknown[], path: string) => {
101
+ blocks.forEach((block, i) => {
102
+ const at = `${path}[${i}]`
103
+ if (!isObject(block)) {
104
+ problems.push(`${at} is not an object`)
105
+ return
106
+ }
107
+ if (typeof block.type !== 'string' || block.type === '') {
108
+ problems.push(`${at} has no type`)
109
+ }
110
+ // §13.3: every block, not only the ones an app happens to know.
111
+ if (typeof block.id !== 'string' || block.id === '') {
112
+ problems.push(`${at} has no id`)
113
+ } else if (seen.has(block.id)) {
114
+ problems.push(`${at} repeats the id ${JSON.stringify(block.id)}`)
115
+ } else {
116
+ seen.add(block.id)
117
+ }
118
+ if (block.type === 'heading') {
119
+ const level = isObject(block.attrs) ? block.attrs.level : undefined
120
+ if (typeof level !== 'number' || !Number.isInteger(level) || level < 1 || level > 3) {
121
+ problems.push(`${at} is a heading with level ${JSON.stringify(level)}, expected 1–3`)
122
+ }
123
+ }
124
+ if (block.content === undefined) return
125
+ if (!Array.isArray(block.content)) {
126
+ problems.push(`${at} has a content that is not an array`)
127
+ return
128
+ }
129
+ if (isInlineRun(block.content)) {
130
+ block.content.forEach((node, j) => {
131
+ const nodeAt = `${at}.content[${j}]`
132
+ if (typeof (node as { text?: unknown }).text !== 'string') {
133
+ problems.push(`${nodeAt} has no text`)
134
+ }
135
+ const marks = (node as { marks?: unknown }).marks
136
+ if (marks === undefined) return
137
+ if (!Array.isArray(marks)) {
138
+ problems.push(`${nodeAt} has marks that are not an array`)
139
+ return
140
+ }
141
+ for (const mark of marks) {
142
+ if (!isObject(mark) || typeof mark.type !== 'string') {
143
+ problems.push(`${nodeAt} has a mark with no type`)
144
+ }
145
+ }
146
+ })
147
+ return
148
+ }
149
+ walk(block.content, `${at}.content`)
150
+ })
151
+ }
152
+ walk(value.content, 'content')
153
+ return problems
154
+ }
155
+
156
+ /**
157
+ * A block document from JSON text, or from an already-parsed value.
158
+ *
159
+ * **Throws rather than returning a partial document.** A caller that cannot
160
+ * tell "this is not a block document" from "this is an empty one" would render
161
+ * a blank field for a body that is really there — and §13.4 is explicit that a
162
+ * body's model is decided by its event's tag, so arriving here with something
163
+ * that is not a document means the tag was wrong, which is worth an error and
164
+ * not a shrug.
165
+ */
166
+ export function parseBlockDocument(input: string | unknown): BlockDocument {
167
+ let value: unknown = input
168
+ if (typeof input === 'string') {
169
+ try {
170
+ value = JSON.parse(input)
171
+ } catch (e) {
172
+ throw new BlockDocumentError([`content is not JSON: ${(e as Error).message}`])
173
+ }
174
+ }
175
+ const problems = validateBlockDocument(value)
176
+ if (problems.length) throw new BlockDocumentError(problems)
177
+ return value as BlockDocument
178
+ }
179
+
180
+ /** JSON text for the wire. §12.3's 256 KiB ingest cap applies to this string. */
181
+ export function serializeBlockDocument(doc: BlockDocument): string {
182
+ return JSON.stringify(doc)
183
+ }
184
+
185
+ /**
186
+ * A fresh block id.
187
+ *
188
+ * Short on purpose: ids repeat in every anchor and every serialisation, the
189
+ * document has a 256 KiB ceiling, and uniqueness is only required *within one
190
+ * document* (§13.3) rather than globally. 12 hex characters is far more than
191
+ * that needs, and {@link assignMissingBlockIds} checks for a collision anyway
192
+ * rather than trusting the arithmetic.
193
+ */
194
+ export function newBlockId(): string {
195
+ // `@noble/hashes`' randomBytes, the same source `nip98.ts` draws its nonce
196
+ // from — one CSPRNG seam for the package rather than a direct `globalThis`
197
+ // reach that types differently under DOM and node libs.
198
+ return bytesToHex(randomBytes(6))
199
+ }
200
+
201
+ /**
202
+ * Ids for blocks that have none, **leaving every existing id alone**.
203
+ *
204
+ * This is the id-stability rule (§13.3) as a function. An editor rebuilds a
205
+ * document on every keystroke; if that rebuild re-mints ids, every anchored
206
+ * comment detaches on the next edit and the anchoring feature is silently
207
+ * worthless. Assigning only what is missing makes the safe path the easy one.
208
+ *
209
+ * Returns a new document; the input is not mutated.
210
+ */
211
+ export function assignMissingBlockIds(doc: BlockDocument): BlockDocument {
212
+ const taken = new Set(blockIds(doc))
213
+ const fresh = () => {
214
+ let id = newBlockId()
215
+ while (taken.has(id)) id = newBlockId()
216
+ taken.add(id)
217
+ return id
218
+ }
219
+ const walk = (blocks: Block[]): Block[] =>
220
+ blocks.map((block) => {
221
+ const id = typeof block.id === 'string' && block.id !== '' ? block.id : fresh()
222
+ const content =
223
+ Array.isArray(block.content) && !isInlineRun(block.content)
224
+ ? walk(block.content as Block[])
225
+ : block.content
226
+ return { ...block, id, ...(content === undefined ? {} : { content }) } as Block
227
+ })
228
+ return { ...doc, content: walk(doc.content) }
229
+ }
230
+
231
+ /** Every block id in document order, nested blocks included. */
232
+ export function blockIds(doc: BlockDocument): string[] {
233
+ const out: string[] = []
234
+ const walk = (blocks: Block[]) => {
235
+ for (const block of blocks) {
236
+ if (typeof block.id === 'string' && block.id !== '') out.push(block.id)
237
+ if (Array.isArray(block.content) && !isInlineRun(block.content)) walk(block.content as Block[])
238
+ }
239
+ }
240
+ walk(doc.content)
241
+ return out
242
+ }
243
+
244
+ /** The block an anchor points at, or `undefined` if it is gone. */
245
+ export function findBlock(doc: BlockDocument, id: string): Block | undefined {
246
+ const walk = (blocks: Block[]): Block | undefined => {
247
+ for (const block of blocks) {
248
+ if (block.id === id) return block
249
+ if (Array.isArray(block.content) && !isInlineRun(block.content)) {
250
+ const hit = walk(block.content as Block[])
251
+ if (hit) return hit
252
+ }
253
+ }
254
+ return undefined
255
+ }
256
+ return walk(doc.content)
257
+ }
258
+
259
+ /**
260
+ * A block's text, including its children's.
261
+ *
262
+ * This is what §13.3 requires a reader to draw for a block type it does not
263
+ * know — *"render that block's inline text rather than dropping it"*. It works
264
+ * on an unknown type for the same reason it works on a known one: it reads the
265
+ * shape, never the name.
266
+ */
267
+ export function inlineTextOf(block: Block): string {
268
+ if (!Array.isArray(block.content)) return ''
269
+ if (isInlineRun(block.content)) return inlineNodesToText(block.content)
270
+ return (block.content as Block[]).map(inlineTextOf).join('\n')
271
+ }
272
+
273
+ /** The whole document as plain text — previews, search, and the last-resort render. */
274
+ export function documentText(doc: BlockDocument): string {
275
+ return doc.content.map(inlineTextOf).filter((t) => t !== '').join('\n')
276
+ }
package/src/content.ts CHANGED
@@ -292,3 +292,59 @@ export function stripInlineFormatting(text: string): string {
292
292
  .map((line) => parseInlineMarks(stripLinePrefixes(line)).map((s) => s.text).join(''))
293
293
  .join('\n')
294
294
  }
295
+
296
+ // ── The inline vocabulary's second serialisation — SPEC §13.1 ──
297
+ //
298
+ // The same marks, encoded as JSON nodes instead of markers, because a block
299
+ // document's inline content is an array of these (§13.3). RIC-4 shipped the
300
+ // marker side and deliberately stopped there: this half had no consumer until
301
+ // the block model existed, and designing an encoding against no caller is how
302
+ // you get one nobody can use.
303
+ //
304
+ // **The vocabulary is shared; the encoding is not.** That is the whole shape of
305
+ // SPEC §13 — a message and a paragraph mean the same thing by "bold", and agree
306
+ // about nothing else.
307
+
308
+ /** A mark on an inline run, in the JSON encoding. */
309
+ export type InlineMarkNode = { type: InlineMark }
310
+
311
+ /** One run of text and its marks — §13.3's `{"type":"text","text":…,"marks":[…]}`. */
312
+ export interface InlineTextNode {
313
+ type: 'text'
314
+ text: string
315
+ marks?: InlineMarkNode[]
316
+ }
317
+
318
+ /** Deterministic order, so the same marks always serialise to the same JSON.
319
+ * Two encoders disagreeing about array order would produce documents that
320
+ * differ byte-for-byte while meaning the same thing, and every equality check
321
+ * downstream — a diff, a dedupe, a cache key — would be wrong about it. */
322
+ const MARK_ORDER: InlineMark[] = ['bold', 'italic', 'underline', 'code']
323
+
324
+ /** Marker text → inline JSON nodes. */
325
+ export function markersToInlineNodes(text: string): InlineTextNode[] {
326
+ return parseInlineMarks(text).map((span) => {
327
+ const marks = MARK_ORDER.filter((m) => span[m]).map((type) => ({ type }))
328
+ return marks.length ? { type: 'text' as const, text: span.text, marks } : { type: 'text' as const, text: span.text }
329
+ })
330
+ }
331
+
332
+ /**
333
+ * Inline JSON nodes → marker text.
334
+ *
335
+ * The inverse of {@link markersToInlineNodes} for every mark the dialect can
336
+ * spell, which is all four of them. Whitespace at a run's edges is hoisted
337
+ * outside the markers by `wrapInlineMarks`, because §13.2 rule 1 would not
338
+ * parse it back otherwise — so this round-trips the *marks on each character*
339
+ * rather than the span boundaries. See the corpus tests.
340
+ */
341
+ export function inlineNodesToMarkers(nodes: readonly InlineTextNode[]): string {
342
+ return nodes
343
+ .map((node) => wrapInlineMarks(node.text, new Set((node.marks ?? []).map((m) => m.type))))
344
+ .join('')
345
+ }
346
+
347
+ /** The plain text of a run of inline nodes, marks discarded. */
348
+ export function inlineNodesToText(nodes: readonly InlineTextNode[]): string {
349
+ return nodes.map((n) => n.text).join('')
350
+ }
package/src/index.ts CHANGED
@@ -47,7 +47,7 @@
47
47
  /** Bumped by hand with the version in package.json — `test/version.test.ts`
48
48
  * pins the two together. It exists so "the upgrade reached the app" can be
49
49
  * checked by grepping a built bundle rather than by trusting a lockfile. */
50
- export const PROTOCOL_VERSION = '0.6.0'
50
+ export const PROTOCOL_VERSION = '0.8.0'
51
51
 
52
52
  export {
53
53
  // types
@@ -168,8 +168,38 @@ export {
168
168
  type InlineMark,
169
169
  type InlineMarkSpan,
170
170
  type BodySegment,
171
+ type InlineMarkNode,
172
+ type InlineTextNode,
171
173
  parseInlineMarks,
172
174
  wrapInlineMarks,
173
175
  parseBodySegments,
174
176
  stripInlineFormatting,
177
+ markersToInlineNodes,
178
+ inlineNodesToMarkers,
179
+ inlineNodesToText,
175
180
  } from './content.js'
181
+
182
+ export {
183
+ type Block,
184
+ type BlockDocument,
185
+ type KnownBlockType,
186
+ KNOWN_BLOCK_TYPES,
187
+ BlockDocumentError,
188
+ validateBlockDocument,
189
+ parseBlockDocument,
190
+ serializeBlockDocument,
191
+ newBlockId,
192
+ assignMissingBlockIds,
193
+ blockIds,
194
+ findBlock,
195
+ inlineTextOf,
196
+ documentText,
197
+ } from './blocks.js'
198
+
199
+ export {
200
+ type RenderInline,
201
+ type RenderBlock,
202
+ type RenderFormat,
203
+ toRenderTree,
204
+ renderTreeText,
205
+ } from './render.js'