@estiva-app/protocol 0.29.0 → 0.31.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/embeds.ts ADDED
@@ -0,0 +1,176 @@
1
+ /**
2
+ * Showing a reference as a card — SPEC §13.6.2 (OPT-16).
3
+ *
4
+ * `["embed", <value>, "compact" | "detailed" | "none"]` says how the author
5
+ * wants one reference in a message drawn: as a card under the message, and how
6
+ * much of it. `<value>` is what an `a` or `q` would carry for the same thing —
7
+ * an address or a 64-hex event id. The values are a density, not a widget
8
+ * name: `compact` is §7.5's closed `row` and `detailed` its closed `card`, so
9
+ * a richer card can come later without changing the wire.
10
+ *
11
+ * A reference with no `embed` is drawn by the reader's default (a chip, §13.1).
12
+ * An `embed` for a value overrides that default, which is why `none` exists:
13
+ * it is the author saying "no card" in an edit that replaces the set (§6.8).
14
+ *
15
+ * Like `part` (§13.6.1), the tags are only half the answer. A card is drawn
16
+ * only while the body — as edited — still names its value, and there is no
17
+ * `a`/`q` match: an edit carries no index tags (§6.8), and a value first named
18
+ * in an edit can still carry a card (Miky, 2026-10-13, OPT-16 kickoff).
19
+ * {@link cardsIn} applies that rule; {@link embedsOf} reads the tags alone.
20
+ */
21
+ import { bech32Decode, convertBits, decodeNevent, naddrToAddr } from './nip19.js'
22
+ import type { PartPointer } from './anchors.js'
23
+ import type { RenderBlock } from './render.js'
24
+
25
+ export const EMBED_TAG = 'embed'
26
+
27
+ /** How much of a referenced object a card shows, or `none` for no card. */
28
+ export type EmbedLayout = 'compact' | 'detailed' | 'none'
29
+
30
+ /** One `embed` tag, read. */
31
+ export interface Embed {
32
+ /** An address (`kind:pubkey:d`) or a 64-hex event id, lowercase hex. */
33
+ value: string
34
+ layout: EmbedLayout
35
+ }
36
+
37
+ /** The `embed` tag for one reference. */
38
+ export function embedTag(value: string, layout: EmbedLayout): string[] {
39
+ return [EMBED_TAG, value, layout]
40
+ }
41
+
42
+ // `partsOf`'s shape: an empty `d` is a valid address (NIP-01).
43
+ const ADDRESS = /^\d+:[0-9a-f]{64}:/
44
+ const EVENT_ID = /^[0-9a-f]{64}$/
45
+
46
+ /**
47
+ * The `embed` tags on one event, one per value, in tag order.
48
+ *
49
+ * The first tag for a value wins. A layout this reader does not know draws as
50
+ * `compact` rather than nothing: the author asked for a card, and the smallest
51
+ * one is the safe reading of a density added after this reader was written. A
52
+ * value that is neither an address nor an event id is skipped.
53
+ *
54
+ * **This is the tags only**, of one event. For a message, fold its edits first
55
+ * (`foldEmbeds` in `@estiva-app/conversation`), then ask {@link cardsIn} which
56
+ * of them the body still names.
57
+ */
58
+ export function embedsOf(event: { tags: readonly (readonly string[])[] }): Embed[] {
59
+ const out: Embed[] = []
60
+ const seen = new Set<string>()
61
+ for (const tag of event.tags) {
62
+ if (tag[0] !== EMBED_TAG || !tag[1]) continue
63
+ const value = normalise(tag[1])
64
+ if (!value || seen.has(value)) continue
65
+ seen.add(value)
66
+ out.push({ value, layout: layoutOf(tag[2]) })
67
+ }
68
+ return out
69
+ }
70
+
71
+ function layoutOf(raw: string | undefined): EmbedLayout {
72
+ return raw === 'detailed' || raw === 'none' ? raw : 'compact'
73
+ }
74
+
75
+ function normalise(value: string): string | undefined {
76
+ if (EVENT_ID.test(value.toLowerCase())) return value.toLowerCase()
77
+ if (!ADDRESS.test(value)) return undefined
78
+ // The kind and pubkey are hex and compared as such; the `d` is the author's and kept as written.
79
+ const [kind, pubkey, ...d] = value.split(':')
80
+ return `${kind}:${pubkey.toLowerCase()}:${d.join(':')}`
81
+ }
82
+
83
+ /**
84
+ * What an app link names, as the reader resolved it by §7.7 — the host and the
85
+ * `<type>` segment against a published `urls` pattern, then the one author who
86
+ * holds that `d` — or undefined. Never a match on the link's trailing
87
+ * identifier alone: that resolves any site's URL as somebody's object, and puts
88
+ * a real issue's card under a link that does not open it (§7.7).
89
+ */
90
+ export type LinkResolver = (url: string) => string | undefined
91
+
92
+ const TRAILING = new Set(['.', ',', ';', ':', '!', '?', ')', ']'])
93
+
94
+ /** The http(s) links in a text. Trailing punctuation is the sentence's, not the link's; stripped by a loop, which stays linear on a hostile run of dots. */
95
+ function urlsIn(text: string): string[] {
96
+ return (text.match(/https?:\/\/[^\s<>"'`]+/g) ?? []).map((url) => {
97
+ let end = url.length
98
+ while (end > 0 && TRAILING.has(url[end - 1])) end--
99
+ return url.slice(0, end)
100
+ })
101
+ }
102
+
103
+ /** The address or event id a `nostr:` reference names, or undefined for a person or something unreadable. */
104
+ function valueOfReference(reference: string): string | undefined {
105
+ const bare = reference.replace(/^nostr:/i, '').toLowerCase()
106
+ try {
107
+ if (bare.startsWith('naddr1')) return normalise(naddrToAddr(bare))
108
+ if (bare.startsWith('nevent1')) return decodeNevent(bare).id.toLowerCase()
109
+ if (bare.startsWith('note1')) {
110
+ const { hrp, data } = bech32Decode(bare)
111
+ if (hrp !== 'note') return undefined
112
+ const hex = convertBits(data, 5, 8, false).map((b) => b.toString(16).padStart(2, '0')).join('')
113
+ return EVENT_ID.test(hex) ? hex : undefined
114
+ }
115
+ } catch {
116
+ return undefined
117
+ }
118
+ return undefined
119
+ }
120
+
121
+ /**
122
+ * The cards a message asks for, in the order the body first names them.
123
+ *
124
+ * `embeds` is the message's folded set; `blocks` its folded body as a render
125
+ * tree; `parts` its `part` pointers (§13.6.1). A value appears here only while
126
+ * the body names it — by a `nostr:` reference, or by an app link that
127
+ * `resolveLink` resolves to it (§7.7) — and only when no `part` names the
128
+ * same address, because the live block already stands for that object. Text in
129
+ * a code span names nothing (§13.1). Without `resolveLink` a link names nothing:
130
+ * resolving one needs the manifests and the relay, which this package does not hold.
131
+ *
132
+ * `none` entries are kept: they draw no card, but they still override the
133
+ * reader's own default for that value (as of 2026-10-13 Ship and Peek draw a
134
+ * reference alone on its line as its card; an `embed` replaces that). Filter
135
+ * them out to get the cards to draw.
136
+ */
137
+ export function cardsIn(embeds: readonly Embed[], blocks: readonly RenderBlock[], parts: readonly PartPointer[] = [], resolveLink?: LinkResolver): Embed[] {
138
+ if (embeds.length === 0) return []
139
+ const byValue = new Map(embeds.map((e) => [e.value, e]))
140
+ const withPart = new Set(parts.map((p) => normalise(p.address)).filter((v): v is string => !!v))
141
+ const out: Embed[] = []
142
+ const seen = new Set<string>()
143
+ const take = (value: string | undefined) => {
144
+ if (!value || seen.has(value) || withPart.has(value)) return
145
+ const embed = byValue.get(value)
146
+ if (!embed) return
147
+ seen.add(value)
148
+ out.push(embed)
149
+ }
150
+ // Adjacent plain runs are read as one text, so a link a mark splits in two is still one link.
151
+ const scan = (text: string) => {
152
+ if (!resolveLink || !text.includes('://')) return
153
+ for (const url of urlsIn(text)) {
154
+ const value = resolveLink(url)
155
+ if (value) take(normalise(value))
156
+ }
157
+ }
158
+ const walk = (bs: readonly RenderBlock[]) => {
159
+ for (const block of bs) {
160
+ if (block.type !== 'codeBlock') {
161
+ let text = ''
162
+ for (const run of block.inline ?? []) {
163
+ if (run.reference || run.marks.includes('code')) {
164
+ scan(text)
165
+ text = ''
166
+ if (run.reference) take(valueOfReference(run.reference))
167
+ } else text += run.text
168
+ }
169
+ scan(text)
170
+ }
171
+ if (block.children) walk(block.children)
172
+ }
173
+ }
174
+ walk(blocks)
175
+ return out
176
+ }
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.29.0'
50
+ export const PROTOCOL_VERSION = '0.31.0'
51
51
 
52
52
  export {
53
53
  // types
@@ -205,6 +205,10 @@ export {
205
205
  findBlock,
206
206
  listItemDepths,
207
207
  MAX_LIST_DEPTH,
208
+ listItemChecked,
209
+ CALLOUT_TONES,
210
+ type CalloutTone,
211
+ calloutTone,
208
212
  inlineTextOf,
209
213
  documentText,
210
214
  } from './blocks.js'
@@ -226,6 +230,7 @@ export {
226
230
  export {
227
231
  markerTextToBlockDocument,
228
232
  blockDocumentToMarkerText,
233
+ type DescriptionTextOptions,
229
234
  } from './bridge-content.js'
230
235
 
231
236
  export {
@@ -254,6 +259,7 @@ export {
254
259
  resolveBlockAnchor,
255
260
  resolvePart,
256
261
  } from './anchors.js'
262
+ export { type Embed, type EmbedLayout, type LinkResolver, EMBED_TAG, cardsIn, embedTag, embedsOf } from './embeds.js'
257
263
  export {
258
264
  type BlossomVerb,
259
265
  type Imeta,
package/src/render.ts CHANGED
@@ -36,7 +36,7 @@ import {
36
36
  parseBodySegments,
37
37
  parseInlineMarks,
38
38
  } from './content.js'
39
- import { type Block, type BlockDocument, parseBlockDocument, inlineTextOf, listItemDepths } from './blocks.js'
39
+ import { type Block, type BlockDocument, type CalloutTone, parseBlockDocument, inlineTextOf, listItemDepths, listItemChecked, calloutTone } from './blocks.js'
40
40
  import type { SignedEvent } from './events.js'
41
41
 
42
42
  /** A run of text and the marks on it. Nothing here needs escaping; it is text. */
@@ -79,6 +79,16 @@ export interface RenderBlock {
79
79
  * them nested, and numbering each level from 1, is the reader's.
80
80
  */
81
81
  indent?: number
82
+ /**
83
+ * A checklist item's tick (§13.3, RIC-19): `true` or `false` on a checklist
84
+ * item, absent on a plain one — `attrs.checked` as `listItemChecked` reads it.
85
+ */
86
+ checked?: boolean
87
+ /**
88
+ * A callout's tone (§13.3, RIC-19), absent on a plain quote — `attrs.tone` as
89
+ * `calloutTone` reads it, so an unknown tone is already `note` here.
90
+ */
91
+ tone?: CalloutTone
82
92
  attrs?: Record<string, unknown>
83
93
  /** What the document actually called it, when `type` is `'unknown'`. */
84
94
  typeName?: string
@@ -213,6 +223,10 @@ function blockFromDocument(block: Block): RenderBlock {
213
223
  if (block.type === 'codeBlock' && typeof language === 'string') out.language = language
214
224
  const start = block.attrs?.start
215
225
  if (block.type === 'orderedList' && typeof start === 'number' && start > 1) out.start = start
226
+ const checked = block.type === 'listItem' ? listItemChecked(block) : undefined
227
+ if (checked !== undefined) out.checked = checked
228
+ const tone = block.type === 'blockquote' ? calloutTone(block) : undefined
229
+ if (tone) out.tone = tone
216
230
 
217
231
  if (Array.isArray(block.content)) {
218
232
  if (isInlineRun(block.content)) {