独家

Invisibles `<mv-invisibles>`

在文本框中显示那些不可见和形似的字符，它们会导致真实的 bug：粘贴进 IBAN、邮箱、API 密钥和验证码中的零宽空格和连接符，不换行空格和特殊空格，首尾空白，制表符，软连字符，控制字符，双向控制字符（Trojan source），隐藏的标签文本，同形字（拉丁单词中的西里尔字母“а”，数字中的“O”），全角字母，以及命令中的智能引号或破折号。

文化出处

《隐身人》，H.G. 威尔斯（1897 年，小说）。隐身的科学家只有用绷带、衣服和护目镜裹住身体时才能被看见：看不见的东西，借助包裹它的轮廓变得可见。这个组件给每个不可见字符或形近字符包上一个可见的轮廓和一个简短名称，准确地放在它在字段中的位置，让这个字符能被看见、被理解、被删除。

工作原理

让文本字段中的不可见字符和形近字符显形，它们会造成真实的 bug：粘贴进 IBAN、邮箱、API 密钥和代码中的零宽空格和零宽连接符，不换行空格和各种特殊空格，首尾空白，制表符，软连字符，控制字符，双向文本控制符（Trojan Source），隐藏的标签字符文本，同形字（拉丁单词中的西里尔字母“а”，数字中的“O”），全角字母，以及命令中的弯引号或长短横线。包裹一个 input 或 textarea：一个精确且同步滚动的镜像层（相同的字体度量、内边距和换行）在每个不可见字符周围画出轮廓：零宽字符用细长胶囊，异常空格用方括号，首尾空白用斜线阴影，形近字符用点状下划线；单行字段还会在文字正下方标出它们的简短代码（ZWSP、NBSP、⇥、RLO、CYR……）。悬停在标记上，或把光标移到它旁边，会显示该字符的名称、码位以及它为何重要。摘要行（“3 hidden characters · 1 look-alike”）提供一键修复（Remove invisible characters、Normalize spaces、Replace look-alikes），这些修复经由浏览器的编辑管线执行，因此 Ctrl/Cmd+Z 可以撤销，另外还有一个 Undo 按钮；详情列表可以在字段中选中每一处发现。规则随字段而定（profile 可为 iban、email、code、username、text 或 prose：emoji 连接符、连写文字和法语不换行空格在该保留的地方保持合法），validate 会设置自定义校验消息，mv-invisibles 会报告发现了什么，mv-fix 可以否决某次修复。以 <pre> 或 <code> 为目标时会就地显形，每个双向控制符都被隔离，使文本按其真实的存储顺序显示，并提供 Copy clean text。检测器以 findInvisibles() / cleanInvisibles() 导出，可在服务器上应用相同的规则。

分类	表单
类型	Web Component（`<mv-invisibles>`）
状态	稳定版
套件	不让用户流失的表单
同时安装	button
Keywords	exclusive, culture, form, validation, input, textarea, unicode, zero-width, whitespace, nbsp, homoglyph, confusable, trojan-source, bidi, sanitize, paste, iban, security, undo, code

When to use

Users paste IBANs, emails, API keys or codes copied from PDFs, chats or web pages, and silent mismatches reach support
A username or email field must catch homoglyph impersonation (Cyrillic or Greek letters inside Latin names)
Commands or config snippets are pasted from docs that turned quotes and dashes into typographic characters
A code review or snippet view must expose bidi controls and hidden text before anyone trusts what they read

Avoid when

The value only needs a format check (length, pattern, checksum) and invisible characters can simply be stripped on submit
The field is a password: the mirror cannot follow masked text, sanitize on the server instead
The text is a rich-text document (contenteditable, WYSIWYG editor); the mirror only follows native inputs and textareas

安装

node scripts/add.mjs invisibles --out ./src/marvelous

使用 Marvelous UI MCP 服务器的 AI 智能体：install_components({ slugs: ["invisibles"], target_dir: "<absolute path>/src/marvelous", framework: "react" })。

复制的文件（含依赖）：tokens/tokens.css, core/base.css, components/button/button.css, core/dom.js, core/element.js, core/observe.js, components/invisibles/invisibles.js, components/invisibles/invisibles.css。

用法

快速开始，最小可运行标记：

<mv-invisibles profile="iban">
  <label for="iban">IBAN</label>
  <input id="iban" value="FR76 3000 6000 0112&#8203;3456 7890 189">
</mv-invisibles>

标准标记，可在此基础上通过属性、data-* 和 CSS 变量进行定制：

<div id="iv-demo" style="width:min(100%,66rem);margin-inline:auto">
  <style>
    #iv-demo .iv-grid { display:grid; grid-template-columns:minmax(0,1fr) minmax(0,1.1fr); gap:1.25rem; align-items:start }
    #iv-demo .iv-col { display:grid; gap:1.25rem; min-width:0 }
    #iv-demo .iv-card { display:grid; gap:1.125rem; min-width:0; margin:0; padding:1.25rem; border:1px solid var(--mv-border); border-radius:var(--mv-radius-xl); background:var(--mv-surface); box-shadow:var(--mv-shadow-sm) }
    #iv-demo .iv-card > * { min-width:0 }
    #iv-demo .iv-head { display:flex; align-items:flex-start; justify-content:space-between; gap:.75rem }
    #iv-demo .iv-head h3 { margin:0; font-size:1rem; letter-spacing:-.01em }
    #iv-demo .iv-head p { margin:.1875rem 0 0; color:var(--mv-fg-muted); font-size:.8125rem; line-height:1.45 }
    #iv-demo .iv-mono { font-family:var(--mv-font-mono); font-size:.8125rem }
    #iv-demo textarea.iv-mono { font-size:.75rem; line-height:1.6 }
    #iv-demo .iv-foot { display:flex; align-items:center; justify-content:flex-end; gap:.5rem; flex-wrap:wrap; padding-top:1rem; border-top:1px solid var(--mv-border) }
    #iv-demo .iv-saved { margin-inline-end:auto; color:var(--mv-fg-muted); font-size:.75rem }
    #iv-demo .iv-code { margin:0; padding:.75rem .875rem; border:1px solid var(--mv-border); border-radius:var(--mv-radius-lg); background:var(--mv-bg-subtle); font:.75rem/1.7 var(--mv-font-mono); font-variant-ligatures:none; overflow-x:auto; white-space:pre }
    #iv-demo .iv-k { display:block; margin:0 0 .375rem; color:var(--mv-fg-muted); font-size:.6875rem; font-weight:600; letter-spacing:.04em; text-transform:uppercase }
    #iv-demo .iv-seen { margin:0; padding:.5rem .875rem; border:1px dashed var(--mv-border-strong); border-radius:var(--mv-radius-lg); color:var(--mv-fg-muted); font:.75rem/1.7 var(--mv-font-mono); font-variant-ligatures:none; white-space:pre; overflow-x:auto }
    #iv-demo .mv-choice { font-size:.8125rem }
    @media (max-width:56rem) { #iv-demo .iv-grid { grid-template-columns:minmax(0,1fr) } }
  </style>

  <div class="iv-grid">
    <!-- Single-line fields: codes pinned under each field, validity blocks the submit -->
    <form class="iv-card" id="iv-form" aria-labelledby="iv-form-title">
      <div class="iv-head">
        <div>
          <h3 id="iv-form-title">Payout details</h3>
          <p>Pasted from a vendor’s onboarding email</p>
        </div>
        <span class="mv-badge" data-variant="warning" id="iv-count">Checking…</span>
      </div>

      <mv-invisibles profile="iban" validate>
        <div class="mv-field">
          <label class="mv-label" for="iv-iban">IBAN</label>
          <input class="mv-input iv-mono" id="iv-iban" name="iban" value="DE89&#x200B; 3704&#xA0;0O44 0532 0130 00" autocomplete="off" spellcheck="false">
        </div>
      </mv-invisibles>

      <mv-invisibles profile="email" validate>
        <div class="mv-field">
          <label class="mv-label" for="iv-email">Remittance email</label>
          <input class="mv-input" id="iv-email" name="email" type="email" value="sofia.m&#x430;rtinez@&#x435;xample.com" autocomplete="off" spellcheck="false">
        </div>
      </mv-invisibles>

      <mv-invisibles profile="code" validate="warning">
        <div class="mv-field">
          <label class="mv-label" for="iv-coupon">Partner code</label>
          <input class="mv-input iv-mono" id="iv-coupon" name="coupon" value="SPRING2O26&#x20;" autocomplete="off" spellcheck="false">
        </div>
      </mv-invisibles>

      <div class="iv-foot">
        <span class="iv-saved" id="iv-saved" role="status"></span>
        <button class="mv-button" data-variant="outline" type="reset">Restore examples</button>
        <button class="mv-button" type="submit">Save payout details</button>
      </div>
    </form>

    <div class="iv-col">
      <!-- Multi-line field: tokens in place, the code shows on hover or when the caret touches it -->
      <section class="iv-card" aria-labelledby="iv-cmd-title">
        <div class="iv-head">
          <div>
            <h3 id="iv-cmd-title">Deploy command</h3>
            <p>Copied from the team wiki. Hover a marker, or move the caret next to it</p>
          </div>
        </div>
        <mv-invisibles profile="code" id="iv-cmd">
          <label class="mv-sr-only" for="iv-cmd-field">Deploy command</label>
          <textarea class="mv-textarea iv-mono" id="iv-cmd-field" rows="3" spellcheck="false">curl &#x2013;X POST https://api.example.com/v1/deploys \&#x20;
  -H &#x201C;Authorization: Bearer $DEPLOY_TOKEN&#x201D; \
  -d&#xA0;'{"service": "checkout", "region": "us-east-1"}'</textarea>
        </mv-invisibles>
        <label class="mv-choice" data-control="end">
          <input type="checkbox" role="switch" class="mv-switch" id="iv-ws">
          <span class="mv-choice-text"><span class="mv-choice-title">Show all whitespace</span></span>
        </label>
      </section>

      <!-- Read-only target: revealed in place, with the true character order -->
      <section class="iv-card" aria-labelledby="iv-pr-title">
        <div class="iv-head">
          <div>
            <h3 id="iv-pr-title">Code review</h3>
            <p>auth/guard.js · pull request #482</p>
          </div>
        </div>
        <div>
          <span class="iv-k" id="iv-seen-k">What the reviewer saw</span>
          <pre class="iv-seen" aria-labelledby="iv-seen-k">if (role !== "user&#x202E; &#x2066;// Check if admin&#x2069; &#x2066;") {</pre>
        </div>
        <div>
          <span class="iv-k">What is stored</span>
          <mv-invisibles>
            <pre class="iv-code"><code>const role = session.user.role;
if (role !== "user&#x202E; &#x2066;// Check if admin&#x2069; &#x2066;") {
  grantAccess(adminPanel);
}</code></pre>
          </mv-invisibles>
        </div>
      </section>
    </div>
  </div>

  <script type="module">
    const form = document.getElementById("iv-form");
    await customElements.whenDefined("mv-invisibles");
    const badge = document.getElementById("iv-count");
    const saved = document.getElementById("iv-saved");
    const fields = [...form.querySelectorAll("mv-invisibles")];

    const refresh = () => {
      const total = fields.reduce((sum, el) => sum + el.counts.total, 0);
      badge.textContent = total ? `${total} to review` : "Ready to save";
      badge.dataset.variant = total ? "warning" : "success";
    };
    form.addEventListener("mv-invisibles", () => { saved.textContent = ""; refresh(); });
    form.addEventListener("reset", () => setTimeout(refresh));
    form.addEventListener("submit", (e) => {
      e.preventDefault();
      saved.textContent = "Payout details saved";
    });
    refresh();

    document.getElementById("iv-ws").addEventListener("change", (e) => {
      document.getElementById("iv-cmd").showWhitespace = e.target.checked;
    });
  </script>
</div>

API

Attributes

Name	类型	Default	Description
`profile`	iban \| email \| code \| username \| text \| prose	`email for type=email, prose for textarea, code for pre/code, text otherwise`	Rule set for the kind of value. iban, email, code and username are strict: every non-ASCII look-alike letter, bidi mark and odd space is flagged; code also flags smart quotes, typographic dashes and look-alike punctuation; iban and code flag an O/I/l among digits (or a 0/1 among letters) on single-line fields. text flags hidden characters, odd spaces, edges and mixed-script words only. prose is lenient: no-break spaces, soft hyphens and bidi marks are fine, joiners inside emoji and joining scripts are ignored, only words mixing Latin with Cyrillic, Greek or Armenian look-alikes are flagged.
`rules`	list of rule ids		Replaces the profile's rules. Ids: zero-width, joiner, soft-hyphen, bidi, bidi-mark, control, tags, nbsp, spaces, tab, edge, line-separator, homoglyph, fullwidth, ambiguous, punctuation.
`allow`	list		Exceptions, comma or space separated: rule ids ("nbsp, edge"), short codes ("ZWJ"), code points ("U+00A0") or single characters.
`validate`	"" \| "warning"		Present: the field gets a custom validity message (setCustomValidity) while danger or error findings remain, so native form validation blocks the submit. "warning" also blocks warnings (look-alike punctuation, ambiguous O/0, spaces in multi-line fields). The message is removed as soon as the field is clean, and never touches a validity message the app set itself.
`validity-message`	string		Custom validity message used instead of the default (“This field contains 2 hidden characters. Fix them before continuing.”).
`show-whitespace`	boolean	`false`	Also draws regular spaces (·) and line ends (¶) faintly in the mirror, like an editor's render-whitespace mode. They are never counted.
`show-clean`	boolean	`false`	Keeps the summary line visible when nothing is found (“No hidden characters”), for fields where the check itself should be visible.
`data-invisibles-target`	attribute on a descendant		Marks the element to watch when the wrapper contains several candidates. Otherwise the first input or textarea is used, then the first pre, then the first code.
`data-invisibles-report`	attribute on a descendant		Container that receives the report (summary, fixes, details). By default the report is inserted right after the wrapper's child that contains the field.

Properties

Name	类型	Description
`found`	Finding[]	Current findings (read-only copies), sorted by position; identical adjacent characters are merged. Finding: { index, end, length, count, text, codePoint, hex, code, name, hint, rule, category: "invisible" \| "space" \| "lookalike", severity: "danger" \| "error" \| "warning", replacement, fix, hidden? } (hidden = decoded tag text).
`counts`	{ hidden, invisible, space, lookalike, danger, total }	Totals in characters (hidden = invisible + space).
`clean`	string	The current text with every fix applied, without touching the field.
`field`	HTMLElement \| null	The watched element.
`profile / rules / allow / validate / validityMessage / showWhitespace / showClean`	reflected	Mirror the attributes; changing one rescans immediately.

Methods

Name	Description
`scan()`	Rescans now and returns the findings. Call it after setting the field's value from script (programmatic value changes fire no event); input, change, focus and form reset rescan automatically.
`fix(kind = "all")`	kind: "invisible" \| "spaces" \| "lookalikes" \| "all". Replaces only the changed span with document.execCommand("insertText"), so native undo, input events and framework bindings all see a normal edit (falls back to setting the value and dispatching input). The caret is mapped through the edit. Returns the number of characters fixed (0 if nothing to fix, read-only field or vetoed).
`copyClean()`	Copies the text with every fix applied to the clipboard (the action offered for pre/code targets). Resolves to the number of characters fixed.
`findInvisibles(text, { profile, rules, allow, multiline }) (module export)`	The detector alone, DOM-free: returns the same findings, for server-side or Node validation.
`cleanInvisibles(text, options, kind) (module export)`	Returns { text, count, ops } with the chosen fixes applied.

Events

Name	Description
`mv-invisibles`	Findings changed (and once on start if any). detail: { found, counts, value, source: "initial" \| "input" \| "paste" \| "drop" \| "change" \| "fix" \| "reset" \| "api" \| "config" \| "mutation" }.
`mv-fix`	Before a fix or a clean copy. detail: { kind, count, before, after, found, mode: "edit" \| "copy" }. Cancelable: preventDefault() leaves the value untouched (e.g. log it, or apply your own normalization).

Content structure

Name	Description
`(content)`	Your label and one input (text, search, email, url, tel), textarea, pre or code, in any markup (a field wrapper, an input group…). The component adds a mirror and a tooltip (both aria-hidden) plus a report after the field; the field itself is only given aria-describedby and, with validate, a custom validity message.

CSS classes

Name	Description
`mv-invisibles-mirror`	The transparent copy of the text laid over the field (aria-hidden, pointer-events: none).
`mv-invisibles-token`	A wrapped character. data-shape: zero \| space \| edge \| break \| glyph, data-rule, data-category, data-severity, data-code.
`mv-invisibles-rail / -chip`	Codes pinned under single-line fields, with a tick pointing at the exact position (‹ › when scrolled out of view, +N when they do not fit).
`mv-invisibles-tip`	Tooltip naming the hovered or caret-adjacent character.
`mv-invisibles-report / -summary / -fixes / -result / -list / -item`	The report: data-state (found \| fixed \| clean) and data-severity on the report.

CSS variables

Name	Default	Description
`--mv-invisibles-color`	`var(--mv-warning)`	Tone of hidden characters and odd spaces.
`--mv-invisibles-danger`	`var(--mv-danger)`	Tone of bidi controls and hidden tag text.
`--mv-invisibles-lookalike`	`var(--mv-accent)`	Tone of look-alike characters.

Accessibility

The mirror, rail and tooltip are purely visual (aria-hidden, pointer-events: none): the field keeps its native role, label, caret, selection, spellcheck and IME behavior, and nothing is inserted into its value. Findings are described in text: the summary element is linked to the field with aria-describedby while there is something to report (removed when the field is clean), and includes a screen-reader sentence naming the first four findings and where they are (“zero width space after DE89”). New findings are announced politely, once the input settles (“Pasted text contains 2 hidden characters: zero width space, no-break space.”). Fixes are real buttons; a fix moves focus into the field (where typing continues), announces its result (“Removed 1 invisible character. Press Ctrl+Z or use Undo to restore.”) and stays undoable natively. The Details toggle uses aria-expanded / aria-controls, and each finding in the list is a button that selects that character in the field, so keyboard and screen-reader users can reach every finding without hovering; moving the caret next to a marker shows the same tooltip as hovering. Meaning never relies on color: every marker has a distinct shape (capsule, bracket, hatching, dotted underline, solid capsule with a notch for dangerous controls) and a text code, and the summary icon changes shape with severity. With validate, the native validity message explains the problem in plain words. The overlay follows the field's own font metrics, so it stays aligned at any zoom level and text size. Reduced motion removes the tooltip fade, the rail slide and the locate flash; forced colors switch markers and chips to system colors while keeping their shapes.