@barefootjs/shared 0.18.3 → 0.18.5

package/dist/dom-prop.d.ts

@@ -42,9 +42,11 @@ export declare function toHTMLAttrName(key: string): string;
  * Runtime variant of attribute name mapping that additionally applies
  * camelCase→kebab conversion for `data-*` and `aria-*` convenience
  * props (e.g. `dataTestId` → `data-test-id`) and preserves SVG XML
- * attribute casing. All other non-SVG keys pass through unchanged —
- * standard HTML attributes like `tabIndex` and `autoFocus` must not
- * be kebab-cased (`tab-index` / `auto-focus` are not valid attrs).
+ * attribute casing. HTML camelCase aliases resolve through the same
+ * `HTML_CAMEL_ALIASES` table as the compile-time variant (`tabIndex` →
+ * `tabindex`); generic kebab-casing still applies ONLY to `data-*` /
+ * `aria-*` — an unknown camelCase key passes through unchanged rather
+ * than being guessed into a hyphenated non-attribute.
  */
 export declare function toHTMLAttrNameRuntime(key: string): string;
 /**

package/dist/html-entities.d.ts

@@ -0,0 +1,43 @@
+/**
+ * HTML character-reference decoding and escaping for STATIC template
+ * content.
+ *
+ * JSX decodes character references at parse time: `<span>Fish &amp;
+ * Chips</span>` means the TEXT `Fish & Chips`, and `&copy;` means `©`
+ * (Babel/esbuild/TypeScript's JSX emit all decode). Phase 1
+ * (`jsx-to-ir`) applies `decodeEntities` once so `IRText.value` and
+ * static attribute values carry the DECODED text — the semantics —
+ * and every adapter re-escapes for its own emission context
+ * (`escapeHtml` for HTML template output; the Hono adapter
+ * re-encodes for JSX source). An adapter that emitted the raw entity
+ * text passed `&copy;` through as bytes while the reference decoded it
+ * (the `html-entity-text` divergence), and one that skipped
+ * re-escaping emitted a parse-corrupting `<`.
+ *
+ * The named table is the curated set below, not the full HTML5 list
+ * (~2,200 names): an unknown name (`&foo;`) is left as raw text, so
+ * BOTH the reference adapter and the template adapters receive the
+ * same undecoded string from the IR and stay byte-identical — the
+ * degradation is consistent, exactly how a browser treats an unknown
+ * reference. Numeric references (`&#169;` / `&#xA9;`) decode fully.
+ */
+/**
+ * Decode HTML character references in JSX literal text / static
+ * attribute values: numeric decimal (`&#169;`), numeric hex
+ * (`&#xA9;`), and the curated named set above. Anything unrecognized
+ * (unknown name, malformed numeric, bare `&`) is left verbatim.
+ */
+export declare function decodeEntities(text: string): string;
+/**
+ * Escape decoded static text for direct HTML emission: `&` `<` `>`
+ * `"` to their named forms. Used for BOTH text nodes and double-quoted
+ * attribute values — one set, no context-dependent under-escaping.
+ *
+ * `'` is deliberately NOT escaped: the reference (Hono JSX) escapes it
+ * as `&#39;`, but raw `'` is valid everywhere outside single-quoted
+ * attributes (which no adapter emits), and the conformance harness's
+ * `normalizeHTML` canonicalises the raw and entity forms to one
+ * spelling on both sides — so leaving apostrophes raw keeps every
+ * existing template byte-stable instead of rewriting all prose text.
+ */
+export declare function escapeHtml(text: string): string;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { BF_SCOPE, BF_SLOT, BF_HOST, BF_AT, BF_ROOT, BF_PROPS, BF_COND, BF_ITEM, BF_PORTAL_OWNER, BF_PORTAL_ID, BF_PORTAL_PLACEHOLDER, BF_PARENT_OWNED_PREFIX, BF_SCOPE_COMMENT_PREFIX, BF_LOOP_START, BF_LOOP_END, BF_LOOP_ITEM, loopItemMarker, loopStartMarker, loopEndMarker, BF_KEY, BF_KEY_PREFIX, BF_PLACEHOLDER, BF_ASYNC, BF_ASYNC_RESOLVE, BF_REGION, BF_PARENT_SCOPE_PLACEHOLDER, BF_SEAM_HYDRATE, BF_SEAM_HYDRATE_WITHIN, BF_SEAM_DISPOSE_WITHIN, BF_SEAM_PUSH_SEARCH, BF_SEAM_NAV_SEARCH, } from './markers.ts';
 export { classifyDOMProp, toHTMLAttrName, toHTMLAttrNameRuntime, isBooleanAttr, isEventProp, BOOLEAN_ATTRS, } from './dom-prop.ts';
 export type { DOMPropKind, DOMPropClassification } from './dom-prop.ts';
+export { decodeEntities, escapeHtml } from './html-entities.ts';
 export type { ProfilerEvent, ProfilerEventType, ProfilerSubscriberKind, } from './profiler-events.ts';

package/dist/index.js

@@ -84,6 +84,63 @@ var SVG_CAMEL_TO_KEBAB = {
   markerMid: "marker-mid",
   markerEnd: "marker-end"
 };
+var HTML_CAMEL_ALIASES = {
+  acceptCharset: "accept-charset",
+  accessKey: "accesskey",
+  allowFullScreen: "allowfullscreen",
+  autoCapitalize: "autocapitalize",
+  autoComplete: "autocomplete",
+  autoCorrect: "autocorrect",
+  autoFocus: "autofocus",
+  autoPlay: "autoplay",
+  cellPadding: "cellpadding",
+  cellSpacing: "cellspacing",
+  charSet: "charset",
+  colSpan: "colspan",
+  contentEditable: "contenteditable",
+  controlsList: "controlslist",
+  crossOrigin: "crossorigin",
+  dateTime: "datetime",
+  dirName: "dirname",
+  encType: "enctype",
+  enterKeyHint: "enterkeyhint",
+  fetchPriority: "fetchpriority",
+  formAction: "formaction",
+  formEncType: "formenctype",
+  formMethod: "formmethod",
+  formNoValidate: "formnovalidate",
+  formTarget: "formtarget",
+  frameBorder: "frameborder",
+  hrefLang: "hreflang",
+  httpEquiv: "http-equiv",
+  imageSizes: "imagesizes",
+  imageSrcSet: "imagesrcset",
+  inputMode: "inputmode",
+  itemID: "itemid",
+  itemProp: "itemprop",
+  itemRef: "itemref",
+  itemScope: "itemscope",
+  itemType: "itemtype",
+  marginHeight: "marginheight",
+  marginWidth: "marginwidth",
+  maxLength: "maxlength",
+  minLength: "minlength",
+  noModule: "nomodule",
+  noValidate: "novalidate",
+  playsInline: "playsinline",
+  popoverTarget: "popovertarget",
+  popoverTargetAction: "popovertargetaction",
+  radioGroup: "radiogroup",
+  readOnly: "readonly",
+  referrerPolicy: "referrerpolicy",
+  rowSpan: "rowspan",
+  spellCheck: "spellcheck",
+  srcDoc: "srcdoc",
+  srcLang: "srclang",
+  srcSet: "srcset",
+  tabIndex: "tabindex",
+  useMap: "usemap"
+};
 var SVG_XML_CAMEL_ATTRS = new Set([
   "allowReorder",
   "attributeName",
@@ -178,6 +235,9 @@ function toHTMLAttrName(key) {
     return "class";
   if (key === "htmlFor")
     return "for";
+  const htmlAlias = HTML_CAMEL_ALIASES[key];
+  if (htmlAlias !== undefined)
+    return htmlAlias;
   const svgKebab = SVG_CAMEL_TO_KEBAB[key];
   if (svgKebab !== undefined)
     return svgKebab;
@@ -188,6 +248,9 @@ function toHTMLAttrNameRuntime(key) {
     return "class";
   if (key === "htmlFor")
     return "for";
+  const htmlAlias = HTML_CAMEL_ALIASES[key];
+  if (htmlAlias !== undefined)
+    return htmlAlias;
   const svgKebab = SVG_CAMEL_TO_KEBAB[key];
   if (svgKebab !== undefined)
     return svgKebab;
@@ -201,6 +264,76 @@ function toHTMLAttrNameRuntime(key) {
 function isBooleanAttr(name) {
   return BOOLEAN_ATTRS.has(name.toLowerCase());
 }
+// src/html-entities.ts
+var NAMED_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  copy: "©",
+  reg: "®",
+  trade: "™",
+  deg: "°",
+  plusmn: "±",
+  times: "×",
+  divide: "÷",
+  middot: "·",
+  bull: "•",
+  hellip: "…",
+  ndash: "–",
+  mdash: "—",
+  lsquo: "‘",
+  rsquo: "’",
+  ldquo: "“",
+  rdquo: "”",
+  laquo: "«",
+  raquo: "»",
+  sect: "§",
+  para: "¶",
+  dagger: "†",
+  Dagger: "‡",
+  euro: "€",
+  pound: "£",
+  yen: "¥",
+  cent: "¢",
+  sup1: "¹",
+  sup2: "²",
+  sup3: "³",
+  frac12: "½",
+  frac14: "¼",
+  frac34: "¾",
+  larr: "←",
+  uarr: "↑",
+  rarr: "→",
+  darr: "↓",
+  harr: "↔",
+  minus: "−",
+  infin: "∞",
+  ne: "≠",
+  le: "≤",
+  ge: "≥"
+};
+function decodeEntities(text) {
+  return text.replace(/&(#[xX]?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (match, body) => {
+    if (body[0] === "#") {
+      const isHex = body[1] === "x" || body[1] === "X";
+      const digits = body.slice(isHex ? 2 : 1);
+      if (!isHex && !/^[0-9]+$/.test(digits))
+        return match;
+      const code = parseInt(digits, isHex ? 16 : 10);
+      if (!Number.isFinite(code) || code > 1114111 || code >= 55296 && code <= 57343) {
+        return match;
+      }
+      return String.fromCodePoint(code);
+    }
+    return NAMED_ENTITIES[body] ?? match;
+  });
+}
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
 export {
   toHTMLAttrNameRuntime,
   toHTMLAttrName,
@@ -209,6 +342,8 @@ export {
   loopEndMarker,
   isEventProp,
   isBooleanAttr,
+  escapeHtml,
+  decodeEntities,
   classifyDOMProp,
   BOOLEAN_ATTRS,
   BF_SLOT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/shared",
-  "version": "0.18.3",
+  "version": "0.18.5",
   "description": "Shared constants for BarefootJS compiler and runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/dom-prop.test.ts

@@ -106,12 +106,27 @@ describe('toHTMLAttrName (compile-time)', () => {
     expect(toHTMLAttrName('strokeWidth')).toBe('stroke-width')
   })
 
-  test('tabIndex passes through (no generic kebab)', () => {
-    expect(toHTMLAttrName('tabIndex')).toBe('tabIndex')
+  // #2172: HTML camelCase aliases resolve through HTML_CAMEL_ALIASES —
+  // these are known HTML attributes with a defined lowercase spelling,
+  // NOT the generic kebab conversion (which stays data-*/aria-* only).
+  test('tabIndex lowers to tabindex (HTML alias table)', () => {
+    expect(toHTMLAttrName('tabIndex')).toBe('tabindex')
   })
 
-  test('autoFocus passes through (no generic kebab)', () => {
-    expect(toHTMLAttrName('autoFocus')).toBe('autoFocus')
+  test('autoFocus lowers to autofocus (HTML alias table)', () => {
+    expect(toHTMLAttrName('autoFocus')).toBe('autofocus')
+  })
+
+  test('readOnly lowers to the BOOLEAN_ATTRS member readonly', () => {
+    expect(toHTMLAttrName('readOnly')).toBe('readonly')
+  })
+
+  test('spellCheck lowers to the enumerated (non-boolean) spellcheck', () => {
+    expect(toHTMLAttrName('spellCheck')).toBe('spellcheck')
+  })
+
+  test('unknown camelCase names still pass through unchanged', () => {
+    expect(toHTMLAttrName('myCustomAttr')).toBe('myCustomAttr')
   })
 })
 
@@ -144,12 +159,24 @@ describe('toHTMLAttrNameRuntime', () => {
     expect(toHTMLAttrNameRuntime('ariaLabel')).toBe('aria-label')
   })
 
-  test('tabIndex passes through (no kebab)', () => {
-    expect(toHTMLAttrNameRuntime('tabIndex')).toBe('tabIndex')
+  test('tabIndex lowers to tabindex (HTML alias table, #2172)', () => {
+    expect(toHTMLAttrNameRuntime('tabIndex')).toBe('tabindex')
+  })
+
+  test('autoFocus lowers to autofocus (HTML alias table, #2172)', () => {
+    expect(toHTMLAttrNameRuntime('autoFocus')).toBe('autofocus')
+  })
+
+  test('readOnly lowers to the boolean attr spelling readonly (HTML alias table, #2172)', () => {
+    expect(toHTMLAttrNameRuntime('readOnly')).toBe('readonly')
+  })
+
+  test('spellCheck lowers to the enumerated attr spelling spellcheck (HTML alias table, #2172)', () => {
+    expect(toHTMLAttrNameRuntime('spellCheck')).toBe('spellcheck')
   })
 
-  test('autoFocus passes through (no kebab)', () => {
-    expect(toHTMLAttrNameRuntime('autoFocus')).toBe('autoFocus')
+  test('unknown camelCase names still pass through unchanged', () => {
+    expect(toHTMLAttrNameRuntime('myCustomAttr')).toBe('myCustomAttr')
   })
 })
 

package/src/__tests__/html-entities.test.ts

@@ -0,0 +1,54 @@
+import { describe, test, expect } from 'bun:test'
+import { decodeEntities, escapeHtml } from '../html-entities'
+
+describe('decodeEntities', () => {
+  test('escaping-set names decode', () => {
+    expect(decodeEntities('Fish & Chips')).toBe('Fish & Chips')
+    expect(decodeEntities('a &lt; b &gt; c')).toBe('a < b > c')
+    expect(decodeEntities('&quot;x&quot; &apos;y&apos;')).toBe(`"x" 'y'`)
+  })
+
+  test('common typographic names decode', () => {
+    expect(decodeEntities('&copy; 2026')).toBe('© 2026')
+    expect(decodeEntities('1&nbsp;000')).toBe('1 000')
+    expect(decodeEntities('A&hellip;')).toBe('A…')
+    expect(decodeEntities('&euro;5 / &pound;4 / &yen;3')).toBe('€5 / £4 / ¥3')
+  })
+
+  test('numeric decimal and hex references decode', () => {
+    expect(decodeEntities('&#169;')).toBe('©')
+    expect(decodeEntities('&#xA9;')).toBe('©')
+    expect(decodeEntities('&#x1F600;')).toBe('😀')
+  })
+
+  test('unknown / malformed references stay verbatim', () => {
+    expect(decodeEntities('&unknownname;')).toBe('&unknownname;')
+    expect(decodeEntities('a & b')).toBe('a & b')
+    expect(decodeEntities('&amp')).toBe('&amp')
+    // Lone surrogate / out-of-range code points are refused, not
+    // replaced with garbage.
+    expect(decodeEntities('&#xD800;')).toBe('&#xD800;')
+    expect(decodeEntities('&#x110000;')).toBe('&#x110000;')
+  })
+
+  test('double-escaped input decodes exactly one level', () => {
+    expect(decodeEntities('&amp;copy;')).toBe('&copy;')
+  })
+})
+
+describe('escapeHtml', () => {
+  test('escapes & < > " and leaves the rest', () => {
+    expect(escapeHtml('Fish & Chips')).toBe('Fish &amp; Chips')
+    expect(escapeHtml('a < b > c')).toBe('a &lt; b &gt; c')
+    expect(escapeHtml('say "hi"')).toBe('say &quot;hi&quot;')
+    expect(escapeHtml("it's © fine")).toBe("it's © fine")
+  })
+
+  test('decode → escape round-trips the entity text', () => {
+    expect(escapeHtml(decodeEntities('Fish &amp; Chips'))).toBe('Fish &amp; Chips')
+    expect(escapeHtml(decodeEntities('a &lt; b'))).toBe('a &lt; b')
+    // Named references outside the escape set stay decoded — the
+    // literal character is the canonical emission (`©`, not `&copy;`).
+    expect(escapeHtml(decodeEntities('&copy; 2026'))).toBe('© 2026')
+  })
+})

package/src/dom-prop.ts

@@ -72,6 +72,79 @@ const SVG_CAMEL_TO_KEBAB: Readonly<Record<string, string>> = {
   markerEnd: 'marker-end',
 }
 
+/**
+ * HTML attributes written in React-style camelCase in JSX that map to a
+ * lowercase (or hyphenated) HTML attribute name. Mirrors React DOM's
+ * HTML attribute aliases. `className` / `htmlFor` are handled before
+ * this table (they predate it); everything here is a plain rename —
+ * value semantics are untouched (`readOnly` becomes the BOOLEAN_ATTRS
+ * member `readonly`; `spellCheck` stays the *enumerated* — NOT boolean
+ * — `spellcheck`).
+ *
+ * Consumed by `toHTMLAttrName` (compile-time Phase 1: `processAttributes`
+ * normalizes IRAttribute.name so adapters emit the HTML name as-is) and
+ * by `toHTMLAttrNameRuntime` (runtime spread paths). Names NOT in this
+ * table pass through unchanged, so `data-*`, `aria-*`, and custom-element
+ * attributes are never rewritten.
+ */
+const HTML_CAMEL_ALIASES: Readonly<Record<string, string>> = {
+  acceptCharset: 'accept-charset',
+  accessKey: 'accesskey',
+  allowFullScreen: 'allowfullscreen',
+  autoCapitalize: 'autocapitalize',
+  autoComplete: 'autocomplete',
+  autoCorrect: 'autocorrect',
+  autoFocus: 'autofocus',
+  autoPlay: 'autoplay',
+  cellPadding: 'cellpadding',
+  cellSpacing: 'cellspacing',
+  charSet: 'charset',
+  colSpan: 'colspan',
+  contentEditable: 'contenteditable',
+  controlsList: 'controlslist',
+  crossOrigin: 'crossorigin',
+  dateTime: 'datetime',
+  dirName: 'dirname',
+  encType: 'enctype',
+  enterKeyHint: 'enterkeyhint',
+  fetchPriority: 'fetchpriority',
+  formAction: 'formaction',
+  formEncType: 'formenctype',
+  formMethod: 'formmethod',
+  formNoValidate: 'formnovalidate',
+  formTarget: 'formtarget',
+  frameBorder: 'frameborder',
+  hrefLang: 'hreflang',
+  httpEquiv: 'http-equiv',
+  imageSizes: 'imagesizes',
+  imageSrcSet: 'imagesrcset',
+  inputMode: 'inputmode',
+  itemID: 'itemid',
+  itemProp: 'itemprop',
+  itemRef: 'itemref',
+  itemScope: 'itemscope',
+  itemType: 'itemtype',
+  marginHeight: 'marginheight',
+  marginWidth: 'marginwidth',
+  maxLength: 'maxlength',
+  minLength: 'minlength',
+  noModule: 'nomodule',
+  noValidate: 'novalidate',
+  playsInline: 'playsinline',
+  popoverTarget: 'popovertarget',
+  popoverTargetAction: 'popovertargetaction',
+  radioGroup: 'radiogroup',
+  readOnly: 'readonly',
+  referrerPolicy: 'referrerpolicy',
+  rowSpan: 'rowspan',
+  spellCheck: 'spellcheck',
+  srcDoc: 'srcdoc',
+  srcLang: 'srclang',
+  srcSet: 'srcset',
+  tabIndex: 'tabindex',
+  useMap: 'usemap',
+}
+
 /**
  * SVG XML attribute names that are case-sensitive and MUST stay in camelCase.
  *
@@ -169,6 +242,8 @@ export function classifyDOMProp(key: string): DOMPropClassification {
 export function toHTMLAttrName(key: string): string {
   if (key === 'className') return 'class'
   if (key === 'htmlFor')   return 'for'
+  const htmlAlias = HTML_CAMEL_ALIASES[key]
+  if (htmlAlias !== undefined) return htmlAlias
   const svgKebab = SVG_CAMEL_TO_KEBAB[key]
   if (svgKebab !== undefined) return svgKebab
   return key
@@ -178,13 +253,17 @@ export function toHTMLAttrName(key: string): string {
  * Runtime variant of attribute name mapping that additionally applies
  * camelCase→kebab conversion for `data-*` and `aria-*` convenience
  * props (e.g. `dataTestId` → `data-test-id`) and preserves SVG XML
- * attribute casing. All other non-SVG keys pass through unchanged —
- * standard HTML attributes like `tabIndex` and `autoFocus` must not
- * be kebab-cased (`tab-index` / `auto-focus` are not valid attrs).
+ * attribute casing. HTML camelCase aliases resolve through the same
+ * `HTML_CAMEL_ALIASES` table as the compile-time variant (`tabIndex` →
+ * `tabindex`); generic kebab-casing still applies ONLY to `data-*` /
+ * `aria-*` — an unknown camelCase key passes through unchanged rather
+ * than being guessed into a hyphenated non-attribute.
  */
 export function toHTMLAttrNameRuntime(key: string): string {
   if (key === 'className') return 'class'
   if (key === 'htmlFor')   return 'for'
+  const htmlAlias = HTML_CAMEL_ALIASES[key]
+  if (htmlAlias !== undefined) return htmlAlias
   const svgKebab = SVG_CAMEL_TO_KEBAB[key]
   if (svgKebab !== undefined) return svgKebab
   if (SVG_XML_CAMEL_ATTRS.has(key)) return key

package/src/html-entities.ts

@@ -0,0 +1,123 @@
+/**
+ * HTML character-reference decoding and escaping for STATIC template
+ * content.
+ *
+ * JSX decodes character references at parse time: `<span>Fish &amp;
+ * Chips</span>` means the TEXT `Fish & Chips`, and `&copy;` means `©`
+ * (Babel/esbuild/TypeScript's JSX emit all decode). Phase 1
+ * (`jsx-to-ir`) applies `decodeEntities` once so `IRText.value` and
+ * static attribute values carry the DECODED text — the semantics —
+ * and every adapter re-escapes for its own emission context
+ * (`escapeHtml` for HTML template output; the Hono adapter
+ * re-encodes for JSX source). An adapter that emitted the raw entity
+ * text passed `&copy;` through as bytes while the reference decoded it
+ * (the `html-entity-text` divergence), and one that skipped
+ * re-escaping emitted a parse-corrupting `<`.
+ *
+ * The named table is the curated set below, not the full HTML5 list
+ * (~2,200 names): an unknown name (`&foo;`) is left as raw text, so
+ * BOTH the reference adapter and the template adapters receive the
+ * same undecoded string from the IR and stay byte-identical — the
+ * degradation is consistent, exactly how a browser treats an unknown
+ * reference. Numeric references (`&#169;` / `&#xA9;`) decode fully.
+ */
+
+/**
+ * Named character references JSX authors actually write in literal
+ * text. `amp`/`lt`/`gt`/`quot`/`apos` are the escaping set itself;
+ * the rest are the common typographic/symbol names.
+ */
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  copy: '©',
+  reg: '®',
+  trade: '™',
+  deg: '°',
+  plusmn: '±',
+  times: '×',
+  divide: '÷',
+  middot: '·',
+  bull: '•',
+  hellip: '…',
+  ndash: '–',
+  mdash: '—',
+  lsquo: '‘',
+  rsquo: '’',
+  ldquo: '“',
+  rdquo: '”',
+  laquo: '«',
+  raquo: '»',
+  sect: '§',
+  para: '¶',
+  dagger: '†',
+  Dagger: '‡',
+  euro: '€',
+  pound: '£',
+  yen: '¥',
+  cent: '¢',
+  sup1: '¹',
+  sup2: '²',
+  sup3: '³',
+  frac12: '½',
+  frac14: '¼',
+  frac34: '¾',
+  larr: '←',
+  uarr: '↑',
+  rarr: '→',
+  darr: '↓',
+  harr: '↔',
+  minus: '−',
+  infin: '∞',
+  ne: '≠',
+  le: '≤',
+  ge: '≥',
+}
+
+/**
+ * Decode HTML character references in JSX literal text / static
+ * attribute values: numeric decimal (`&#169;`), numeric hex
+ * (`&#xA9;`), and the curated named set above. Anything unrecognized
+ * (unknown name, malformed numeric, bare `&`) is left verbatim.
+ */
+export function decodeEntities(text: string): string {
+  return text.replace(/&(#[xX]?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (match, body: string) => {
+    if (body[0] === '#') {
+      const isHex = body[1] === 'x' || body[1] === 'X'
+      const digits = body.slice(isHex ? 2 : 1)
+      if (!isHex && !/^[0-9]+$/.test(digits)) return match
+      const code = parseInt(digits, isHex ? 16 : 10)
+      // Reject out-of-range / lone-surrogate code points rather than
+      // producing replacement garbage — leave the reference raw.
+      if (!Number.isFinite(code) || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)) {
+        return match
+      }
+      return String.fromCodePoint(code)
+    }
+    return NAMED_ENTITIES[body] ?? match
+  })
+}
+
+/**
+ * Escape decoded static text for direct HTML emission: `&` `<` `>`
+ * `"` to their named forms. Used for BOTH text nodes and double-quoted
+ * attribute values — one set, no context-dependent under-escaping.
+ *
+ * `'` is deliberately NOT escaped: the reference (Hono JSX) escapes it
+ * as `&#39;`, but raw `'` is valid everywhere outside single-quoted
+ * attributes (which no adapter emits), and the conformance harness's
+ * `normalizeHTML` canonicalises the raw and entity forms to one
+ * spelling on both sides — so leaving apostrophes raw keeps every
+ * existing template byte-stable instead of rewriting all prose text.
+ */
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}

package/src/index.ts

@@ -41,6 +41,7 @@ export {
   BOOLEAN_ATTRS,
 } from './dom-prop.ts'
 export type { DOMPropKind, DOMPropClassification } from './dom-prop.ts'
+export { decodeEntities, escapeHtml } from './html-entities.ts'
 
 export type {
   ProfilerEvent,