@estiva-app/protocol 0.7.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.
- package/CHANGELOG.md +39 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/render.d.ts +77 -0
- package/dist/render.d.ts.map +1 -0
- package/dist/render.js +162 -0
- package/dist/render.js.map +1 -0
- package/package.json +1 -1
- package/src/index.ts +9 -1
- package/src/render.ts +203 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,45 @@ Every entry answers the wire question explicitly, including when the answer is
|
|
|
4
4
|
nothing (ADR 0002 §4b). A change to the bytes an app publishes is a MAJOR — in
|
|
5
5
|
`0.x`, a MINOR — even when no TypeScript signature moved.
|
|
6
6
|
|
|
7
|
+
## 0.8.0 — 2026-09-02
|
|
8
|
+
|
|
9
|
+
**Wire behaviour: unchanged.** No builder, tag layout, id computation or
|
|
10
|
+
signature input moved. This release adds a resolver, and a resolver reads what
|
|
11
|
+
somebody else published.
|
|
12
|
+
|
|
13
|
+
- **New: `render.ts` — one resolved tree, whichever model the body is in.**
|
|
14
|
+
`toRenderTree(value, format)` and `renderTreeText`. Marker text and a block
|
|
15
|
+
document both become the same `RenderBlock[]`, so a consumer writes one
|
|
16
|
+
mapper instead of two, and a block document's ids survive into it while
|
|
17
|
+
marker text correctly has none.
|
|
18
|
+
|
|
19
|
+
**This is what SPEC §13.5's "safe by construction" means in practice.** The
|
|
20
|
+
safety is not a component — it is that an app is never handed a string it has
|
|
21
|
+
to interpret. Marks are decided, blocks are decided, and there is nothing
|
|
22
|
+
left to parse, so an app that maps this tree *cannot* accidentally render
|
|
23
|
+
markup. There is a corpus test asserting every character of output came from
|
|
24
|
+
the input; making the resolver append four characters fails 4 tests.
|
|
25
|
+
|
|
26
|
+
- **A tree rather than a shared component, and not for the reason the ticket
|
|
27
|
+
said.** RIC-6 justified it as "Ship is vanilla `h()` and Peek is React". That
|
|
28
|
+
was true when the ticket was written and is no longer: Ship's UI is React +
|
|
29
|
+
Vite and both apps already depend on `@estiva-app/ui`, so a shared component
|
|
30
|
+
was available. It is still a tree, for a better reason — **how rich text
|
|
31
|
+
looks is the consumer's**, which is RFC 0.4 §13.1's rule for projections and
|
|
32
|
+
SPEC §10's line about sharing the wire and never the interpretation. A shared
|
|
33
|
+
component would make Ship and Peek look alike by construction, which nobody
|
|
34
|
+
asked for.
|
|
35
|
+
|
|
36
|
+
- **`'unknown'` is handled here rather than in each consumer.** A format
|
|
37
|
+
declared after this code was written becomes one unmarked paragraph of the
|
|
38
|
+
raw value, which §13.5 says is conformant. Leaving that to consumers is how
|
|
39
|
+
one of them ends up guessing.
|
|
40
|
+
|
|
41
|
+
- **A mis-tagged body degrades instead of throwing.** A `'blocks'` value that
|
|
42
|
+
is not a document renders as its own text. A reader that throws renders an
|
|
43
|
+
empty field, and an empty field is indistinguishable from a description
|
|
44
|
+
nobody wrote.
|
|
45
|
+
|
|
7
46
|
## 0.7.0 — 2026-09-02
|
|
8
47
|
|
|
9
48
|
**Wire behaviour: unchanged.** No builder, tag layout, id computation or
|
package/dist/index.d.ts
CHANGED
|
@@ -46,7 +46,7 @@
|
|
|
46
46
|
/** Bumped by hand with the version in package.json — `test/version.test.ts`
|
|
47
47
|
* pins the two together. It exists so "the upgrade reached the app" can be
|
|
48
48
|
* checked by grepping a built bundle rather than by trusting a lockfile. */
|
|
49
|
-
export declare const PROTOCOL_VERSION = "0.
|
|
49
|
+
export declare const PROTOCOL_VERSION = "0.8.0";
|
|
50
50
|
export { type NostrTag, type UnsignedEvent, type SignedEvent, type Profile, type ThreadRef, type ChannelVisibility, type ChannelKind, type MemberRole, type Label, type ResolutionAction, KIND, MAX_EMOJI_CHARS, MAX_MESSAGE_BYTES, MAX_MENTIONS, MAX_RATIONALE_BYTES, RELAY_AUTH_TOLERANCE_SECS, ASSERTION_SUBTYPE, computeEventId, toNostrSeconds, canonicalChannelName, threadTags, addr, relayAuthUrl, buildProfile, parseProfile, buildCreateChannel, buildDeleteChannel, buildEditChannelMetadata, buildAddMember, buildReaction, buildDeletion, buildMessage, buildResolution, buildFile, buildComponent, buildHighlight, buildUnsignedRelayAuthEvent, } from './events.js';
|
|
51
51
|
export { type AddressPointer, type EventPointer, encodeNevent, decodeNevent, convertBits, bech32Encode, bech32Decode, encodeNaddr, decodeNaddr, pointerToAddress, addressToPointer, addrToNaddr, naddrToAddr, referenceToPointer, NADDR_RE, findNaddrs, stripNaddrs, } from './nip19.js';
|
|
52
52
|
export { type AuthEventArgs, TIMESTAMP_TOLERANCE_SECS, normalizeUrl, buildUnsignedAuthEvent, base64, authorizationHeaderFor, authorizationHeader, } from './nip98.js';
|
|
@@ -56,4 +56,5 @@ export { type RelayState, type SocketLike, type RelayCredential, type LiveRelayO
|
|
|
56
56
|
export { type ChannelEventHandler, type ChannelSubscription, type ChannelSubscriptions, createChannelSubscriptions, } from './subscriptions.js';
|
|
57
57
|
export { type InlineMark, type InlineMarkSpan, type BodySegment, type InlineMarkNode, type InlineTextNode, parseInlineMarks, wrapInlineMarks, parseBodySegments, stripInlineFormatting, markersToInlineNodes, inlineNodesToMarkers, inlineNodesToText, } from './content.js';
|
|
58
58
|
export { type Block, type BlockDocument, type KnownBlockType, KNOWN_BLOCK_TYPES, BlockDocumentError, validateBlockDocument, parseBlockDocument, serializeBlockDocument, newBlockId, assignMissingBlockIds, blockIds, findBlock, inlineTextOf, documentText, } from './blocks.js';
|
|
59
|
+
export { type RenderInline, type RenderBlock, type RenderFormat, toRenderTree, renderTreeText, } from './render.js';
|
|
59
60
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH;;4EAE4E;AAC5E,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,gBAAgB,EAErB,IAAI,EACJ,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EAEjB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,IAAI,EACJ,YAAY,EAEZ,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,eAAe,EACf,SAAS,EACT,cAAc,EACd,cAAc,EACd,2BAA2B,GAC5B,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,KAAK,aAAa,EAClB,wBAAwB,EACxB,YAAY,EACZ,sBAAsB,EACtB,MAAM,EACN,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,KAAK,MAAM,EACX,KAAK,UAAU,EACf,mBAAmB,EACnB,SAAS,EACT,eAAe,GAChB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,GACN,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,cAAc,EACd,UAAU,EACV,eAAe,GAChB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,UAAU,EACV,qBAAqB,EACrB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,YAAY,GACb,MAAM,aAAa,CAAA"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH;;4EAE4E;AAC5E,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,gBAAgB,EAErB,IAAI,EACJ,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EAEjB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,IAAI,EACJ,YAAY,EAEZ,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,eAAe,EACf,SAAS,EACT,cAAc,EACd,cAAc,EACd,2BAA2B,GAC5B,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,KAAK,aAAa,EAClB,wBAAwB,EACxB,YAAY,EACZ,sBAAsB,EACtB,MAAM,EACN,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,KAAK,MAAM,EACX,KAAK,UAAU,EACf,mBAAmB,EACnB,SAAS,EACT,eAAe,GAChB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,GACN,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,cAAc,EACd,UAAU,EACV,eAAe,GAChB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,UAAU,EACV,qBAAqB,EACrB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,YAAY,GACb,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAA"}
|
package/dist/index.js
CHANGED
|
@@ -46,7 +46,7 @@
|
|
|
46
46
|
/** Bumped by hand with the version in package.json — `test/version.test.ts`
|
|
47
47
|
* pins the two together. It exists so "the upgrade reached the app" can be
|
|
48
48
|
* checked by grepping a built bundle rather than by trusting a lockfile. */
|
|
49
|
-
export const PROTOCOL_VERSION = '0.
|
|
49
|
+
export const PROTOCOL_VERSION = '0.8.0';
|
|
50
50
|
export {
|
|
51
51
|
// constants
|
|
52
52
|
KIND, MAX_EMOJI_CHARS, MAX_MESSAGE_BYTES, MAX_MENTIONS, MAX_RATIONALE_BYTES, RELAY_AUTH_TOLERANCE_SECS, ASSERTION_SUBTYPE,
|
|
@@ -62,4 +62,5 @@ export { toWebSocketUrl, parseFrame, createLiveRelay, } from './live.js';
|
|
|
62
62
|
export { createChannelSubscriptions, } from './subscriptions.js';
|
|
63
63
|
export { parseInlineMarks, wrapInlineMarks, parseBodySegments, stripInlineFormatting, markersToInlineNodes, inlineNodesToMarkers, inlineNodesToText, } from './content.js';
|
|
64
64
|
export { KNOWN_BLOCK_TYPES, BlockDocumentError, validateBlockDocument, parseBlockDocument, serializeBlockDocument, newBlockId, assignMissingBlockIds, blockIds, findBlock, inlineTextOf, documentText, } from './blocks.js';
|
|
65
|
+
export { toRenderTree, renderTreeText, } from './render.js';
|
|
65
66
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH;;4EAE4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEvC,OAAO;AAYL,YAAY;AACZ,IAAI,EACJ,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB;AACjB,8CAA8C;AAC9C,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,IAAI,EACJ,YAAY;AACZ,WAAW;AACX,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,eAAe,EACf,SAAS,EACT,cAAc,EACd,cAAc,EACd,2BAA2B,GAC5B,MAAM,aAAa,CAAA;AAEpB,OAAO,EAGL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,YAAY,CAAA;AAEnB,OAAO,EAEL,wBAAwB,EACxB,YAAY,EACZ,sBAAsB,EACtB,MAAM,EACN,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAGL,mBAAmB,EACnB,SAAS,EACT,eAAe,GAChB,MAAM,WAAW,CAAA;AAElB,OAAO,EAOL,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,GACN,MAAM,aAAa,CAAA;AAEpB,OAAO,EAOL,cAAc,EACd,UAAU,EACV,eAAe,GAChB,MAAM,WAAW,CAAA;AAElB,OAAO,EAIL,0BAA0B,GAC3B,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAML,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,OAAO,EAIL,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,UAAU,EACV,qBAAqB,EACrB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,YAAY,GACb,MAAM,aAAa,CAAA"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH;;4EAE4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEvC,OAAO;AAYL,YAAY;AACZ,IAAI,EACJ,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB;AACjB,8CAA8C;AAC9C,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,IAAI,EACJ,YAAY;AACZ,WAAW;AACX,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,eAAe,EACf,SAAS,EACT,cAAc,EACd,cAAc,EACd,2BAA2B,GAC5B,MAAM,aAAa,CAAA;AAEpB,OAAO,EAGL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,YAAY,CAAA;AAEnB,OAAO,EAEL,wBAAwB,EACxB,YAAY,EACZ,sBAAsB,EACtB,MAAM,EACN,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAGL,mBAAmB,EACnB,SAAS,EACT,eAAe,GAChB,MAAM,WAAW,CAAA;AAElB,OAAO,EAOL,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,GACN,MAAM,aAAa,CAAA;AAEpB,OAAO,EAOL,cAAc,EACd,UAAU,EACV,eAAe,GAChB,MAAM,WAAW,CAAA;AAElB,OAAO,EAIL,0BAA0B,GAC3B,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAML,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,OAAO,EAIL,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,UAAU,EACV,qBAAqB,EACrB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,YAAY,GACb,MAAM,aAAa,CAAA;AAEpB,OAAO,EAIL,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAA"}
|
package/dist/render.d.ts
ADDED
|
@@ -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.
|
|
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/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.
|
|
50
|
+
export const PROTOCOL_VERSION = '0.8.0'
|
|
51
51
|
|
|
52
52
|
export {
|
|
53
53
|
// types
|
|
@@ -195,3 +195,11 @@ export {
|
|
|
195
195
|
inlineTextOf,
|
|
196
196
|
documentText,
|
|
197
197
|
} from './blocks.js'
|
|
198
|
+
|
|
199
|
+
export {
|
|
200
|
+
type RenderInline,
|
|
201
|
+
type RenderBlock,
|
|
202
|
+
type RenderFormat,
|
|
203
|
+
toRenderTree,
|
|
204
|
+
renderTreeText,
|
|
205
|
+
} from './render.js'
|
package/src/render.ts
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
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 {
|
|
33
|
+
type BodySegment,
|
|
34
|
+
type InlineMark,
|
|
35
|
+
type InlineTextNode,
|
|
36
|
+
parseBodySegments,
|
|
37
|
+
parseInlineMarks,
|
|
38
|
+
} from './content.js'
|
|
39
|
+
import { type Block, type BlockDocument, parseBlockDocument, inlineTextOf } from './blocks.js'
|
|
40
|
+
|
|
41
|
+
/** A run of text and the marks on it. Nothing here needs escaping; it is text. */
|
|
42
|
+
export interface RenderInline {
|
|
43
|
+
text: string
|
|
44
|
+
marks: InlineMark[]
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* A resolved block.
|
|
49
|
+
*
|
|
50
|
+
* **A `\n` inside `inline` text is a line break**, in both content models — it
|
|
51
|
+
* is how a marker-text paragraph carries its lines, and it keeps a consumer
|
|
52
|
+
* from needing two rules. Splitting on it is the consumer's whole obligation.
|
|
53
|
+
*/
|
|
54
|
+
export interface RenderBlock {
|
|
55
|
+
type:
|
|
56
|
+
| 'paragraph' | 'heading' | 'bulletList' | 'orderedList' | 'listItem'
|
|
57
|
+
| 'blockquote' | 'codeBlock' | 'table' | 'horizontalRule'
|
|
58
|
+
| 'attachment' | 'widget' | 'unknown'
|
|
59
|
+
/** The block's address, from a block document. Marker text has no addressable
|
|
60
|
+
* sub-unit (§13.1), so it is absent — which is the difference that matters. */
|
|
61
|
+
id?: string
|
|
62
|
+
level?: 1 | 2 | 3
|
|
63
|
+
language?: string
|
|
64
|
+
attrs?: Record<string, unknown>
|
|
65
|
+
/** What the document actually called it, when `type` is `'unknown'`. */
|
|
66
|
+
typeName?: string
|
|
67
|
+
inline?: RenderInline[]
|
|
68
|
+
children?: RenderBlock[]
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** The content models a body can be in — `contentFormatOf`'s three values. */
|
|
72
|
+
export type RenderFormat = 'marker' | 'blocks' | 'unknown'
|
|
73
|
+
|
|
74
|
+
const KNOWN: ReadonlySet<string> = new Set([
|
|
75
|
+
'paragraph', 'heading', 'bulletList', 'orderedList', 'listItem',
|
|
76
|
+
'blockquote', 'codeBlock', 'table', 'horizontalRule', 'attachment', 'widget',
|
|
77
|
+
])
|
|
78
|
+
|
|
79
|
+
const marksOf = (span: { bold?: boolean; italic?: boolean; underline?: boolean; code?: boolean }): InlineMark[] => {
|
|
80
|
+
const out: InlineMark[] = []
|
|
81
|
+
if (span.bold) out.push('bold')
|
|
82
|
+
if (span.italic) out.push('italic')
|
|
83
|
+
if (span.underline) out.push('underline')
|
|
84
|
+
if (span.code) out.push('code')
|
|
85
|
+
return out
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const inlineFromMarkers = (text: string): RenderInline[] =>
|
|
89
|
+
parseInlineMarks(text).map((s) => ({ text: s.text, marks: marksOf(s) }))
|
|
90
|
+
|
|
91
|
+
/** One inline run per line, joined by the `\n` the interface documents. */
|
|
92
|
+
const inlineFromLines = (lines: string[]): RenderInline[] => inlineFromMarkers(lines.join('\n'))
|
|
93
|
+
|
|
94
|
+
function blockFromSegment(seg: BodySegment): RenderBlock {
|
|
95
|
+
switch (seg.type) {
|
|
96
|
+
case 'heading':
|
|
97
|
+
return { type: 'heading', level: seg.level, inline: inlineFromMarkers(seg.text) }
|
|
98
|
+
case 'bullet':
|
|
99
|
+
return {
|
|
100
|
+
type: 'bulletList',
|
|
101
|
+
children: seg.items.map((item) => ({ type: 'listItem' as const, inline: inlineFromMarkers(item) })),
|
|
102
|
+
}
|
|
103
|
+
case 'numbered':
|
|
104
|
+
return {
|
|
105
|
+
type: 'orderedList',
|
|
106
|
+
children: seg.items.map((item) => ({ type: 'listItem' as const, inline: inlineFromMarkers(item) })),
|
|
107
|
+
}
|
|
108
|
+
case 'quote':
|
|
109
|
+
return { type: 'blockquote', inline: inlineFromLines(seg.lines) }
|
|
110
|
+
case 'code':
|
|
111
|
+
// A fence is literal by definition — its content is never mark-parsed.
|
|
112
|
+
return {
|
|
113
|
+
type: 'codeBlock',
|
|
114
|
+
...(seg.language ? { language: seg.language } : {}),
|
|
115
|
+
inline: [{ text: seg.lines.join('\n'), marks: [] }],
|
|
116
|
+
}
|
|
117
|
+
case 'text':
|
|
118
|
+
return { type: 'paragraph', inline: inlineFromLines(seg.lines) }
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
const isInlineRun = (content: unknown): content is InlineTextNode[] =>
|
|
123
|
+
Array.isArray(content) && content.every((n) => typeof n === 'object' && n !== null && (n as { type?: unknown }).type === 'text')
|
|
124
|
+
|
|
125
|
+
function blockFromDocument(block: Block): RenderBlock {
|
|
126
|
+
const known = KNOWN.has(block.type)
|
|
127
|
+
const out: RenderBlock = {
|
|
128
|
+
type: (known ? block.type : 'unknown') as RenderBlock['type'],
|
|
129
|
+
id: block.id,
|
|
130
|
+
...(known ? {} : { typeName: block.type }),
|
|
131
|
+
...(block.attrs ? { attrs: block.attrs } : {}),
|
|
132
|
+
}
|
|
133
|
+
const level = block.attrs?.level
|
|
134
|
+
if (block.type === 'heading' && (level === 1 || level === 2 || level === 3)) out.level = level
|
|
135
|
+
const language = block.attrs?.language
|
|
136
|
+
if (block.type === 'codeBlock' && typeof language === 'string') out.language = language
|
|
137
|
+
|
|
138
|
+
if (Array.isArray(block.content)) {
|
|
139
|
+
if (isInlineRun(block.content)) {
|
|
140
|
+
out.inline = block.content.map((node) => ({
|
|
141
|
+
text: node.text,
|
|
142
|
+
marks: (node.marks ?? []).map((m) => m.type),
|
|
143
|
+
}))
|
|
144
|
+
} else {
|
|
145
|
+
out.children = (block.content as Block[]).map(blockFromDocument)
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
/*
|
|
149
|
+
§13.3: a reader MUST render an unknown block's inline text and MUST NOT drop
|
|
150
|
+
it. A later version could nest content in a shape this code cannot walk, so
|
|
151
|
+
the fallback reads the text by shape rather than trusting the walk above to
|
|
152
|
+
have found it.
|
|
153
|
+
*/
|
|
154
|
+
if (!known && !out.inline && !out.children) {
|
|
155
|
+
const text = inlineTextOf(block)
|
|
156
|
+
if (text) out.inline = [{ text, marks: [] }]
|
|
157
|
+
}
|
|
158
|
+
return out
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* The body, resolved.
|
|
163
|
+
*
|
|
164
|
+
* `format` comes from the event's `content-format` tag — `contentFormatOf` in
|
|
165
|
+
* `@estiva-app/interop`. Do not infer it from `value`: §13.4 forbids it, and a
|
|
166
|
+
* legacy description that happens to begin with `{` is the case that proves
|
|
167
|
+
* why.
|
|
168
|
+
*
|
|
169
|
+
* A body in an unparseable state never throws here. A `'blocks'` value that is
|
|
170
|
+
* not a document degrades to one unmarked paragraph — the same outcome as
|
|
171
|
+
* `'unknown'` — because a reader that throws renders nothing at all, and a
|
|
172
|
+
* description that is present is better shown as its own text than as an empty
|
|
173
|
+
* field.
|
|
174
|
+
*/
|
|
175
|
+
export function toRenderTree(value: string, format: RenderFormat): RenderBlock[] {
|
|
176
|
+
if (format === 'unknown') return plainParagraph(value)
|
|
177
|
+
if (format === 'blocks') {
|
|
178
|
+
let doc: BlockDocument
|
|
179
|
+
try {
|
|
180
|
+
doc = parseBlockDocument(value)
|
|
181
|
+
} catch {
|
|
182
|
+
return plainParagraph(value)
|
|
183
|
+
}
|
|
184
|
+
return doc.content.map(blockFromDocument)
|
|
185
|
+
}
|
|
186
|
+
return parseBodySegments(value).map(blockFromSegment)
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
function plainParagraph(value: string): RenderBlock[] {
|
|
190
|
+
return value === '' ? [] : [{ type: 'paragraph', inline: [{ text: value, marks: [] }] }]
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** Every character a reader would see, for previews and search. */
|
|
194
|
+
export function renderTreeText(blocks: readonly RenderBlock[]): string {
|
|
195
|
+
return blocks
|
|
196
|
+
.map((b) => {
|
|
197
|
+
const own = (b.inline ?? []).map((i) => i.text).join('')
|
|
198
|
+
const kids = b.children ? renderTreeText(b.children) : ''
|
|
199
|
+
return [own, kids].filter((s) => s !== '').join('\n')
|
|
200
|
+
})
|
|
201
|
+
.filter((s) => s !== '')
|
|
202
|
+
.join('\n')
|
|
203
|
+
}
|