@liminis/editor 0.5.0 → 0.6.0

package/docs/markdown-pipeline.md

@@ -314,6 +314,219 @@ is called at each level. Removing either turns an authoring mistake into an
 infinite loop or unbounded recursion instead of a contained "circular
 transclusion"/"nested too deeply" indicator.
 
+## Block anchor badges (#122, widened by #124 and #127)
+
+A block anchor — a bare `^ULID` at its *definition* site, most commonly
+trailing an action-item checkbox (`- [ ] ... ^01M00VDX0S4JHMDNA7F776Y8R8`) —
+renders as a compact badge instead of the raw caret-plus-id text. This is
+presentation only: the underlying markdown, and the id itself, never change.
+It has no relationship to the `#^blockId` fragment inside `[[file#^id]]`
+above other than sharing a source convention — this section is about the
+anchor's own definition site, not a link's target.
+
+### `blockAnchor` is a new mdast node type, detected by a post-parse text split
+
+```ts
+{ type: 'blockAnchor', id: '01M00VDX0S4JHMDNA7F776Y8R8' }
+```
+
+Unlike the embed marker (`![[...]]`), a bare `^ULID` needs no tokenizer
+unlock — there is no bracket syntax to let through. Detection is therefore a
+**post-parse** pass (`splitTextNodeBlockAnchors`/`splitBlockAnchors` in
+`parse.ts`) walking already-typed mdast `text` nodes and splitting a matching
+run into its own `blockAnchor` node, mirroring `#17`'s
+`splitTextNodeEscapes`/`splitEscapedPunctuation` (including its decode-replay
+position-mapping machinery and the same conservative bail-out: if a text
+node's replayed decoding doesn't exactly reproduce `node.value` — e.g. a
+character reference is present — the whole run is left unsplit rather than
+risk a wrong split).
+
+Because this only ever inspects a `text` node's own `value`, it structurally
+cannot see into `inlineCode`, `code`, `inlineMath`, `wikiLink` or `wikiEmbed`
+node content — none of those are `text` nodes once mdast has typed them —
+which satisfies the code-span/fenced-code/math edge case and FR-006 for free,
+with no "protected ranges" pre-parse machinery required (unlike
+`substituteEmbedMarker` above, which needs that machinery only because it has
+to influence tokenization itself).
+
+The matcher also rejects a match whose leading `^` came from a backslash
+escape (`\^`) in the source, using the same `replayDecodeEscapes` output the
+decode-replay machinery above already computes. Without this check, an
+author who deliberately wrote `\^` before a ULID-shaped run to mean literal
+text — not an anchor — would still get a badge, and since the `blockAnchor`
+stringify handler always emits a bare, unescaped `^id`, saving would silently
+drop their backslash. This does not repair the pre-existing, unrelated gap
+that `^` sits outside `FORCE_ESCAPE_CHARS`: a bare `\^` with no adjacent
+ULID-shaped run still loses its backslash on round-trip today, anchor or
+not — see ADR-122's accepted limitations.
+
+The pass runs in `parseMarkdown`'s post-process sequence after
+`resolveWikiEmbeds`/`annotateEmphasisMarkers` — so it never sees wiki-link or
+embed target text — and immediately before `splitEscapedPunctuation` (which
+stays last), so that pass still sees, and can process, any escaped
+punctuation left in the anchor split's "before"/"after" text siblings.
+
+`stringify.ts`'s `blockAnchor` handler emits exactly `^` + the node's `id`,
+with no escaping — lossless by construction, the same way `wikiLink`/
+`wikiEmbed` are.
+
+### The detection rule: one universal position rule, every id form alike (#124, #127, #126)
+
+`findBlockAnchorMatches` in `parse.ts` applies a single rule at each
+unescaped `^`, left to right: any id the resolver and the wiki-link
+reference side already accept — ULID, raw-decimal snowflake ids, NanoID-style
+ids with `_`/`-`, mixed-case base62, UUID-shaped hyphenated ids, short
+alphanumeric ids — badges if and only if the caret starts a token (line-start
+or preceded by whitespace) and the captured id (`WIDE_ID_CHAR`, the same
+charset the wiki-link reference side and the resolver use) runs to end of
+line. This is the resolver's own regex (`liminis-app/src/main/fs.ts`,
+verveguy/liminis#1109) adopted verbatim, so badge and resolver agree by
+construction rather than by coincidence, for every id form with no
+carve-out. (At the time #124 shipped, `WIDE_ID_CHAR` was `[^\s\]#]+`; #127
+later narrowed it to also exclude `*`, matching a further narrowing the
+resolver itself picked up for `liminis#1114` — see below.)
+
+**This was not always one rule.** #124 originally split detection into two
+branches: ULID kept #122's original rule, unconstrained by position, while
+every other id form was gated by the position rule above. That carve-out
+existed because #122's own fixtures required a ULID to badge immediately
+after a wiki-link/emphasis run with no preceding space, and required a ULID
+followed by more prose on the same line to badge — shapes the resolver can
+never address, since it only ever matches an anchor definition running to
+end of line. #126 deleted the carve-out: those mid-line fixtures turned out
+to encode parser-robustness tests, not a product requirement, because
+production's actual mid-line ULID occurrences are wiki-link *references*
+(`[[file#^id]]`), parsed position-independently and unaffected by this
+change — not anchor *definitions*. A badged mid-line ULID was a promise
+`[[file#^id]]` could never keep, the same "UI says X, system does Y"
+disagreement #124 fixes, in the opposite direction. Deleting the carve-out
+was a pure removal, not a rewrite: Crockford Base32 (ULID's charset) is
+already a strict subset of the position rule's charset, so every ULID that
+already satisfied the position rule — plain or emphasis-wrapped, at line
+end — keeps badging unchanged; only mid-line ULIDs, and ULIDs immediately
+adjacent to a preceding sibling with zero intervening whitespace, stopped
+badging. See ADR-122's 2026-09-10 (#126) amendment for the full history,
+including the rejected minimum-length threshold and the residual this left
+(a caret with zero preceding whitespace, immediately after a wiki-link or
+emphasis/strong sibling, can never badge at any line position — not just
+mid-line).
+
+Widening the charset without position-gating was, and remains, rejected:
+`x^2`/`2^10`/`a ^ b` would badge as false positives, since nothing else
+bounds an undelimited charset match the way `[[...]]` brackets bound the
+wiki-link reference side's use of the same charset.
+
+A shared, cross-repo case table
+(`src/markdown/__tests__/blockAnchorCases.ts`, `BLOCK_ANCHOR_POSITION_CASES`)
+pins this rule's id/position behavior against the resolver's actual, merged
+`ANCHOR_LINE_PATTERN`, asserted in full by a single `it.each` in
+`parse.test.ts` — so a future divergence between the two repositories' rules
+fails a test instead of shipping as a live defect, the way both #124's and
+#126's own gaps originally did.
+
+The boundary checks may need to peek one character outside the current text
+node's own source span — into the surrounding normalized document text, one
+character before the node's start or from the node's end onward — since a
+preceding/following sibling (e.g. a wiki-link) has no character of its own
+for the matcher to inspect directly. This is equivalent to inspecting the
+sibling node and needs no AST traversal to do it.
+
+**A symmetric emphasis wrapper at line end (added by #127).**
+`**^a1b2c3**`, `__^a1b2c3__`, `*^a1b2c3*` and `_^a1b2c3_` all badge
+`a1b2c3` — matching `verveguy/liminis#1114`'s widened resolver, which
+accepts the same wrapped shape.
+
+When CommonMark parses `**^a1b2c3**` as real emphasis, the wrapper
+characters are consumed into the *parent* `strong`/`emphasis` node's
+position span — they never appear in the inner `text` node's own
+`decoded`/`value`. That has a useful structural consequence: a caret can
+only be adjacent to a *structural* wrapper marker when it is the first
+character of its own text node (`i === 0`), and a closer only when the id
+capture runs all the way to that same node's own end
+(`idEnd === decoded.length`) — outside those two positions, whatever
+wrapper-like characters are present are literal text left over from an
+unmatched delimiter run, already correctly rejected by the plain rule with
+no wrapper logic involved. Gating wrapper detection on both invariants
+means the extension is just two more raw-character peeks into the
+surrounding normalized text (`matchWrapperMarkerBefore` on the open side,
+an exact-string check on the close side), the same style the plain
+whitespace boundary above already uses — no need to pass the enclosing
+`strong`/`emphasis` node's type, marker, or position down through the tree
+walk.
+
+The wrapped id charset (`WRAPPED_ID_CHAR`, `[^\s\]#*]`) matches the
+resolver's actual wrapped-branch charset as implemented for `liminis#1114`
+(`ANCHOR_LINE_PATTERN`'s `[^\s\]#*]+?` wrapped-id group) — it excludes `*`
+but allows `_`, since `_` is a legitimate character in ids like
+`V1StGXR8_Z5jdHi6B-myT` (NanoID) and `snake_case_id`. `WIDE_ID_CHAR` (the
+unwrapped path) uses the same charset: the resolver's implemented pattern
+narrowed *both* its wrapped and unwrapped branches to exclude `*`, not just
+the wrapped one, so the two constants are currently identical — kept as
+separate names since they're independent knobs in the resolver's pattern
+that could diverge again. Neither excludes `_`: doing so would regress the
+NanoID-with-underscore case (`^V1StGXR8_Z5jdHi6B-myT`, #124/FR-004), and the
+resolver doesn't exclude it either.
+
+The closer must be the *exact same marker string* that opened it — not an
+independently optional match — so an asymmetric wrapper (`item **^<ULID>_`)
+is rejected outright rather than captured with a corrupted id, ULID or not
+(#126: there is no longer a position-free carve-out for it to fall back to).
+Wrapper forms other than `**`/`__`/`*`/`_` — triple emphasis (`***…***`),
+strikethrough (`~~…~~`), backtick-wrapped, and paren-wrapped — stay
+unhandled by design: `WRAPPER_MARKERS` only lists the four forms
+`liminis#1114`'s resolver pattern accepts. `squared *^2*` becomes a
+badged-and-resolved false anchor as a result of this widening — accepted
+deliberately, for the same reason a minimum-length floor was already
+rejected for `^100` in #124 (excluding it would also exclude legitimate
+short ids like `^a1b2c3`). See ADR-122's 2026-09-10 (#127) and 2026-09-10
+(#126) amendments.
+
+### The Lexical side: `BlockAnchorNode`, mirroring `FootnoteNode`
+
+`BlockAnchorNode` (`src/app/editor/nodes/BlockAnchorNode.tsx`) is an inline
+`DecoratorNode<JSX.Element>` carrying the id, a format bitmask, and
+strong/emphasis marker fields — the same shape as `FootnoteNode`, so an
+anchor sitting inside `**bold**`/`_italic_` still round-trips its original
+marker style rather than silently dropping it (the defect class already
+fixed once for other inline decorators, `#898`/`#908`). `BlockAnchorComponent`
+renders the actual badge: the full id is exposed via the native `title`
+tooltip on hover, and a click copies it via `navigator.clipboard.writeText`
+with brief "Copied" feedback — mirroring `CodeBlockPlugin.tsx`'s existing
+copy pattern, rather than a new interaction affordance (User Story 2/SC-003).
+
+`convertInlineNode` (`mdastToLexical.ts`) maps a `blockAnchor` mdast node to
+`$createBlockAnchorNode`; the reverse direction in `lexicalToMdast.ts` adds an
+`$isBlockAnchorNode` branch at every site that already special-cases
+`$isFootnoteNode` (`isHoistableConstruct`, `getMergeableFormat`,
+`resolveMarkers`, and each content-conversion call site) so a `BlockAnchorNode`
+participates in bold/italic wrapping, mark-boundary hoisting, and format
+merging exactly like every other round-trip-sensitive inline construct.
+
+**If you are maintaining this package: `convertListItemNode` keeps a
+`BlockAnchorNode` inline, unlike an image/equation/footnote/inline-HTML
+child of a list item** (a documented, pre-existing gap — see
+`hoistedTokenReachesOutput`'s docstring in `lexicalToMdast.ts` — where those
+constructs fall to the block dispatcher and do not survive a round trip
+inline). `- [ ] ... ^ULID` is this feature's primary real-world shape, so
+dropping a trailing anchor there would break the checkbox-action-item
+pattern the spec calls out explicitly. Do not fold the `$isBlockAnchorNode`
+branch back into the generic block-dispatch fallback.
+
+### Round-trip contract
+
+`parseMarkdown` → `stringifyMarkdown` reproduces a document containing block
+anchors byte-identically (FR-002/SC-002), including inside a checkbox action
+item, one space after a wiki-link or emphasis run, and inside bold/italic
+text. A caret inside inline code, a fenced code block, or inline math is
+never touched — it round-trips as plain literal text, since the post-parse
+pass never sees inside those node types. A caret with *zero* preceding
+whitespace immediately after a wiki-link or emphasis run also round-trips
+byte-identically, but as plain text, not a `blockAnchor` node (#126: that
+position can never satisfy the position rule, so it never badges — see the
+detection-rule section above). See
+`src/app/mapper/__tests__/fixtures/roundtrip/122-block-anchor/` for the
+fixture corpus.
+
 ## Wiki-link promotion on export
 
 Everything above is about *parsing* `[[target]]` syntax the author already wrote.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liminis/editor",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "//publishing": "Publishing is deliberate, never incidental. `private: true` was this package's guard until verveguy/liminis-editor#39 took the publish decision; it is gone because that decision was taken, not because it was tidied away. The guard is now `prepublishOnly` -> scripts/guard-publish.mjs, which refuses unless LIMINIS_ALLOW_PUBLISH=1 is set explicitly. That variable is set at step scope in .github/workflows/publish.yml and nowhere else, so a release is the only path that publishes. Note that `npm publish --dry-run` does NOT report a private package as blocked (npm 10.8.2), which is why the guard is a script rather than a flag.",
   "license": "MIT",
   "description": "Lexical-based markdown WYSIWYG editor with mdast round-trip and a host-injection seam",