@localess/richtext 4.0.2-dev.20260929183905 → 4.0.2-dev.20260930092045

package/README.md

@@ -49,13 +49,15 @@ const html = renderRichTextToHtml(content.data.content);
 
 ### Overriding a node type
 
-Pass `renderers` to replace how one type is rendered — node types and mark types alike. A renderer receives the node's own `attrs`, `text` and `marks` plus its already-rendered `children`, so you only describe the wrapper:
+Pass `renderers` to replace how one type is rendered — node types and mark types alike. A renderer receives the node's own `attrs`, `text` and `marks` plus its already-rendered `children`, so you only describe the wrapper. A custom `link` renderer receives an already-sanitized `href`; the returned string is trusted HTML, so escape what you interpolate (`escapeAttr` / `escapeHtml`):
 
 ```ts
+import { escapeAttr, renderRichTextToHtml } from '@localess/richtext';
+
 const html = renderRichTextToHtml(content.data.content, {
   renderers: {
     heading: ({ attrs, children }) => `<h${attrs?.level} class="font-bold">${children}</h${attrs?.level}>`,
-    link: ({ attrs, children }) => `<a href="${attrs?.href}" rel="noopener">${children}</a>`,
+    link: ({ attrs, children }) => `<a href="${escapeAttr(attrs?.href ?? '')}" rel="noopener">${children}</a>`,
   },
 });
 ```

package/SKILL.md

@@ -69,6 +69,9 @@ renderRichTextToHtml(data.body, {
 `children` arrives pre-rendered. `props.context.renderers` has the current
 type unset — pass it to a nested `renderRichTextToHtml` call to re-render your
 own node without infinite recursion.
+A custom `link` renderer receives `attrs.href` already passed through
+`sanitizeUrl`. The returned string is trusted HTML, so escape what you
+interpolate: `escapeAttr` for attribute values, `escapeHtml` for text.
 
 Renderer props (`LocalessRichTextRendererProps<TOut>`): `type`, `attrs?`,
 `text?`, `marks?`, `content?`, `children`, `context: { renderers? }`, `_key?`.
@@ -88,7 +91,9 @@ The helpers encode the algorithms once so walkers are mechanical translations:
 { attrMap })` (attribute normalization; React passes `{ class: 'className' }`),
 `NODE_RENDER_MAP` / `MARK_RENDER_MAP` / `resolveHeadingTag` (default table;
 `null` entry = transparent, missing key = unknown), `escapeHtml` /
-`escapeAttr` / `sanitizeUrl` (escaping and URL allowlist).
+`escapeAttr` / `sanitizeUrl` (escaping and URL allowlist), `sanitizeElement(element)`
+(pass every node/mark through it before invoking a custom renderer, so overrides
+never receive an unsanitized link `href`).
 See `@localess/react`'s `src/core/richtext.ts` for the reference walker.
 
 ## Test fixtures
@@ -107,9 +112,10 @@ never weaken an assertion to `toContain`.
 ```typescript
 // @localess/richtext
 export { renderRichTextToHtml }                                        // HTML string renderer
-export { normalizeInput, buildMarkTree, marksEqual, processAttrs }     // walker helpers
+export { normalizeInput, buildMarkTree, marksEqual, processAttrs, sanitizeElement } // walker helpers
 export { escapeHtml, escapeAttr, sanitizeUrl }                         // escaping / URL policy
 export { NODE_RENDER_MAP, MARK_RENDER_MAP, resolveHeadingTag }         // default render table
+export { RichTextParseError }                                          // also on the parser subpaths
 export type {
   LocalessRichTextDocument, LocalessRichTextNode, LocalessRichTextNodeWithKey,
   LocalessRichTextMark, LocalessRichTextLinkAttrs, LocalessRichTextElement,
@@ -117,8 +123,15 @@ export type {
   LocalessRichTextRenderer, LocalessRichTextRenderers, LocalessRichTextRendererProps,
   LocalessRichTextHtmlOptions, NormalizeInputOptions, ProcessAttrsOptions,
   RichTextRenderSpec, MarkTreeSegment, MarkTreeText, MarkTreeMark,
+  RichTextParseOptions, RichTextParseResult, RichTextUnsupportedPolicy, RichTextUnsupportedReport,
 }
 
+// @localess/richtext/html-parser, @localess/richtext/markdown-parser
+export { parseHtmlToRichText }       // html-parser
+export { parseMarkdownToRichText }   // markdown-parser
+export { RichTextParseError }
+export type { RichTextParseOptions, RichTextParseResult, RichTextUnsupportedPolicy, RichTextUnsupportedReport }
+
 // @localess/richtext/test-utils
 export { richTextFixtures }
 export type { RichTextFixture }

package/dist/attrs.d.ts

@@ -8,3 +8,12 @@ export interface ProcessAttrsOptions {
  * and in the fixtures together if the parity test disagrees).
  */
 export declare function processAttrs(type: string, attrs: Record<string, any> | undefined, options?: ProcessAttrsOptions): Record<string, any>;
+/**
+ * Returns the node/mark a custom renderer receives: for `link`, a copy whose `href` has passed
+ * {@link sanitizeUrl}; every other element is returned unchanged. Applied by every Localess
+ * renderer before invoking an override, so custom `link` renderers never see a raw href.
+ */
+export declare function sanitizeElement<T extends {
+    type: string;
+    attrs?: Record<string, any> | null;
+}>(element: T): T;

package/dist/index.js

@@ -29,6 +29,21 @@ function processAttrs(type, attrs, options = {}) {
 	}
 	return out;
 }
+/**
+* Returns the node/mark a custom renderer receives: for `link`, a copy whose `href` has passed
+* {@link sanitizeUrl}; every other element is returned unchanged. Applied by every Localess
+* renderer before invoking an override, so custom `link` renderers never see a raw href.
+*/
+function sanitizeElement(element) {
+	if (element.type !== "link" || !element.attrs || element.attrs.href === null || element.attrs.href === void 0) return element;
+	return {
+		...element,
+		attrs: {
+			...element.attrs,
+			href: require_parse_common.sanitizeUrl(String(element.attrs.href))
+		}
+	};
+}
 //#endregion
 //#region src/marks.ts
 /** Deep equality of two marks (type + attrs). Attr key order must match, which holds for editor-produced documents. */
@@ -211,7 +226,7 @@ function renderNode(node, ctx) {
 		};
 		const children = node.type === "text" ? require_parse_common.escapeHtml(node.text ?? "") : renderNodes(node.content ?? [], childCtx);
 		return custom({
-			...node,
+			...sanitizeElement(node),
 			children,
 			context: { renderers: childRenderers }
 		});
@@ -246,7 +261,7 @@ function renderSegments(segments, ctx) {
 		const custom = ctx.renderers?.[segment.mark.type];
 		if (custom) {
 			out += custom({
-				...segment.mark,
+				...sanitizeElement(segment.mark),
 				children,
 				context: { renderers: ctx.renderers }
 			});
@@ -287,4 +302,5 @@ exports.normalizeInput = normalizeInput;
 exports.processAttrs = processAttrs;
 exports.renderRichTextToHtml = renderRichTextToHtml;
 exports.resolveHeadingTag = resolveHeadingTag;
+exports.sanitizeElement = sanitizeElement;
 exports.sanitizeUrl = require_parse_common.sanitizeUrl;

package/dist/index.mjs

@@ -28,6 +28,21 @@ function processAttrs(type, attrs, options = {}) {
 	}
 	return out;
 }
+/**
+* Returns the node/mark a custom renderer receives: for `link`, a copy whose `href` has passed
+* {@link sanitizeUrl}; every other element is returned unchanged. Applied by every Localess
+* renderer before invoking an override, so custom `link` renderers never see a raw href.
+*/
+function sanitizeElement(element) {
+	if (element.type !== "link" || !element.attrs || element.attrs.href === null || element.attrs.href === void 0) return element;
+	return {
+		...element,
+		attrs: {
+			...element.attrs,
+			href: sanitizeUrl(String(element.attrs.href))
+		}
+	};
+}
 //#endregion
 //#region src/marks.ts
 /** Deep equality of two marks (type + attrs). Attr key order must match, which holds for editor-produced documents. */
@@ -210,7 +225,7 @@ function renderNode(node, ctx) {
 		};
 		const children = node.type === "text" ? escapeHtml(node.text ?? "") : renderNodes(node.content ?? [], childCtx);
 		return custom({
-			...node,
+			...sanitizeElement(node),
 			children,
 			context: { renderers: childRenderers }
 		});
@@ -245,7 +260,7 @@ function renderSegments(segments, ctx) {
 		const custom = ctx.renderers?.[segment.mark.type];
 		if (custom) {
 			out += custom({
-				...segment.mark,
+				...sanitizeElement(segment.mark),
 				children,
 				context: { renderers: ctx.renderers }
 			});
@@ -273,4 +288,4 @@ function warnUnknown(ctx, type) {
 	console.warn(`[@localess/richtext] Unknown rich text element "${type}" was skipped. Provide a custom renderer to handle it.`);
 }
 //#endregion
-export { MARK_RENDER_MAP, NODE_RENDER_MAP, RichTextParseError, UnsupportedTracker, buildMarkTree, emptyDocument, escapeAttr, escapeHtml, marksEqual, normalizeInput, processAttrs, renderRichTextToHtml, resolveHeadingTag, sanitizeUrl };
+export { MARK_RENDER_MAP, NODE_RENDER_MAP, RichTextParseError, UnsupportedTracker, buildMarkTree, emptyDocument, escapeAttr, escapeHtml, marksEqual, normalizeInput, processAttrs, renderRichTextToHtml, resolveHeadingTag, sanitizeElement, sanitizeUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localess/richtext",
-  "version": "4.0.2-dev.20260929183905",
+  "version": "4.0.2-dev.20260930092045",
   "description": "Framework-neutral rich text model and renderer for Localess's TipTap JSON content.",
   "keywords": [
     "localess",
@@ -58,7 +58,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@localess/model": "4.0.2-dev.20260929183905"
+    "@localess/model": "4.0.2-dev.20260930092045"
   },
   "devDependencies": {
     "@tiptap/extension-bold": "^3.22.5",