@localess/richtext 3.4.1-dev.20260831165456

package/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: localess-richtext
+description: Framework-neutral rich text model and renderer for Localess TipTap JSON content. Zero dependencies. Use when rendering Localess RICH_TEXT fields to HTML or building a framework-specific rich text walker.
+---
+
+# @localess/richtext
+
+Renders Localess rich text field values (TipTap/ProseMirror JSON produced by
+the Localess Studio editor) without TipTap at runtime. Zero production
+dependencies; safe in browsers, SSR, and edge runtimes.
+
+Framework packages (`@localess/react`, `@localess/vue`, `@localess/svelte`,
+`@localess/astro`, `@localess/angular`) ship idiomatic wrappers — prefer those
+in app code. Use this package directly for custom pipelines (emails, static
+generation, other frameworks).
+
+## Render to HTML
+
+```ts
+import { renderRichTextToHtml } from '@localess/richtext';
+
+const html = renderRichTextToHtml(data.body);
+```
+
+- Input: `LocalessRichTextInput` — a `doc`, a node, a node array, `null`, or
+  `@localess/client`'s `ContentRichText` (structurally compatible, no cast).
+- Output is byte-identical to TipTap's `generateHTML` for the Studio's
+  extension set, except link `href`s pass a protocol allowlist
+  (`http:`/`https:`/`mailto:`/`tel:`/scheme-less); `javascript:`/`data:`
+  hrefs become `""`.
+- Never throws; malformed input renders `''`.
+
+## Supported node set
+
+Nodes: `doc`, `paragraph`, `heading` (1–6), `bulletList`, `orderedList`
+(`start`), `listItem`, `codeBlock` (`language` → `class="language-x"` on
+`<code>`), `text`. Marks: `bold` → `<strong>`, `italic` → `<em>`,
+`strike` → `<s>`, `underline` → `<u>`, `code` → `<code>`, `link` → `<a>`.
+
+Unknown types are skipped with a dev-only warning unless a custom renderer is
+provided for that type string.
+
+## Custom renderers
+
+```ts
+renderRichTextToHtml(data.body, {
+  renderers: {
+    heading: ({ attrs, children }) => `<h${attrs.level} class="title">${children}</h${attrs.level}>`,
+  },
+});
+```
+
+`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.
+
+## Building a native walker
+
+The helpers encode the algorithms once so walkers are mechanical translations:
+`normalizeInput(input, { withKeys: true })` (keyed node list),
+`buildMarkTree(textRun)` (adjacent-mark merging), `processAttrs(type, attrs,
+{ attrMap })` (attribute normalization; React passes `{ class: 'className' }`),
+`NODE_RENDER_MAP` / `MARK_RENDER_MAP` / `resolveHeadingTag` (default table).
+See `@localess/react`'s `src/core/richtext.ts` for the reference walker.
+
+## Test fixtures
+
+```ts
+import { richTextFixtures } from '@localess/richtext/test-utils';
+```
+
+`{ title, input, expected, parity }` corpus asserted by every Localess
+renderer. `parity: true` fixtures are additionally byte-compared to TipTap's
+`generateHTML` — parity is normative; never weaken an assertion to
+`toContain`.

package/dist/attrs.d.ts

@@ -0,0 +1,10 @@
+export interface ProcessAttrsOptions {
+    /** Per-framework attribute renames, e.g. `{ class: 'className' }` for React. */
+    attrMap?: Record<string, string>;
+}
+/**
+ * Normalizes a node/mark's stored attrs into the attributes to emit, in the
+ * order TipTap's `generateHTML` emits them (parity-tested — adjust order here
+ * 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>;

package/dist/escape.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Escapes text content for safe HTML output. The escape set (`& < >`) matches
+ * TipTap's `generateHTML` DOM serialization — parity-tested; do not widen it
+ * without updating the parity fixtures.
+ */
+export declare function escapeHtml(text: string): string;
+/** Escapes an attribute value for safe double-quoted HTML output (`& " < >`). */
+export declare function escapeAttr(value: string): string;
+/**
+ * Allowlist URL sanitizer for link hrefs: `http:`, `https:`, `mailto:`, `tel:`
+ * and scheme-less (relative/protocol-relative/fragment/query) URLs pass;
+ * everything else (e.g. `javascript:`, `data:`) becomes `''`.
+ */
+export declare function sanitizeUrl(url: string): string;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './attrs';
+export * from './escape';
+export * from './marks';
+export * from './model';
+export * from './normalize';
+export * from './render-html';
+export * from './render-map';

package/dist/index.js

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e={"&":`&amp;`,"<":`&lt;`,">":`&gt;`},t={...e,'"':`&quot;`};function n(t){return t.replace(/[&<>]/g,t=>e[t])}function r(e){return e.replace(/[&"<>]/g,e=>t[e])}var i=/^(?:https?:|mailto:|tel:)/i,a=/^[a-z][a-z0-9+.-]*:/i;function o(e){let t=e.trim();return t===``?``:i.test(t)||!a.test(t)?t:``}function s(e,t,n={}){let r={},i=e=>n.attrMap?.[e]??e,a=(e,t)=>{t!=null&&t!==``&&(r[i(e)]=t)};if(!t)return r;switch(e){case`orderedList`:t.start!==null&&t.start!==void 0&&t.start!==1&&a(`start`,t.start);break;case`codeBlock`:t.language&&a(`class`,`language-${t.language}`);break;case`link`:a(`target`,t.target),a(`rel`,t.rel),r[i(`href`)]=o(String(t.href??``)),a(`class`,t.class)}return r}function c(e,t){return e.type===t.type&&JSON.stringify(e.attrs??{})===JSON.stringify(t.attrs??{})}function l(e){let t=[],n=[];for(let r of e){let e=r.marks??[],i=0;for(;i<n.length&&i<e.length&&c(n[i].mark,e[i]);)i++;n.length=i;for(let r=i;r<e.length;r++){let i={kind:`mark`,mark:e[r],children:[]};(n.length>0?n[n.length-1].children:t).push(i),n.push(i)}(n.length>0?n[n.length-1].children:t).push({kind:`text`,text:r.text})}return t}function u(e,t={}){let n;return n=e?Array.isArray(e)?e:e.type===`doc`?e.content??[]:typeof e.type==`string`?[e]:[]:[],t.withKeys?d(n,{}):n}function d(e,t){return e.map(e=>{t[e.type]=(t[e.type]??0)+1;let n={...e,_key:`${e.type}-${t[e.type]}`};return Array.isArray(n.content)&&(n.content=d(n.content,t)),n})}var f=[1,2,3,4,5,6];function p(e){let t=e?.level;return`h${f.includes(t)?t:1}`}var m={doc:null,text:null,paragraph:{tag:`p`,content:!0},heading:{resolve:p,content:!0},bulletList:{tag:`ul`,content:!0},orderedList:{tag:`ol`,content:!0},listItem:{tag:`li`,content:!0},codeBlock:{tag:`pre`,children:[{tag:`code`,content:!0}]}},h={bold:{tag:`strong`,content:!0},italic:{tag:`em`,content:!0},strike:{tag:`s`,content:!0},underline:{tag:`u`,content:!0},code:{tag:`code`,content:!0},link:{tag:`a`,content:!0}};function g(e,t={}){return _(u(e),{renderers:t.renderers,warned:new Set})}function _(e,t){let n=``,r=0;for(;r<e.length;){let i=e[r];if(i.type===`text`&&!t.renderers?.text){let i=[];for(;r<e.length&&e[r].type===`text`;)i.push(e[r]),r++;n+=y(l(i),t)}else n+=v(i,t),r++}return n}function v(e,t){let r=t.renderers?.[e.type];if(r){let i={...t.renderers,[e.type]:void 0},a={renderers:i,warned:t.warned},o=e.type===`text`?n(e.text??``):_(e.content??[],a);return r({...e,children:o,context:{renderers:i}})}if(e.type===`text`)return y(l([e]),t);let i=m[e.type];if(i===void 0)return x(t,e.type),``;if(i===null)return _(e.content??[],t);let a=s(e.type,e.attrs),o=_(e.content??[],t);if(i.children){let e=o;for(let t=i.children.length-1;t>=0;t--){let n=i.children[t];e=b(n.tag,n.content?a:{},e)}return b(i.tag,{},e)}return b(i.resolve?i.resolve(e.attrs):i.tag,a,o)}function y(e,t){let r=``;for(let i of e){if(i.kind===`text`){r+=n(i.text);continue}let e=y(i.children,t),a=t.renderers?.[i.mark.type];if(a){r+=a({...i.mark,children:e,context:{renderers:t.renderers}});continue}let o=h[i.mark.type];if(!o){x(t,i.mark.type),r+=e;continue}r+=b(o.tag,s(i.mark.type,i.mark.attrs),e)}return r}function b(e,t,n){let i=`<${e}`;for(let[e,n]of Object.entries(t))i+=` ${e}="${r(String(n))}"`;return`${i}>${n}</${e}>`}function x(e,t){typeof process<`u`&&process.env&&process.env.NODE_ENV===`production`||e.warned.has(t)||(e.warned.add(t),console.warn(`[@localess/richtext] Unknown rich text element "${t}" was skipped. Provide a custom renderer to handle it.`))}exports.MARK_RENDER_MAP=h,exports.NODE_RENDER_MAP=m,exports.buildMarkTree=l,exports.escapeAttr=r,exports.escapeHtml=n,exports.marksEqual=c,exports.normalizeInput=u,exports.processAttrs=s,exports.renderRichTextToHtml=g,exports.resolveHeadingTag=p,exports.sanitizeUrl=o;

package/dist/index.mjs

@@ -0,0 +1,236 @@
+//#region src/escape.ts
+var e = {
+	"&": "&",
+	"<": "&lt;",
+	">": "&gt;"
+}, t = {
+	...e,
+	"\"": "&quot;"
+};
+function n(t) {
+	return t.replace(/[&<>]/g, (t) => e[t]);
+}
+function r(e) {
+	return e.replace(/[&"<>]/g, (e) => t[e]);
+}
+var i = /^(?:https?:|mailto:|tel:)/i, a = /^[a-z][a-z0-9+.-]*:/i;
+function o(e) {
+	let t = e.trim();
+	return t === "" ? "" : i.test(t) || !a.test(t) ? t : "";
+}
+//#endregion
+//#region src/attrs.ts
+function s(e, t, n = {}) {
+	let r = {}, i = (e) => n.attrMap?.[e] ?? e, a = (e, t) => {
+		t != null && t !== "" && (r[i(e)] = t);
+	};
+	if (!t) return r;
+	switch (e) {
+		case "orderedList":
+			t.start !== null && t.start !== void 0 && t.start !== 1 && a("start", t.start);
+			break;
+		case "codeBlock":
+			t.language && a("class", `language-${t.language}`);
+			break;
+		case "link": a("target", t.target), a("rel", t.rel), r[i("href")] = o(String(t.href ?? "")), a("class", t.class);
+	}
+	return r;
+}
+//#endregion
+//#region src/marks.ts
+function c(e, t) {
+	return e.type === t.type && JSON.stringify(e.attrs ?? {}) === JSON.stringify(t.attrs ?? {});
+}
+function l(e) {
+	let t = [], n = [];
+	for (let r of e) {
+		let e = r.marks ?? [], i = 0;
+		for (; i < n.length && i < e.length && c(n[i].mark, e[i]);) i++;
+		n.length = i;
+		for (let r = i; r < e.length; r++) {
+			let i = {
+				kind: "mark",
+				mark: e[r],
+				children: []
+			};
+			(n.length > 0 ? n[n.length - 1].children : t).push(i), n.push(i);
+		}
+		(n.length > 0 ? n[n.length - 1].children : t).push({
+			kind: "text",
+			text: r.text
+		});
+	}
+	return t;
+}
+//#endregion
+//#region src/normalize.ts
+function u(e, t = {}) {
+	let n;
+	return n = e ? Array.isArray(e) ? e : e.type === "doc" ? e.content ?? [] : typeof e.type == "string" ? [e] : [] : [], t.withKeys ? d(n, {}) : n;
+}
+function d(e, t) {
+	return e.map((e) => {
+		t[e.type] = (t[e.type] ?? 0) + 1;
+		let n = {
+			...e,
+			_key: `${e.type}-${t[e.type]}`
+		};
+		return Array.isArray(n.content) && (n.content = d(n.content, t)), n;
+	});
+}
+//#endregion
+//#region src/render-map.ts
+var f = [
+	1,
+	2,
+	3,
+	4,
+	5,
+	6
+];
+function p(e) {
+	let t = e?.level;
+	return `h${f.includes(t) ? t : 1}`;
+}
+var m = {
+	doc: null,
+	text: null,
+	paragraph: {
+		tag: "p",
+		content: !0
+	},
+	heading: {
+		resolve: p,
+		content: !0
+	},
+	bulletList: {
+		tag: "ul",
+		content: !0
+	},
+	orderedList: {
+		tag: "ol",
+		content: !0
+	},
+	listItem: {
+		tag: "li",
+		content: !0
+	},
+	codeBlock: {
+		tag: "pre",
+		children: [{
+			tag: "code",
+			content: !0
+		}]
+	}
+}, h = {
+	bold: {
+		tag: "strong",
+		content: !0
+	},
+	italic: {
+		tag: "em",
+		content: !0
+	},
+	strike: {
+		tag: "s",
+		content: !0
+	},
+	underline: {
+		tag: "u",
+		content: !0
+	},
+	code: {
+		tag: "code",
+		content: !0
+	},
+	link: {
+		tag: "a",
+		content: !0
+	}
+};
+//#endregion
+//#region src/render-html.ts
+function g(e, t = {}) {
+	return _(u(e), {
+		renderers: t.renderers,
+		warned: /* @__PURE__ */ new Set()
+	});
+}
+function _(e, t) {
+	let n = "", r = 0;
+	for (; r < e.length;) {
+		let i = e[r];
+		if (i.type === "text" && !t.renderers?.text) {
+			let i = [];
+			for (; r < e.length && e[r].type === "text";) i.push(e[r]), r++;
+			n += y(l(i), t);
+		} else n += v(i, t), r++;
+	}
+	return n;
+}
+function v(e, t) {
+	let r = t.renderers?.[e.type];
+	if (r) {
+		let i = {
+			...t.renderers,
+			[e.type]: void 0
+		}, a = {
+			renderers: i,
+			warned: t.warned
+		}, o = e.type === "text" ? n(e.text ?? "") : _(e.content ?? [], a);
+		return r({
+			...e,
+			children: o,
+			context: { renderers: i }
+		});
+	}
+	if (e.type === "text") return y(l([e]), t);
+	let i = m[e.type];
+	if (i === void 0) return x(t, e.type), "";
+	if (i === null) return _(e.content ?? [], t);
+	let a = s(e.type, e.attrs), o = _(e.content ?? [], t);
+	if (i.children) {
+		let e = o;
+		for (let t = i.children.length - 1; t >= 0; t--) {
+			let n = i.children[t];
+			e = b(n.tag, n.content ? a : {}, e);
+		}
+		return b(i.tag, {}, e);
+	}
+	return b(i.resolve ? i.resolve(e.attrs) : i.tag, a, o);
+}
+function y(e, t) {
+	let r = "";
+	for (let i of e) {
+		if (i.kind === "text") {
+			r += n(i.text);
+			continue;
+		}
+		let e = y(i.children, t), a = t.renderers?.[i.mark.type];
+		if (a) {
+			r += a({
+				...i.mark,
+				children: e,
+				context: { renderers: t.renderers }
+			});
+			continue;
+		}
+		let o = h[i.mark.type];
+		if (!o) {
+			x(t, i.mark.type), r += e;
+			continue;
+		}
+		r += b(o.tag, s(i.mark.type, i.mark.attrs), e);
+	}
+	return r;
+}
+function b(e, t, n) {
+	let i = `<${e}`;
+	for (let [e, n] of Object.entries(t)) i += ` ${e}="${r(String(n))}"`;
+	return `${i}>${n}</${e}>`;
+}
+function x(e, t) {
+	typeof process < "u" && process.env && process.env.NODE_ENV === "production" || e.warned.has(t) || (e.warned.add(t), console.warn(`[@localess/richtext] Unknown rich text element "${t}" was skipped. Provide a custom renderer to handle it.`));
+}
+//#endregion
+export { h as MARK_RENDER_MAP, m as NODE_RENDER_MAP, l as buildMarkTree, r as escapeAttr, n as escapeHtml, c as marksEqual, u as normalizeInput, s as processAttrs, g as renderRichTextToHtml, p as resolveHeadingTag, o as sanitizeUrl };

package/dist/marks.d.ts

@@ -0,0 +1,24 @@
+import { LocalessRichTextMark } from './model';
+export interface MarkTreeText {
+    kind: 'text';
+    text: string;
+}
+export interface MarkTreeMark {
+    kind: 'mark';
+    mark: LocalessRichTextMark;
+    children: MarkTreeSegment[];
+}
+export type MarkTreeSegment = MarkTreeText | MarkTreeMark;
+/** Deep equality of two marks (type + attrs). Attr key order must match, which holds for editor-produced documents. */
+export declare function marksEqual(a: LocalessRichTextMark, b: LocalessRichTextMark): boolean;
+/**
+ * Folds a run of consecutive text nodes into a tree in which adjacent nodes
+ * sharing the same outer marks share one wrapper — the same merging
+ * ProseMirror's DOM serializer performs, so output matches TipTap's
+ * `generateHTML` (one `<a>` per link span, `<strong>a<em>b</em></strong>`
+ * instead of sibling `<strong>` wrappers).
+ */
+export declare function buildMarkTree(nodes: Array<{
+    text: string;
+    marks?: LocalessRichTextMark[];
+}>): MarkTreeSegment[];

package/dist/model.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Attributes of a `link` mark as stored by the Localess Studio editor
+ * (TipTap Link extension JSON).
+ */
+export interface LocalessRichTextLinkAttrs {
+    href: string;
+    target?: string | null;
+    rel?: string | null;
+    class?: string | null;
+}
+/**
+ * A rich text mark — inline formatting applied to a `text` node.
+ * Exactly the mark set the Localess Studio editor can produce.
+ */
+export type LocalessRichTextMark = {
+    type: 'bold';
+} | {
+    type: 'italic';
+} | {
+    type: 'strike';
+} | {
+    type: 'underline';
+} | {
+    type: 'code';
+} | {
+    type: 'link';
+    attrs: LocalessRichTextLinkAttrs;
+};
+/**
+ * A rich text node — exactly the node set the Localess Studio editor can produce.
+ */
+export type LocalessRichTextNode = {
+    type: 'paragraph';
+    content?: LocalessRichTextNode[];
+} | {
+    type: 'heading';
+    attrs: {
+        level: 1 | 2 | 3 | 4 | 5 | 6;
+    };
+    content?: LocalessRichTextNode[];
+} | {
+    type: 'bulletList';
+    content?: LocalessRichTextNode[];
+} | {
+    type: 'orderedList';
+    attrs?: {
+        start?: number;
+    };
+    content?: LocalessRichTextNode[];
+} | {
+    type: 'listItem';
+    content?: LocalessRichTextNode[];
+} | {
+    type: 'codeBlock';
+    attrs?: {
+        language?: string | null;
+    };
+    content?: LocalessRichTextNode[];
+} | {
+    type: 'text';
+    text: string;
+    marks?: LocalessRichTextMark[];
+};
+/** A node with an optional stable key injected by `normalizeInput(input, { withKeys: true })`. */
+export type LocalessRichTextNodeWithKey = LocalessRichTextNode & {
+    _key?: string;
+};
+/** The root document node (`getJSON()` output of the Studio editor). */
+export interface LocalessRichTextDocument {
+    type: 'doc';
+    content?: LocalessRichTextNode[];
+}
+/**
+ * Structural stand-in for `@localess/client`'s `ContentRichText` so client
+ * values pass without casting. Deliberately not imported — this package has
+ * zero dependencies.
+ */
+export interface ContentRichTextLike {
+    type?: string;
+    content?: ContentRichTextLike[];
+}
+/** Anything a render function accepts. */
+export type LocalessRichTextInput = LocalessRichTextDocument | LocalessRichTextNode | LocalessRichTextNode[] | ContentRichTextLike | null | undefined;
+/** Union of every known node and mark type name. */
+export type LocalessRichTextElement = LocalessRichTextNode['type'] | LocalessRichTextMark['type'] | 'doc';
+/**
+ * Props passed to a custom renderer. `children` is the pre-rendered content of
+ * the node/mark; `context.renderers` is the override map with the current
+ * type unset (loop prevention) for safe re-entrant rendering.
+ */
+export interface LocalessRichTextRendererProps<TOut> {
+    type: string;
+    attrs?: Record<string, any>;
+    text?: string;
+    marks?: LocalessRichTextMark[];
+    content?: LocalessRichTextNode[];
+    children: TOut;
+    context: {
+        renderers?: LocalessRichTextRenderers<TOut>;
+    };
+    _key?: string;
+}
+/** A custom renderer for one node or mark type. */
+export type LocalessRichTextRenderer<TOut> = (props: LocalessRichTextRendererProps<TOut>) => TOut;
+/**
+ * Override map: node/mark type name → custom renderer. Unknown type names are
+ * allowed — that is the forward-compat seam for future node types.
+ */
+export type LocalessRichTextRenderers<TOut> = Record<string, LocalessRichTextRenderer<TOut> | undefined>;

package/dist/normalize.d.ts

@@ -0,0 +1,11 @@
+import { LocalessRichTextInput, LocalessRichTextNodeWithKey } from './model';
+export interface NormalizeInputOptions {
+    /** Inject recursive `_key` values (`paragraph-1`, `text-3`, …) for keyed renderers. */
+    withKeys?: boolean;
+}
+/**
+ * Flattens any accepted rich text input (document, node, node array, or the
+ * loose `ContentRichText` shape from `@localess/client`) into a node list.
+ * Never throws; malformed input yields `[]`.
+ */
+export declare function normalizeInput(input: LocalessRichTextInput, options?: NormalizeInputOptions): LocalessRichTextNodeWithKey[];

package/dist/render-html.d.ts

@@ -0,0 +1,11 @@
+import { LocalessRichTextInput, LocalessRichTextRenderers } from './model';
+export interface LocalessRichTextHtmlOptions {
+    /** Per-type overrides. A custom renderer receives pre-rendered `children` and a loop-safe `context`. */
+    renderers?: LocalessRichTextRenderers<string>;
+}
+/**
+ * Renders Localess rich text JSON to an HTML string. Framework-neutral,
+ * dependency-free, and byte-compatible with TipTap's `generateHTML` for the
+ * node set the Localess Studio editor produces.
+ */
+export declare function renderRichTextToHtml(input: LocalessRichTextInput, options?: LocalessRichTextHtmlOptions): string;

package/dist/render-map.d.ts

@@ -0,0 +1,18 @@
+/** Declarative default rendering for one node/mark type. */
+export interface RichTextRenderSpec {
+    tag?: string;
+    /** Dynamic tag resolution (heading levels). Wins over `tag`. */
+    resolve?: (attrs: Record<string, any> | undefined) => string;
+    /** Render children inside this element. */
+    content?: boolean;
+    /** Static nested structure; node attrs attach to the child with `content: true`. */
+    children?: Array<{
+        tag: string;
+        content?: boolean;
+    }>;
+}
+/** Invalid levels fall back to h1, matching TipTap's first-configured-level behavior. */
+export declare function resolveHeadingTag(attrs: Record<string, any> | undefined): string;
+/** `null` = transparent (render children only, no element). Missing key = unknown type. */
+export declare const NODE_RENDER_MAP: Record<string, RichTextRenderSpec | null>;
+export declare const MARK_RENDER_MAP: Record<string, RichTextRenderSpec>;

package/dist/test-utils/fixtures.d.ts

@@ -0,0 +1,14 @@
+import { LocalessRichTextInput } from '../model';
+export interface RichTextFixture {
+    title: string;
+    input: LocalessRichTextInput;
+    expected: string;
+    parity: boolean;
+}
+/**
+ * Shared correctness corpus. Every renderer in every framework package must
+ * produce exactly these strings (DOM-roundtrip-normalized where the framework
+ * renders through a real DOM). `parity: true` fixtures are additionally
+ * asserted byte-identical to TipTap's `generateHTML`.
+ */
+export declare const richTextFixtures: RichTextFixture[];

package/dist/test-utils/index.d.ts

@@ -0,0 +1 @@
+export * from './fixtures';

package/dist/test-utils/index.js

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=(...e)=>({type:`doc`,content:e}),t=(...e)=>({type:`paragraph`,content:e}),n=(e,t)=>({type:`text`,text:e,...t?{marks:t}:{}}),r=(...e)=>({type:`listItem`,content:e}),i={type:`link`,attrs:{href:`https://example.com`,target:`_blank`,rel:`noopener noreferrer nofollow`,class:null}},a=[{title:`empty doc`,input:e(),expected:``,parity:!0},{title:`null input`,input:null,expected:``,parity:!1},{title:`plain paragraph`,input:e(t(n(`Hello world`))),expected:`<p>Hello world</p>`,parity:!0},{title:`two paragraphs`,input:e(t(n(`One`)),t(n(`Two`))),expected:`<p>One</p><p>Two</p>`,parity:!0},{title:`all six heading levels`,input:e(...[1,2,3,4,5,6].map(e=>({type:`heading`,attrs:{level:e},content:[n(`H${e}`)]}))),expected:`<h1>H1</h1><h2>H2</h2><h3>H3</h3><h4>H4</h4><h5>H5</h5><h6>H6</h6>`,parity:!0},{title:`invalid heading level falls back to h1`,input:e({type:`heading`,attrs:{level:9},content:[n(`Big`)]}),expected:`<h1>Big</h1>`,parity:!0},{title:`every simple mark`,input:e(t(n(`b`,[{type:`bold`}]),n(`i`,[{type:`italic`}]),n(`s`,[{type:`strike`}]),n(`u`,[{type:`underline`}]),n(`c`,[{type:`code`}]))),expected:`<p><strong>b</strong><em>i</em><s>s</s><u>u</u><code>c</code></p>`,parity:!0},{title:`nested marks fold with marks[0] outermost`,input:e(t(n(`x`,[{type:`bold`},{type:`italic`}]))),expected:`<p><strong><em>x</em></strong></p>`,parity:!0},{title:`adjacent nodes sharing an outer mark merge into one wrapper`,input:e(t(n(`a`,[{type:`bold`}]),n(`b`,[{type:`bold`},{type:`italic`}]))),expected:`<p><strong>a<em>b</em></strong></p>`,parity:!0},{title:`bullet list with paragraphs in items`,input:e({type:`bulletList`,content:[r(t(n(`One`))),r(t(n(`Two`)))]}),expected:`<ul><li><p>One</p></li><li><p>Two</p></li></ul>`,parity:!0},{title:`ordered list omits start=1`,input:e({type:`orderedList`,attrs:{start:1},content:[r(t(n(`One`)))]}),expected:`<ol><li><p>One</p></li></ol>`,parity:!0},{title:`ordered list emits start=3`,input:e({type:`orderedList`,attrs:{start:3},content:[r(t(n(`Three`)))]}),expected:`<ol start="3"><li><p>Three</p></li></ol>`,parity:!0},{title:`nested bullet list inside a list item`,input:e({type:`bulletList`,content:[r(t(n(`Outer`)),{type:`bulletList`,content:[r(t(n(`Inner`)))]})]}),expected:`<ul><li><p>Outer</p><ul><li><p>Inner</p></li></ul></li></ul>`,parity:!0},{title:`code block without language`,input:e({type:`codeBlock`,attrs:{language:null},content:[n(`const x = 1;`)]}),expected:`<pre><code>const x = 1;</code></pre>`,parity:!0},{title:`code block with language class`,input:e({type:`codeBlock`,attrs:{language:`js`},content:[n(`const x = 1;`)]}),expected:`<pre><code class="language-js">const x = 1;</code></pre>`,parity:!0},{title:`link with editor-default attrs`,input:e(t(n(`Visit`,[i]))),expected:`<p><a target="_blank" rel="noopener noreferrer nofollow" href="https://example.com">Visit</a></p>`,parity:!0},{title:`link spanning differently-marked text renders one anchor`,input:e(t(n(`go `,[i]),n(`bold`,[i,{type:`bold`}]),n(` now`,[i]))),expected:`<p><a target="_blank" rel="noopener noreferrer nofollow" href="https://example.com">go <strong>bold</strong> now</a></p>`,parity:!0},{title:`text escaping of angle brackets and ampersands`,input:e(t(n(`a < b & c > d`))),expected:`<p>a &lt; b &amp; c &gt; d</p>`,parity:!0},{title:`javascript: href is sanitized to empty (intentionally stricter than TipTap)`,input:e(t(n(`x`,[{type:`link`,attrs:{href:`javascript:alert(1)`}}]))),expected:`<p><a href="">x</a></p>`,parity:!1},{title:`unknown node types are skipped`,input:e({type:`schema`,attrs:{data:{}}},t(n(`kept`))),expected:`<p>kept</p>`,parity:!1}];exports.richTextFixtures=a;

package/dist/test-utils/index.mjs

@@ -0,0 +1,192 @@
+//#region src/test-utils/fixtures.ts
+var e = (...e) => ({
+	type: "doc",
+	content: e
+}), t = (...e) => ({
+	type: "paragraph",
+	content: e
+}), n = (e, t) => ({
+	type: "text",
+	text: e,
+	...t ? { marks: t } : {}
+}), r = (...e) => ({
+	type: "listItem",
+	content: e
+}), i = {
+	type: "link",
+	attrs: {
+		href: "https://example.com",
+		target: "_blank",
+		rel: "noopener noreferrer nofollow",
+		class: null
+	}
+}, a = [
+	{
+		title: "empty doc",
+		input: e(),
+		expected: "",
+		parity: !0
+	},
+	{
+		title: "null input",
+		input: null,
+		expected: "",
+		parity: !1
+	},
+	{
+		title: "plain paragraph",
+		input: e(t(n("Hello world"))),
+		expected: "<p>Hello world</p>",
+		parity: !0
+	},
+	{
+		title: "two paragraphs",
+		input: e(t(n("One")), t(n("Two"))),
+		expected: "<p>One</p><p>Two</p>",
+		parity: !0
+	},
+	{
+		title: "all six heading levels",
+		input: e(...[
+			1,
+			2,
+			3,
+			4,
+			5,
+			6
+		].map((e) => ({
+			type: "heading",
+			attrs: { level: e },
+			content: [n(`H${e}`)]
+		}))),
+		expected: "<h1>H1</h1><h2>H2</h2><h3>H3</h3><h4>H4</h4><h5>H5</h5><h6>H6</h6>",
+		parity: !0
+	},
+	{
+		title: "invalid heading level falls back to h1",
+		input: e({
+			type: "heading",
+			attrs: { level: 9 },
+			content: [n("Big")]
+		}),
+		expected: "<h1>Big</h1>",
+		parity: !0
+	},
+	{
+		title: "every simple mark",
+		input: e(t(n("b", [{ type: "bold" }]), n("i", [{ type: "italic" }]), n("s", [{ type: "strike" }]), n("u", [{ type: "underline" }]), n("c", [{ type: "code" }]))),
+		expected: "<p><strong>b</strong><em>i</em><s>s</s><u>u</u><code>c</code></p>",
+		parity: !0
+	},
+	{
+		title: "nested marks fold with marks[0] outermost",
+		input: e(t(n("x", [{ type: "bold" }, { type: "italic" }]))),
+		expected: "<p><strong><em>x</em></strong></p>",
+		parity: !0
+	},
+	{
+		title: "adjacent nodes sharing an outer mark merge into one wrapper",
+		input: e(t(n("a", [{ type: "bold" }]), n("b", [{ type: "bold" }, { type: "italic" }]))),
+		expected: "<p><strong>a<em>b</em></strong></p>",
+		parity: !0
+	},
+	{
+		title: "bullet list with paragraphs in items",
+		input: e({
+			type: "bulletList",
+			content: [r(t(n("One"))), r(t(n("Two")))]
+		}),
+		expected: "<ul><li><p>One</p></li><li><p>Two</p></li></ul>",
+		parity: !0
+	},
+	{
+		title: "ordered list omits start=1",
+		input: e({
+			type: "orderedList",
+			attrs: { start: 1 },
+			content: [r(t(n("One")))]
+		}),
+		expected: "<ol><li><p>One</p></li></ol>",
+		parity: !0
+	},
+	{
+		title: "ordered list emits start=3",
+		input: e({
+			type: "orderedList",
+			attrs: { start: 3 },
+			content: [r(t(n("Three")))]
+		}),
+		expected: "<ol start=\"3\"><li><p>Three</p></li></ol>",
+		parity: !0
+	},
+	{
+		title: "nested bullet list inside a list item",
+		input: e({
+			type: "bulletList",
+			content: [r(t(n("Outer")), {
+				type: "bulletList",
+				content: [r(t(n("Inner")))]
+			})]
+		}),
+		expected: "<ul><li><p>Outer</p><ul><li><p>Inner</p></li></ul></li></ul>",
+		parity: !0
+	},
+	{
+		title: "code block without language",
+		input: e({
+			type: "codeBlock",
+			attrs: { language: null },
+			content: [n("const x = 1;")]
+		}),
+		expected: "<pre><code>const x = 1;</code></pre>",
+		parity: !0
+	},
+	{
+		title: "code block with language class",
+		input: e({
+			type: "codeBlock",
+			attrs: { language: "js" },
+			content: [n("const x = 1;")]
+		}),
+		expected: "<pre><code class=\"language-js\">const x = 1;</code></pre>",
+		parity: !0
+	},
+	{
+		title: "link with editor-default attrs",
+		input: e(t(n("Visit", [i]))),
+		expected: "<p><a target=\"_blank\" rel=\"noopener noreferrer nofollow\" href=\"https://example.com\">Visit</a></p>",
+		parity: !0
+	},
+	{
+		title: "link spanning differently-marked text renders one anchor",
+		input: e(t(n("go ", [i]), n("bold", [i, { type: "bold" }]), n(" now", [i]))),
+		expected: "<p><a target=\"_blank\" rel=\"noopener noreferrer nofollow\" href=\"https://example.com\">go <strong>bold</strong> now</a></p>",
+		parity: !0
+	},
+	{
+		title: "text escaping of angle brackets and ampersands",
+		input: e(t(n("a < b & c > d"))),
+		expected: "<p>a &lt; b &amp; c &gt; d</p>",
+		parity: !0
+	},
+	{
+		title: "javascript: href is sanitized to empty (intentionally stricter than TipTap)",
+		input: e(t(n("x", [{
+			type: "link",
+			attrs: { href: "javascript:alert(1)" }
+		}]))),
+		expected: "<p><a href=\"\">x</a></p>",
+		parity: !1
+	},
+	{
+		title: "unknown node types are skipped",
+		input: e({
+			type: "schema",
+			attrs: { data: {} }
+		}, t(n("kept"))),
+		expected: "<p>kept</p>",
+		parity: !1
+	}
+];
+//#endregion
+export { a as richTextFixtures };

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@localess/richtext",
+  "version": "3.4.1-dev.20260831165456",
+  "description": "Framework-neutral rich text model and renderer for Localess's TipTap JSON content.",
+  "keywords": [
+    "localess",
+    "sdk",
+    "richtext",
+    "tiptap",
+    "javascript",
+    "typescript"
+  ],
+  "author": "Lessify",
+  "homepage": "https://github.com/Lessify/localess-js",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "SKILL.md"
+  ],
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./test-utils": {
+      "types": "./dist/test-utils/index.d.ts",
+      "import": "./dist/test-utils/index.mjs",
+      "require": "./dist/test-utils/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lessify/localess-js.git",
+    "directory": "packages/richtext"
+  },
+  "bugs": {
+    "url": "https://github.com/Lessify/localess-js/issues"
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@tiptap/extension-bold": "^3.22.5",
+    "@tiptap/extension-bullet-list": "^3.22.5",
+    "@tiptap/extension-code": "^3.22.5",
+    "@tiptap/extension-code-block-lowlight": "^3.22.5",
+    "@tiptap/extension-document": "^3.22.5",
+    "@tiptap/extension-heading": "^3.22.5",
+    "@tiptap/extension-history": "^3.22.5",
+    "@tiptap/extension-italic": "^3.22.5",
+    "@tiptap/extension-link": "^3.22.5",
+    "@tiptap/extension-list-item": "^3.22.5",
+    "@tiptap/extension-ordered-list": "^3.22.5",
+    "@tiptap/extension-paragraph": "^3.22.5",
+    "@tiptap/extension-strike": "^3.22.5",
+    "@tiptap/extension-text": "^3.22.5",
+    "@tiptap/extension-underline": "^3.22.5",
+    "@tiptap/html": "^3.22.5",
+    "@types/node": "^24",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.16",
+    "vite-plugin-dts": "^5.0.0"
+  },
+  "engines": {
+    "node": ">= 24.0.0"
+  }
+}