@estiva-app/protocol 0.5.0 → 0.7.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/src/content.ts ADDED
@@ -0,0 +1,350 @@
1
+ /**
2
+ * The message marker dialect — SPEC §13.1 and §13.2.
3
+ *
4
+ * ## Why content is in a package that "interprets nothing"
5
+ *
6
+ * `index.ts` draws the line at *interpretation*: the fold stays in the apps,
7
+ * because how an app turns events into current truth is where apps are supposed
8
+ * to differ. A body's formatting is on the other side of that line for the same
9
+ * reason the event id is — **it is wire-visible, and two apps disagreeing about
10
+ * it produces a divergence each copy is self-consistent about and nobody
11
+ * notices.** That is not a hypothetical: measured on production 2026-09-02,
12
+ * 261 of 548 published messages carry structure, Peek parses it, Ship renders
13
+ * it literally, and neither is wrong about its own behaviour.
14
+ *
15
+ * Being honest about the usual test: the relay would *not* notice if two apps
16
+ * disagreed here, so §10's question is a poor fit. What makes this belong is the
17
+ * failure shape rather than the arbiter — see RFC 0.4 §14.3, which put the
18
+ * inline layer here, and SPEC §13.1, which made it normative.
19
+ *
20
+ * **What is deliberately not here.** Mentions resolved against a directory,
21
+ * bracket references to an app's own objects, and anything that needs to know
22
+ * what a topic or a file is. Peek's `textParsing.ts` mixes those with the marks;
23
+ * only the marks moved. A `nostr:` reference is a mark and its *token* is in
24
+ * scope, but what a mention does is RIC-2's.
25
+ */
26
+
27
+ /** Marks a run of text can carry. `code` is exclusive — see {@link parseInlineMarks}. */
28
+ export type InlineMark = 'bold' | 'italic' | 'underline' | 'code'
29
+
30
+ /** A run of text and the marks on it. */
31
+ export interface InlineMarkSpan {
32
+ text: string
33
+ bold?: boolean
34
+ italic?: boolean
35
+ underline?: boolean
36
+ code?: boolean
37
+ }
38
+
39
+ /** A block-level run, parsed from line prefixes. */
40
+ export type BodySegment =
41
+ | { type: 'text'; lines: string[] }
42
+ | { type: 'bullet'; items: string[] }
43
+ | { type: 'numbered'; items: string[] }
44
+ | { type: 'heading'; level: 1 | 2; text: string }
45
+ | { type: 'quote'; lines: string[] }
46
+ | { type: 'code'; language?: string; lines: string[] }
47
+
48
+ interface MarkToken {
49
+ token: string
50
+ keys: InlineMark[]
51
+ /**
52
+ * The content is taken literally and no mark may nest inside it, and the
53
+ * adjacency fence below does not apply to the delimiter.
54
+ */
55
+ literal?: boolean
56
+ }
57
+
58
+ /**
59
+ * Longest token first so `***` is not consumed as `**` plus a dangling `*`.
60
+ *
61
+ * Order only decides ties at one index — the scanner walks left to right, so the
62
+ * leftmost opening delimiter wins regardless of what is listed first.
63
+ */
64
+ const MARK_TOKENS: MarkToken[] = [
65
+ { token: '***', keys: ['bold', 'italic'] },
66
+ { token: '**', keys: ['bold'] },
67
+ { token: '__', keys: ['underline'] },
68
+ { token: '*', keys: ['italic'] },
69
+ { token: '`', keys: ['code'], literal: true },
70
+ ]
71
+
72
+ const isWordChar = (ch: string | undefined) => ch !== undefined && /[A-Za-z0-9]/.test(ch)
73
+
74
+ /**
75
+ * SPEC §13.2 rule 2 — a marker adjacent to an alphanumeric is not a marker, so
76
+ * `2*3*4` stays literal math.
77
+ *
78
+ * **It does not apply to a backtick.** Rule 2 resolves an ambiguity that only
79
+ * asymmetric prose markers have: `*` is multiplication and a glob, `_` is in
80
+ * identifiers. A backtick is not used as ordinary punctuation, so there is no
81
+ * ambiguity to resolve — and applying the fence anyway leaves `` `main`s ``
82
+ * literal, which is a code span followed by a plural or possessive. Measured
83
+ * against production 2026-09-02: 8 such spans in 6 published messages, and zero
84
+ * cases of the opening side needing the fence. CommonMark agrees.
85
+ */
86
+ function findMarkClose(text: string, token: string, from: number, fenced: boolean): number {
87
+ let idx = text.indexOf(token, from)
88
+ while (idx !== -1) {
89
+ if (!fenced || !isWordChar(text[idx + token.length])) return idx
90
+ idx = text.indexOf(token, idx + 1)
91
+ }
92
+ return -1
93
+ }
94
+
95
+ function toMarkSpan(text: string, active: InlineMark[]): InlineMarkSpan {
96
+ const span: InlineMarkSpan = { text }
97
+ for (const key of active) span[key] = true
98
+ return span
99
+ }
100
+
101
+ function scanMarks(text: string, active: InlineMark[]): InlineMarkSpan[] {
102
+ for (let i = 0; i < text.length; i++) {
103
+ for (const { token, keys, literal } of MARK_TOKENS) {
104
+ if (keys.some((k) => active.includes(k))) continue
105
+ if (!text.startsWith(token, i)) continue
106
+ const fenced = !literal
107
+ if (fenced && isWordChar(text[i - 1])) continue
108
+ const close = findMarkClose(text, token, i + token.length, fenced)
109
+ if (close === -1) continue
110
+ const inner = text.slice(i + token.length, close)
111
+ // SPEC §13.2 rule 1: whitespace at the inner edges means it is not a pair.
112
+ if (!inner || /^\s/.test(inner) || /\s$/.test(inner)) continue
113
+ const spans: InlineMarkSpan[] = []
114
+ const before = text.slice(0, i)
115
+ if (before) spans.push(toMarkSpan(before, active))
116
+ if (literal) {
117
+ /*
118
+ SPEC §13.1: code MUST NOT combine with any other mark, and its content
119
+ MUST NOT be parsed for further marks. So the span carries `code` alone
120
+ even inside an enclosing bold — dropping the outer mark rather than
121
+ emitting a combination the spec forbids.
122
+ */
123
+ spans.push({ text: inner, code: true })
124
+ } else {
125
+ spans.push(...scanMarks(inner, [...active, ...keys]))
126
+ }
127
+ spans.push(...scanMarks(text.slice(close + token.length), active))
128
+ return spans
129
+ }
130
+ }
131
+ return text ? [toMarkSpan(text, active)] : []
132
+ }
133
+
134
+ /**
135
+ * Parse one plain-text run into styled spans.
136
+ *
137
+ * Split mentions and app-specific references out first — this function knows
138
+ * about marks and nothing else.
139
+ */
140
+ export function parseInlineMarks(text: string): InlineMarkSpan[] {
141
+ return scanMarks(text, [])
142
+ }
143
+
144
+ /**
145
+ * Wrap a run of text in the markers for the marks it carries.
146
+ *
147
+ * Edge whitespace is hoisted outside the markers, because `**word **` would not
148
+ * parse back under rule 1 — so bolding "word " round-trips as `**word** `.
149
+ *
150
+ * `code` wins alone, for the same reason the parser never emits it combined.
151
+ */
152
+ export function wrapInlineMarks(text: string, markNames: ReadonlySet<string>): string {
153
+ if (!text) return text
154
+ const bold = markNames.has('bold')
155
+ const italic = markNames.has('italic')
156
+ const underline = markNames.has('underline')
157
+ const code = markNames.has('code')
158
+ if (!bold && !italic && !underline && !code) return text
159
+ const m = text.match(/^(\s*)([\s\S]*?)(\s*)$/)!
160
+ const [, lead, core, trail] = m
161
+ if (!core) return text
162
+ if (code) return `${lead}\`${core}\`${trail}`
163
+ let out = core
164
+ if (bold && italic) out = `***${out}***`
165
+ else if (bold) out = `**${out}**`
166
+ else if (italic) out = `*${out}*`
167
+ if (underline) out = `__${out}__`
168
+ return lead + out + trail
169
+ }
170
+
171
+ const HEADING_LINE_RE = /^#{1,2}\s/
172
+ /** `> ` with the space required — a bare `>` typed at a line start ("5 > 3")
173
+ * stays literal, the same conservatism as the inline markers. */
174
+ const QUOTE_LINE_RE = /^>\s/
175
+ const FENCE_RE = /^```/
176
+
177
+ /**
178
+ * Where the fence opened at `from` closes, or -1 if it never does.
179
+ *
180
+ * An unclosed fence is not a fence: SPEC §13.2 requires an unmatched marker to
181
+ * render literally, and swallowing the rest of the body because somebody typed
182
+ * three backticks is the opposite of that.
183
+ */
184
+ function fenceCloses(lines: string[], from: number): number {
185
+ if (!FENCE_RE.test(lines[from])) return -1
186
+ for (let j = from + 1; j < lines.length; j++) if (FENCE_RE.test(lines[j])) return j
187
+ return -1
188
+ }
189
+
190
+ /**
191
+ * Split a body into block segments.
192
+ *
193
+ * Blank lines split runs of plain text into separate `text` segments. `# ` and
194
+ * `## ` become headings; three or more `#`s, and a `#123` reference with no
195
+ * space, stay plain text.
196
+ */
197
+ export function parseBodySegments(body: string): BodySegment[] {
198
+ const lines = body.split('\n')
199
+ const segments: BodySegment[] = []
200
+ let i = 0
201
+ while (i < lines.length) {
202
+ const line = lines[i]
203
+ const fenceEnd = fenceCloses(lines, i)
204
+ if (fenceEnd !== -1) {
205
+ const language = line.slice(3).trim()
206
+ segments.push({
207
+ type: 'code',
208
+ ...(language ? { language } : {}),
209
+ lines: lines.slice(i + 1, fenceEnd),
210
+ })
211
+ i = fenceEnd + 1
212
+ } else if (HEADING_LINE_RE.test(line) && !line.startsWith('###')) {
213
+ segments.push({
214
+ type: 'heading',
215
+ level: line.startsWith('##') ? 2 : 1,
216
+ text: line.replace(HEADING_LINE_RE, ''),
217
+ })
218
+ i++
219
+ } else if (/^[-•]\s/.test(line)) {
220
+ const items: string[] = []
221
+ while (i < lines.length && /^[-•]\s/.test(lines[i])) {
222
+ items.push(lines[i].replace(/^[-•]\s/, ''))
223
+ i++
224
+ }
225
+ segments.push({ type: 'bullet', items })
226
+ } else if (/^\d+\.\s/.test(line)) {
227
+ const items: string[] = []
228
+ while (i < lines.length && /^\d+\.\s/.test(lines[i])) {
229
+ items.push(lines[i].replace(/^\d+\.\s/, ''))
230
+ i++
231
+ }
232
+ segments.push({ type: 'numbered', items })
233
+ } else if (QUOTE_LINE_RE.test(line)) {
234
+ const quoteLines: string[] = []
235
+ while (i < lines.length && QUOTE_LINE_RE.test(lines[i])) {
236
+ quoteLines.push(lines[i].replace(QUOTE_LINE_RE, ''))
237
+ i++
238
+ }
239
+ segments.push({ type: 'quote', lines: quoteLines })
240
+ } else {
241
+ const textLines: string[] = []
242
+ while (
243
+ i < lines.length &&
244
+ fenceCloses(lines, i) === -1 &&
245
+ !/^[-•]\s/.test(lines[i]) &&
246
+ !/^\d+\.\s/.test(lines[i]) &&
247
+ !QUOTE_LINE_RE.test(lines[i]) &&
248
+ !(HEADING_LINE_RE.test(lines[i]) && !lines[i].startsWith('###'))
249
+ ) {
250
+ textLines.push(lines[i])
251
+ i++
252
+ }
253
+ let chunk: string[] = []
254
+ for (const l of textLines) {
255
+ if (l === '') {
256
+ if (chunk.length > 0) { segments.push({ type: 'text', lines: chunk }); chunk = [] }
257
+ } else {
258
+ chunk.push(l)
259
+ }
260
+ }
261
+ if (chunk.length > 0) segments.push({ type: 'text', lines: chunk })
262
+ }
263
+ }
264
+ return segments
265
+ }
266
+
267
+ /**
268
+ * Markers, heading prefixes and fences removed — for one-line previews that
269
+ * render body text raw, outside any renderer.
270
+ *
271
+ * **Prefixes stack, and the order they are removed in is not cosmetic.** The
272
+ * version this was extracted from removed the heading prefix first and the
273
+ * quote prefix second, so `> # Heading` — a quoted heading, which the corpus is
274
+ * full of because every project brief quotes one — came back as `# Heading` and
275
+ * a preview showed a stray `#`. Stripping until the line stops changing removes
276
+ * whatever order they were written in. Found by running this over 152 real
277
+ * published bodies, not by reading the code.
278
+ */
279
+ function stripLinePrefixes(line: string): string {
280
+ let out = line
281
+ for (;;) {
282
+ const next = out.replace(/^>\s/, '').replace(/^#{1,2}\s/, '')
283
+ if (next === out) return out
284
+ out = next
285
+ }
286
+ }
287
+
288
+ export function stripInlineFormatting(text: string): string {
289
+ return text
290
+ .split('\n')
291
+ .filter((line) => !FENCE_RE.test(line))
292
+ .map((line) => parseInlineMarks(stripLinePrefixes(line)).map((s) => s.text).join(''))
293
+ .join('\n')
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.5.0'
50
+ export const PROTOCOL_VERSION = '0.7.0'
51
51
 
52
52
  export {
53
53
  // types
@@ -163,3 +163,35 @@ export {
163
163
  type ChannelSubscriptions,
164
164
  createChannelSubscriptions,
165
165
  } from './subscriptions.js'
166
+
167
+ export {
168
+ type InlineMark,
169
+ type InlineMarkSpan,
170
+ type BodySegment,
171
+ type InlineMarkNode,
172
+ type InlineTextNode,
173
+ parseInlineMarks,
174
+ wrapInlineMarks,
175
+ parseBodySegments,
176
+ stripInlineFormatting,
177
+ markersToInlineNodes,
178
+ inlineNodesToMarkers,
179
+ inlineNodesToText,
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'