@reticlehq/babel-plugin 2.13.1 → 2.14.0

package/dist/dom-tags.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The lowercase JSX tags that are actually DOM elements.
+ *
+ * "Lowercase means host element" was the rule, and it is true only for React DOM. React is a
+ * reconciler interface, not a renderer: react-three-fiber, react-pdf, ink and friends define their
+ * own lowercase intrinsics, and those host instances are not nodes and do not take attributes.
+ *
+ * R3F is the case that bit. Its `applyProps` treats any prop containing a dash as a PIERCED
+ * PROPERTY PATH, so `data-reticle-source` is walked as `data` -> `reticle` -> `source`; there is no
+ * `data` object on a three.js instance, and it throws from inside the commit phase. Unhandled there,
+ * the whole React tree unmounts to a white screen — and because it needs an element UPDATE rather
+ * than a mount, it fires long after the app looked fine.
+ *
+ * So the check is an ALLOWLIST, not a heuristic. The set of custom-reconciler intrinsics is
+ * unbounded and cannot be enumerated; the set of HTML and SVG tags can. Getting it wrong in the
+ * conservative direction costs one source pointer on an exotic element. Getting it wrong the other
+ * way costs the user their entire app.
+ *
+ * WHAT THIS DOES NOT COVER, stated rather than implied: a handful of three.js class names collide
+ * with real DOM tags — `line` is both `<line>` in SVG and `THREE.Line`, and `audio` is both. A tag
+ * name alone cannot separate them, and a lexical "is it under a <Canvas>" walk only sees the file
+ * it is transforming, so a scene component in its own file would still slip through. The complete
+ * answer for a three.js app is `reticle({ sourceMapping: false })` — which `reticle init` writes on
+ * its own when it finds one of these renderers in the manifest (see `Detection.customReconciler`).
+ *
+ * This paragraph described that as already true for a release in which it was not: nothing read the
+ * manifest, and the crash reached new installs anyway. The allowlist below is a mitigation, not the
+ * remedy; the manifest check is the remedy.
+ */
+/**
+ * Whether `tag` names a DOM element that will accept an arbitrary `data-*` attribute.
+ *
+ * Custom elements are deliberately included: a tag containing a dash is a valid custom element per
+ * the HTML spec, it IS a DOM node, and `data-*` on it is ordinary. That rule cannot collide with a
+ * custom reconciler's intrinsics, which are bare identifiers (`mesh`, `group`, `box`).
+ */
+export declare function isDomTag(tag: string): boolean;

package/dist/dom-tags.js

@@ -0,0 +1,274 @@
+"use strict";
+/**
+ * The lowercase JSX tags that are actually DOM elements.
+ *
+ * "Lowercase means host element" was the rule, and it is true only for React DOM. React is a
+ * reconciler interface, not a renderer: react-three-fiber, react-pdf, ink and friends define their
+ * own lowercase intrinsics, and those host instances are not nodes and do not take attributes.
+ *
+ * R3F is the case that bit. Its `applyProps` treats any prop containing a dash as a PIERCED
+ * PROPERTY PATH, so `data-reticle-source` is walked as `data` -> `reticle` -> `source`; there is no
+ * `data` object on a three.js instance, and it throws from inside the commit phase. Unhandled there,
+ * the whole React tree unmounts to a white screen — and because it needs an element UPDATE rather
+ * than a mount, it fires long after the app looked fine.
+ *
+ * So the check is an ALLOWLIST, not a heuristic. The set of custom-reconciler intrinsics is
+ * unbounded and cannot be enumerated; the set of HTML and SVG tags can. Getting it wrong in the
+ * conservative direction costs one source pointer on an exotic element. Getting it wrong the other
+ * way costs the user their entire app.
+ *
+ * WHAT THIS DOES NOT COVER, stated rather than implied: a handful of three.js class names collide
+ * with real DOM tags — `line` is both `<line>` in SVG and `THREE.Line`, and `audio` is both. A tag
+ * name alone cannot separate them, and a lexical "is it under a <Canvas>" walk only sees the file
+ * it is transforming, so a scene component in its own file would still slip through. The complete
+ * answer for a three.js app is `reticle({ sourceMapping: false })` — which `reticle init` writes on
+ * its own when it finds one of these renderers in the manifest (see `Detection.customReconciler`).
+ *
+ * This paragraph described that as already true for a release in which it was not: nothing read the
+ * manifest, and the crash reached new installs anyway. The allowlist below is a mitigation, not the
+ * remedy; the manifest check is the remedy.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDomTag = isDomTag;
+/** Every HTML element name, including the deprecated ones a real codebase still contains. */
+const HTML_TAGS = [
+    'a',
+    'abbr',
+    'address',
+    'area',
+    'article',
+    'aside',
+    'audio',
+    'b',
+    'base',
+    'bdi',
+    'bdo',
+    'big',
+    'blockquote',
+    'body',
+    'br',
+    'button',
+    'canvas',
+    'caption',
+    'center',
+    'cite',
+    'code',
+    'col',
+    'colgroup',
+    'data',
+    'datalist',
+    'dd',
+    'del',
+    'details',
+    'dfn',
+    'dialog',
+    'div',
+    'dl',
+    'dt',
+    'em',
+    'embed',
+    'fieldset',
+    'figcaption',
+    'figure',
+    'font',
+    'footer',
+    'form',
+    'frame',
+    'frameset',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'head',
+    'header',
+    'hgroup',
+    'hr',
+    'html',
+    'i',
+    'iframe',
+    'img',
+    'input',
+    'ins',
+    'kbd',
+    'keygen',
+    'label',
+    'legend',
+    'li',
+    'link',
+    'main',
+    'map',
+    'mark',
+    'marquee',
+    'menu',
+    'menuitem',
+    'meta',
+    'meter',
+    'nav',
+    'nobr',
+    'noframes',
+    'noscript',
+    'object',
+    'ol',
+    'optgroup',
+    'option',
+    'output',
+    'p',
+    'param',
+    'picture',
+    'pre',
+    'progress',
+    'q',
+    'rp',
+    'rt',
+    'ruby',
+    's',
+    'samp',
+    'script',
+    'search',
+    'section',
+    'select',
+    'slot',
+    'small',
+    'source',
+    'span',
+    'strike',
+    'strong',
+    'style',
+    'sub',
+    'summary',
+    'sup',
+    'table',
+    'tbody',
+    'td',
+    'template',
+    'textarea',
+    'tfoot',
+    'th',
+    'thead',
+    'time',
+    'title',
+    'tr',
+    'track',
+    'u',
+    'ul',
+    'var',
+    'video',
+    'wbr',
+];
+/**
+ * SVG element names. Included because SVG is DOM — a `data-*` attribute on `<path>` is as valid as
+ * one on `<div>`, and an app whose UI is a chart would otherwise lose every source pointer in it.
+ *
+ * The camelCase members (`clipPath`, `linearGradient`, …) are real JSX intrinsics in React DOM and
+ * are matched exactly, so the lookup below cannot be case-folded.
+ */
+const SVG_TAGS = [
+    'animate',
+    'animateMotion',
+    'animateTransform',
+    'circle',
+    'clipPath',
+    'defs',
+    'desc',
+    'ellipse',
+    'feBlend',
+    'feColorMatrix',
+    'feComponentTransfer',
+    'feComposite',
+    'feConvolveMatrix',
+    'feDiffuseLighting',
+    'feDisplacementMap',
+    'feDistantLight',
+    'feDropShadow',
+    'feFlood',
+    'feFuncA',
+    'feFuncB',
+    'feFuncG',
+    'feFuncR',
+    'feGaussianBlur',
+    'feImage',
+    'feMerge',
+    'feMergeNode',
+    'feMorphology',
+    'feOffset',
+    'fePointLight',
+    'feSpecularLighting',
+    'feSpotLight',
+    'feTile',
+    'feTurbulence',
+    'filter',
+    'foreignObject',
+    'g',
+    'image',
+    'line',
+    'linearGradient',
+    'marker',
+    'mask',
+    'metadata',
+    'mpath',
+    'path',
+    'pattern',
+    'polygon',
+    'polyline',
+    'radialGradient',
+    'rect',
+    'set',
+    'stop',
+    'svg',
+    'switch',
+    'symbol',
+    'text',
+    'textPath',
+    'tspan',
+    'use',
+    'view',
+];
+/**
+ * MathML, for completeness: also DOM, also takes `data-*`. Small enough that omitting it would be a
+ * deliberate blind spot rather than a saving.
+ */
+const MATHML_TAGS = [
+    'annotation',
+    'annotation-xml',
+    'maction',
+    'math',
+    'merror',
+    'mfrac',
+    'mi',
+    'mmultiscripts',
+    'mn',
+    'mo',
+    'mover',
+    'mpadded',
+    'mphantom',
+    'mprescripts',
+    'mroot',
+    'mrow',
+    'ms',
+    'mspace',
+    'msqrt',
+    'mstyle',
+    'msub',
+    'msubsup',
+    'msup',
+    'mtable',
+    'mtd',
+    'mtext',
+    'mtr',
+    'munder',
+    'munderover',
+    'semantics',
+];
+const DOM_TAGS = new Set([...HTML_TAGS, ...SVG_TAGS, ...MATHML_TAGS]);
+/**
+ * Whether `tag` names a DOM element that will accept an arbitrary `data-*` attribute.
+ *
+ * Custom elements are deliberately included: a tag containing a dash is a valid custom element per
+ * the HTML spec, it IS a DOM node, and `data-*` on it is ordinary. That rule cannot collide with a
+ * custom reconciler's intrinsics, which are bare identifiers (`mesh`, `group`, `box`).
+ */
+function isDomTag(tag) {
+    return DOM_TAGS.has(tag) || (tag.includes('-') && !tag.startsWith('-'));
+}

package/dist/index.js

@@ -1,6 +1,7 @@
 "use strict";
 const node_path_1 = require("node:path");
 const source_constants_1 = require("@reticlehq/core/source-constants");
+const dom_tags_js_1 = require("./dom-tags.js");
 const SOURCE_ATTR = source_constants_1.DATA_RETICLE_SOURCE_ATTR;
 /**
  * Stamps `data-reticle-source="relativeFile:line:col"` on every JSX host element (lowercase
@@ -22,9 +23,16 @@ function reticleSourcePlugin({ types: t }) {
                 // Host elements only (e.g. <div>, <button>) — skip components (<App />).
                 if (node.name.type !== 'JSXIdentifier')
                     return;
-                const first = node.name.name[0];
+                const tag = node.name.name;
+                const first = tag[0];
                 if (first === undefined || first !== first.toLowerCase())
                     return;
+                // ...and only host elements that are DOM. React is a reconciler interface, so a lowercase
+                // intrinsic can belong to react-three-fiber, react-pdf or ink, whose host instances are not
+                // nodes. R3F reads a dashed prop as a pierced property path and throws from the commit
+                // phase, which unmounts the entire app to a white screen. See dom-tags.ts.
+                if (!(0, dom_tags_js_1.isDomTag)(tag))
+                    return;
                 const alreadyStamped = node.attributes.some((attr) => 'JSXAttribute' === attr.type &&
                     'JSXIdentifier' === attr.name.type &&
                     attr.name.name === SOURCE_ATTR);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/babel-plugin",
-  "version": "2.13.1",
+  "version": "2.14.0",
   "description": "Babel plugin that stamps data-reticle-source=\"file:line:col\" on JSX host elements so @reticlehq/react can map a DOM node to its source (works on React 19, which dropped _debugSource).",
   "type": "commonjs",
   "license": "Apache-2.0",
@@ -35,7 +35,7 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@reticlehq/core": "2.13.1"
+    "@reticlehq/core": "2.14.0"
   },
   "peerDependencies": {
     "@babel/core": "^7"