@estiva-app/protocol 0.10.0 → 0.11.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 CHANGED
@@ -4,6 +4,36 @@ 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.11.0 — 2026-09-03
8
+
9
+ **Wire behaviour: unchanged.** No builder, tag layout, id computation or
10
+ signature input moved. This adds a reader for a tag SPEC §13.6 defines, and
11
+ nothing here writes one.
12
+
13
+ - **New: `anchors.ts` — a comment anchored to one block, SPEC §13.6.**
14
+ `BLOCK_ANCHOR_TAG`, `blockAnchorOf`, `resolveBlockAnchor`, and the
15
+ `BlockAnchor` union.
16
+
17
+ **`resolveBlockAnchor` returns which of four states an anchor is in, rather
18
+ than a block or `undefined`**, and that shape is the point. §13.6 requires a
19
+ reader to distinguish *unanchored*, *resolved*, *unaddressable* and
20
+ *detached*, because the pair that matters — detached and unanchored — render
21
+ identically and mean opposite things: a remark about a paragraph somebody
22
+ deleted, versus a remark about the whole object. A signature that lets a
23
+ caller collapse them is a signature that invites the defect.
24
+
25
+ Control: making `detached` return `unanchored` fails exactly the two tests
26
+ written to catch it.
27
+
28
+ - **`unaddressable` is its own state, not a kind of detachment.** Marker text
29
+ has no addressable sub-unit (§13.1), so an anchor against it never resolves
30
+ and nothing was deleted. A reader saying "that paragraph is gone" about a
31
+ marker-text description is wrong twice over.
32
+
33
+ - **A body that claims `blocks` and does not parse is `unaddressable`, not an
34
+ exception.** It has no parts either, and a reader that throws renders nothing
35
+ at all.
36
+
7
37
  ## 0.10.0 — 2026-09-02
8
38
 
9
39
  **Wire behaviour: unchanged.** No builder, tag layout, id computation or
@@ -0,0 +1,69 @@
1
+ /**
2
+ * A comment anchored to one block — SPEC §13.6, and RFC 0.4 §6's answer.
3
+ *
4
+ * The address says which object; a `block` tag says which part of it. That much
5
+ * is two lines. **The reason this is a module rather than two lines is the
6
+ * unhappy path**: an anchor outlives the thing it points at, and the ways it
7
+ * stops resolving are not the same as each other.
8
+ *
9
+ * §13.6 requires a reader to distinguish four outcomes, and the one that
10
+ * matters is `detached` versus `unanchored`. They render identically if you let
11
+ * them and they mean opposite things — one is a remark about the object, the
12
+ * other a remark about a paragraph somebody has since deleted. A reader that
13
+ * collapses them silently converts the second into the first, and nothing
14
+ * reports it.
15
+ *
16
+ * So {@link resolveBlockAnchor} returns which of the four it is, rather than a
17
+ * block or `undefined`. A caller that wants to be careless has to work at it.
18
+ */
19
+ import { type Block } from './blocks.js';
20
+ import type { ContentFormat } from './render.js';
21
+ /** The tag SPEC §13.6 defines. */
22
+ export declare const BLOCK_ANCHOR_TAG = "block";
23
+ /**
24
+ * What an anchor resolved to.
25
+ *
26
+ * A discriminated union on purpose: the four states are not degrees of success,
27
+ * and a caller that treats "no anchor" and "the block is gone" as one thing has
28
+ * the defect §13.6 is about.
29
+ */
30
+ export type BlockAnchor =
31
+ /** The comment carries no `block` tag. It is about the whole object. */
32
+ {
33
+ state: 'unanchored';
34
+ }
35
+ /** The tag names a block that is present. */
36
+ | {
37
+ state: 'resolved';
38
+ id: string;
39
+ block: Block;
40
+ }
41
+ /**
42
+ * The body is not a block document, so it has no parts to point at.
43
+ *
44
+ * Marker text has no addressable sub-unit (§13.1), so this is permanent for
45
+ * that body rather than a failure — it is what two content models means.
46
+ */
47
+ | {
48
+ state: 'unaddressable';
49
+ id: string;
50
+ }
51
+ /** The tag names a block that is no longer in the document. */
52
+ | {
53
+ state: 'detached';
54
+ id: string;
55
+ };
56
+ /** The block id a comment anchors to, or `undefined` when it anchors to none. */
57
+ export declare function blockAnchorOf(event: {
58
+ tags: string[][];
59
+ }): string | undefined;
60
+ /**
61
+ * Which of §13.6's four states an anchor is in, against the body as it is now.
62
+ *
63
+ * `format` comes from the event carrying the *body* — `contentFormatOf` — and
64
+ * never from inspecting `value` (§13.4). Passing `'blocks'` for a body that
65
+ * does not parse yields `unaddressable` rather than throwing: a mis-tagged body
66
+ * has no parts either, and a reader that throws renders nothing at all.
67
+ */
68
+ export declare function resolveBlockAnchor(id: string | undefined, value: string, format: ContentFormat): BlockAnchor;
69
+ //# sourceMappingURL=anchors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"anchors.d.ts","sourceRoot":"","sources":["../src/anchors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,KAAK,KAAK,EAAqD,MAAM,aAAa,CAAA;AAC3F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,kCAAkC;AAClC,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC;;;;;;GAMG;AACH,MAAM,MAAM,WAAW;AACrB,wEAAwE;AACtE;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE;AACzB,6CAA6C;GAC3C;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE;AACjD;;;;;GAKG;GACD;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AACxC,+DAA+D;GAC7D;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAA;AAErC,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CAG7E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,aAAa,GACpB,WAAW,CAWb"}
@@ -0,0 +1,50 @@
1
+ /**
2
+ * A comment anchored to one block — SPEC §13.6, and RFC 0.4 §6's answer.
3
+ *
4
+ * The address says which object; a `block` tag says which part of it. That much
5
+ * is two lines. **The reason this is a module rather than two lines is the
6
+ * unhappy path**: an anchor outlives the thing it points at, and the ways it
7
+ * stops resolving are not the same as each other.
8
+ *
9
+ * §13.6 requires a reader to distinguish four outcomes, and the one that
10
+ * matters is `detached` versus `unanchored`. They render identically if you let
11
+ * them and they mean opposite things — one is a remark about the object, the
12
+ * other a remark about a paragraph somebody has since deleted. A reader that
13
+ * collapses them silently converts the second into the first, and nothing
14
+ * reports it.
15
+ *
16
+ * So {@link resolveBlockAnchor} returns which of the four it is, rather than a
17
+ * block or `undefined`. A caller that wants to be careless has to work at it.
18
+ */
19
+ import { findBlock, parseBlockDocument } from './blocks.js';
20
+ /** The tag SPEC §13.6 defines. */
21
+ export const BLOCK_ANCHOR_TAG = 'block';
22
+ /** The block id a comment anchors to, or `undefined` when it anchors to none. */
23
+ export function blockAnchorOf(event) {
24
+ const id = event.tags.find((t) => t[0] === BLOCK_ANCHOR_TAG)?.[1];
25
+ return id === undefined || id === '' ? undefined : id;
26
+ }
27
+ /**
28
+ * Which of §13.6's four states an anchor is in, against the body as it is now.
29
+ *
30
+ * `format` comes from the event carrying the *body* — `contentFormatOf` — and
31
+ * never from inspecting `value` (§13.4). Passing `'blocks'` for a body that
32
+ * does not parse yields `unaddressable` rather than throwing: a mis-tagged body
33
+ * has no parts either, and a reader that throws renders nothing at all.
34
+ */
35
+ export function resolveBlockAnchor(id, value, format) {
36
+ if (id === undefined || id === '')
37
+ return { state: 'unanchored' };
38
+ if (format !== 'blocks')
39
+ return { state: 'unaddressable', id };
40
+ let document;
41
+ try {
42
+ document = parseBlockDocument(value);
43
+ }
44
+ catch {
45
+ return { state: 'unaddressable', id };
46
+ }
47
+ const block = findBlock(document, id);
48
+ return block ? { state: 'resolved', id, block } : { state: 'detached', id };
49
+ }
50
+ //# sourceMappingURL=anchors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"anchors.js","sourceRoot":"","sources":["../src/anchors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAkC,SAAS,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAG3F,kCAAkC;AAClC,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAwBvC,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,KAA2B;IACvD,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IACjE,OAAO,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAA;AACvD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,EAAsB,EACtB,KAAa,EACb,MAAqB;IAErB,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAA;IACjE,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,EAAE,EAAE,CAAA;IAC9D,IAAI,QAAuB,CAAA;IAC3B,IAAI,CAAC;QACH,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,EAAE,EAAE,CAAA;IACvC,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;IACrC,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAA;AAC7E,CAAC"}
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.10.0";
49
+ export declare const PROTOCOL_VERSION = "0.11.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';
@@ -58,4 +58,5 @@ export { type InlineMark, type InlineMarkSpan, type BodySegment, type InlineMark
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
59
  export { type RenderInline, type RenderBlock, type RenderFormat, type ContentFormat, CONTENT_FORMAT_TAG, BLOCK_DOCUMENT_FORMAT, contentFormatOf, toRenderTree, renderTreeText, } from './render.js';
60
60
  export { markerTextToBlockDocument, blockDocumentToMarkerText, } from './bridge-content.js';
61
+ export { type BlockAnchor, BLOCK_ANCHOR_TAG, blockAnchorOf, resolveBlockAnchor, } from './anchors.js';
61
62
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH;;4EAE4E;AAC5E,eAAO,MAAM,gBAAgB,WAAW,CAAA;AAExC,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,KAAK,aAAa,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EACL,KAAK,WAAW,EAChB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,GACnB,MAAM,cAAc,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.10.0';
49
+ export const PROTOCOL_VERSION = '0.11.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,
@@ -64,4 +64,5 @@ export { parseInlineMarks, wrapInlineMarks, parseBodySegments, stripInlineFormat
64
64
  export { KNOWN_BLOCK_TYPES, BlockDocumentError, validateBlockDocument, parseBlockDocument, serializeBlockDocument, newBlockId, assignMissingBlockIds, blockIds, findBlock, inlineTextOf, documentText, } from './blocks.js';
65
65
  export { CONTENT_FORMAT_TAG, BLOCK_DOCUMENT_FORMAT, contentFormatOf, toRenderTree, renderTreeText, } from './render.js';
66
66
  export { markerTextToBlockDocument, blockDocumentToMarkerText, } from './bridge-content.js';
67
+ export { BLOCK_ANCHOR_TAG, blockAnchorOf, resolveBlockAnchor, } from './anchors.js';
67
68
  //# 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,QAAQ,CAAA;AAExC,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,EAKL,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH;;4EAE4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAA;AAExC,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,EAKL,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAEL,gBAAgB,EAChB,aAAa,EACb,kBAAkB,GACnB,MAAM,cAAc,CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/protocol",
3
- "version": "0.10.0",
3
+ "version": "0.11.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/anchors.ts ADDED
@@ -0,0 +1,76 @@
1
+ /**
2
+ * A comment anchored to one block — SPEC §13.6, and RFC 0.4 §6's answer.
3
+ *
4
+ * The address says which object; a `block` tag says which part of it. That much
5
+ * is two lines. **The reason this is a module rather than two lines is the
6
+ * unhappy path**: an anchor outlives the thing it points at, and the ways it
7
+ * stops resolving are not the same as each other.
8
+ *
9
+ * §13.6 requires a reader to distinguish four outcomes, and the one that
10
+ * matters is `detached` versus `unanchored`. They render identically if you let
11
+ * them and they mean opposite things — one is a remark about the object, the
12
+ * other a remark about a paragraph somebody has since deleted. A reader that
13
+ * collapses them silently converts the second into the first, and nothing
14
+ * reports it.
15
+ *
16
+ * So {@link resolveBlockAnchor} returns which of the four it is, rather than a
17
+ * block or `undefined`. A caller that wants to be careless has to work at it.
18
+ */
19
+ import { type Block, type BlockDocument, findBlock, parseBlockDocument } from './blocks.js'
20
+ import type { ContentFormat } from './render.js'
21
+
22
+ /** The tag SPEC §13.6 defines. */
23
+ export const BLOCK_ANCHOR_TAG = 'block'
24
+
25
+ /**
26
+ * What an anchor resolved to.
27
+ *
28
+ * A discriminated union on purpose: the four states are not degrees of success,
29
+ * and a caller that treats "no anchor" and "the block is gone" as one thing has
30
+ * the defect §13.6 is about.
31
+ */
32
+ export type BlockAnchor =
33
+ /** The comment carries no `block` tag. It is about the whole object. */
34
+ | { state: 'unanchored' }
35
+ /** The tag names a block that is present. */
36
+ | { state: 'resolved'; id: string; block: Block }
37
+ /**
38
+ * The body is not a block document, so it has no parts to point at.
39
+ *
40
+ * Marker text has no addressable sub-unit (§13.1), so this is permanent for
41
+ * that body rather than a failure — it is what two content models means.
42
+ */
43
+ | { state: 'unaddressable'; id: string }
44
+ /** The tag names a block that is no longer in the document. */
45
+ | { state: 'detached'; id: string }
46
+
47
+ /** The block id a comment anchors to, or `undefined` when it anchors to none. */
48
+ export function blockAnchorOf(event: { tags: string[][] }): string | undefined {
49
+ const id = event.tags.find((t) => t[0] === BLOCK_ANCHOR_TAG)?.[1]
50
+ return id === undefined || id === '' ? undefined : id
51
+ }
52
+
53
+ /**
54
+ * Which of §13.6's four states an anchor is in, against the body as it is now.
55
+ *
56
+ * `format` comes from the event carrying the *body* — `contentFormatOf` — and
57
+ * never from inspecting `value` (§13.4). Passing `'blocks'` for a body that
58
+ * does not parse yields `unaddressable` rather than throwing: a mis-tagged body
59
+ * has no parts either, and a reader that throws renders nothing at all.
60
+ */
61
+ export function resolveBlockAnchor(
62
+ id: string | undefined,
63
+ value: string,
64
+ format: ContentFormat,
65
+ ): BlockAnchor {
66
+ if (id === undefined || id === '') return { state: 'unanchored' }
67
+ if (format !== 'blocks') return { state: 'unaddressable', id }
68
+ let document: BlockDocument
69
+ try {
70
+ document = parseBlockDocument(value)
71
+ } catch {
72
+ return { state: 'unaddressable', id }
73
+ }
74
+ const block = findBlock(document, id)
75
+ return block ? { state: 'resolved', id, block } : { state: 'detached', id }
76
+ }
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.10.0'
50
+ export const PROTOCOL_VERSION = '0.11.0'
51
51
 
52
52
  export {
53
53
  // types
@@ -212,3 +212,10 @@ export {
212
212
  markerTextToBlockDocument,
213
213
  blockDocumentToMarkerText,
214
214
  } from './bridge-content.js'
215
+
216
+ export {
217
+ type BlockAnchor,
218
+ BLOCK_ANCHOR_TAG,
219
+ blockAnchorOf,
220
+ resolveBlockAnchor,
221
+ } from './anchors.js'