@docs.plus/extension-hyperlink 1.5.1 → 4.3.0

package/README.md

@@ -1,456 +1,354 @@
-# Hyperlink
+# @docs.plus/extension-hyperlink
 
 [![Version](https://img.shields.io/npm/v/@docs.plus/extension-hyperlink.svg?label=version)](https://www.npmjs.com/package/@docs.plus/extension-hyperlink)
 [![Downloads](https://img.shields.io/npm/dm/@docs.plus/extension-hyperlink.svg)](https://npmcharts.com/compare/@docs.plus/extension-hyperlink)
 [![License](https://img.shields.io/npm/l/@docs.plus/extension-hyperlink.svg)](https://www.npmjs.com/package/@docs.plus/extension-hyperlink)
 
-The Link extension adds support for `<a>` tags to the editor. The extension is headless, there is no actual <u>**UI**</u> to add, <u>modify</u> or <u>delete</u> links. The usage example below uses the native JavaScript prompt to show you how that could work.
+> [!IMPORTANT]
+> **v4 is a major rewrite.** Coming from v1.x? The API has been substantially
+> redesigned (renamed options, renamed commands, kebab-case CSS classes,
+> separate stylesheet, hardened XSS guards). Read the
+> [v1 → v4 migration guide](./CHANGELOG.md#migrating-from-v1x-to-v4x)
+> before upgrading.
 
-In a real world application, you would probably add a more sophisticated user interface.
+A Tiptap extension for hyperlinks. Ships with optional prebuilt popovers for creating, previewing, and editing links, plus auto-linking, markdown input rules, and support for 50+ URL schemes (`mailto:`, `tel:`, `zoommtg:`, `vscode:`, `spotify:`, …).
 
-## Installation
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/docs-plus/docs.plus/main/packages/extension-hyperlink/docs/screenshots/preview-dark.png">
+    <img alt="Hyperlink preview popover anchored to a link, with copy / edit / remove actions" width="640" src="https://raw.githubusercontent.com/docs-plus/docs.plus/main/packages/extension-hyperlink/docs/screenshots/preview-light.png">
+  </picture>
+</p>
 
-````sh
-npm install @docsplus/extension-hyperlink
-````
+## Install
 
-## Settings
-
-### protocols
-
-Additional custom protocols you would like to be recognized as links.
+```sh
+npm install @docs.plus/extension-hyperlink
+```
 
-Default: `[]`
+Peer dependencies:
 
-````js
-Hyperlink.configure({
-  protocols: ['ftp', 'mailto'],
-})
-````
+```sh
+npm install @tiptap/core @tiptap/pm
+```
 
-By default, [linkify](https://linkify.js.org/docs/) adds `//` to the end of a protocol however this behavior can be changed by passing `optionalSlashes` option
+## Usage
 
-````js
-Hyperlink.configure({
-  protocols: [
-    {
-      scheme: 'tel',
-      optionalSlashes: true
-    }
+```ts
+import { useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import {
+  Hyperlink,
+  createHyperlinkPopover,
+  previewHyperlinkPopover
+} from '@docs.plus/extension-hyperlink'
+import '@docs.plus/extension-hyperlink/styles.css'
+
+const editor = useEditor({
+  extensions: [
+    StarterKit.configure({ link: false }),
+    Hyperlink.configure({
+      popovers: {
+        previewHyperlink: previewHyperlinkPopover,
+        createHyperlink: createHyperlinkPopover
+      }
+    })
   ]
 })
-````
-
-### autolink
-
-If enabled, it adds links as you type.
-
-Default: `true`
+```
 
-````js
-Hyperlink.configure({
-  autolink: false,
-})
-````
+The `styles.css` import and `popovers` options are optional — see [Popovers](#popovers) and [Styling](#styling) to bring your own UI.
 
-### openOnClick
+## Options
 
-If enabled, links will be opened on click.
+| Option           | Type                                      | Default   | Description                                                                                     |
+| ---------------- | ----------------------------------------- | --------- | ----------------------------------------------------------------------------------------------- |
+| `autolink`       | `boolean`                                 | `true`    | Convert URLs to links as you type.                                                              |
+| `openOnClick`    | `boolean`                                 | `true`    | Open links on click. Overridden by `popovers.previewHyperlink` when set.                        |
+| `linkOnPaste`    | `boolean`                                 | `true`    | Wrap the current selection in a link when a URL is pasted.                                      |
+| `protocols`      | `Array<string \| LinkProtocolOptions>`    | `[]`      | Extra protocols to register with [linkifyjs](https://linkify.js.org). 50+ are already built in. |
+| `HTMLAttributes` | `Record<string, any>`                     | `{ ... }` | Attributes applied to rendered `<a>` tags. Set a key to `null` to remove it.                    |
+| `validate`       | `(url: string) => boolean`                | —         | Reject auto-linked URLs when this returns `false`.                                              |
+| `popovers`       | `{ previewHyperlink?, createHyperlink? }` | —         | Factory functions that return `HTMLElement`. See [Popovers](#popovers).                         |
 
-Default: `true`
+Example with options:
 
-````js
+```ts
 Hyperlink.configure({
-  openOnClick: false,
+  autolink: true,
+  openOnClick: true,
+  linkOnPaste: true,
+  protocols: ['ftp', { scheme: 'tel', optionalSlashes: true }],
+  HTMLAttributes: { rel: 'noopener noreferrer nofollow', target: '_blank' },
+  validate: (href) => /^https?:\/\//.test(href)
 })
-````
-
-### linkOnPaste
+```
 
-Adds a link to the current selection if the pasted content only contains an url.
+## Commands
 
-Default: `true`
+| Command                                | Description                                                                                     |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `setHyperlink({ href, target? })`      | Create a link on the current selection (or open the `createHyperlink` popover when configured). |
+| `unsetHyperlink()`                     | Remove the link mark from the current selection.                                                |
+| `editHyperlink({ newURL?, newText? })` | Update the href and/or inner text of the link at the current selection.                         |
+| `editHyperlinkHref(url)`               | Shorthand for href-only edits.                                                                  |
+| `editHyperlinkText(text)`              | Shorthand for text-only edits.                                                                  |
 
-````js
-Hyperlink.configure({
-  linkOnPaste: false,
-})
-````
+```ts
+editor.commands.setHyperlink({ href: 'https://example.com' })
+editor.commands.editHyperlink({ newURL: 'https://new.example.com', newText: 'New label' })
+editor.commands.unsetHyperlink()
 
-### HTMLAttributes
+editor.getAttributes('hyperlink').href // read current href
+```
 
-Custom HTML attributes that should be added to the rendered HTML tag.
+## Keyboard shortcuts
 
-````js
-Hyperlink.configure({
-  HTMLAttributes: {
-    class: 'my-custom-class',
-  },
-})
-````
+| Shortcut | Action                                               |
+| -------- | ---------------------------------------------------- |
+| `Mod-k`  | Create or edit a hyperlink on the current selection. |
 
-### Modals
+## Popovers
 
-The Modals configuration option lets you incorporate an interactive user interface similar to Google Docs for **setting** and **previewing** hyperlinks. This provides users with a more intuitive and interactive experience;
+The extension is headless — you decide what the UI looks like. Three paths, from easiest to most flexible:
 
-- [Dive into the code](https://github.com/HMarzban/extension-hyperlink/blob/4f37ffa18237f10d76c316844b1c2ab20b751fe9/packages/nextjs/src/components/Tiptap.tsx#L21-L28)
-- [Demo](https://github.com/HMarzban/extension-hyperlink#test-drive-with-our-demo-)
+1. **Use the prebuilt popovers** (shown in [Usage](#usage)) and import `styles.css`.
+2. **Restyle the prebuilt popovers** by overriding `--hl-*` custom properties (see [Styling](#styling)).
+3. **Bring your own popover** — each popover is a factory that returns an `HTMLElement`. The extension handles positioning, outside-click dismissal, keyboard navigation, and cleanup.
 
 <details>
-<summary>The `previewHyperlinkModal` function</summary>
+<summary><b>Custom <code>previewHyperlink</code></b></summary>
 
 ```ts
-function previewHyperlinkModal(options) {
-  const href = options.link.href;
-
-  const hyperlinkModal = document.createElement("div");
-  const removeButton = document.createElement("button");
-  const copyButton = document.createElement("button");
-
-  const newBubble = document.createElement("div");
-  newBubble.classList.add("hyperlink-preview-modal__metadata");
-
-  const hrefTitle = document.createElement("a");
-  hrefTitle.setAttribute("target", "_blank");
-  hrefTitle.setAttribute("rel", "noreferrer");
-  hrefTitle.setAttribute("href", href);
-  hrefTitle.innerText = href;
-
-  newBubble.append(hrefTitle);
-
-  hyperlinkModal.classList.add("hyperlink-preview-modal");
-
-  removeButton.classList.add("hyperlink-preview-modal__remove-button");
-  removeButton.innerHTML = "remove";
-
-  copyButton.classList.add("hyperlink-preview-modal__copy-button");
-  copyButton.innerHTML = "copy";
-
-  removeButton.addEventListener("click", () => {
-    options.tippy.hide();
-    return options.editor.chain().focus().unsetHyperlink().run();
-  });
-
-  copyButton.addEventListener("click", () => {
-    options.tippy.hide();
-    navigator.clipboard.writeText(href);
-  });
-
-  hyperlinkModal.append(newBubble, copyButton, removeButton);
-
-  return hyperlinkModal;
+import {
+  Hyperlink,
+  hideCurrentToolbar,
+  type PreviewHyperlinkOptions
+} from '@docs.plus/extension-hyperlink'
+
+function previewHyperlink(options: PreviewHyperlinkOptions): HTMLElement {
+  const { editor, attrs } = options
+  const root = document.createElement('div')
+
+  const link = document.createElement('a')
+  link.href = attrs.href
+  link.textContent = attrs.href
+  link.target = '_blank'
+  link.rel = 'noreferrer'
+
+  const remove = document.createElement('button')
+  remove.textContent = 'Remove'
+  remove.addEventListener('click', () => {
+    hideCurrentToolbar()
+    editor.chain().focus().unsetHyperlink().run()
+  })
+
+  root.append(link, remove)
+  return root
 }
 
+Hyperlink.configure({ popovers: { previewHyperlink } })
 ```
 
 </details>
 
 <details>
-<summary>The `setHyperlinkModal` function</summary>
+<summary><b>Custom <code>createHyperlink</code></b></summary>
 
 ```ts
-import { Editor } from "@tiptap/core";
-import { find } from "linkifyjs";
-
-let tooltip = undefined;
-
-function setHyperlinkModal(options) {
-  // Create the tooltip instance
-  if (!tooltip) tooltip = new options.Tooltip(options);
-
-  // Initialize the tooltip
-  let { tippyModal } = tooltip.init();
-
-  const hyperlinkModal = document.createElement("div");
-  const buttonsWrapper = document.createElement("div");
-  const inputsWrapper = document.createElement("div");
-
-  hyperlinkModal.classList.add("hyperlink-set-modal");
-
-  buttonsWrapper.classList.add("hyperlink-set-modal__buttons-wrapper");
-  inputsWrapper.classList.add("hyperlink-set-modal__inputs-wrapper");
-
-  // create a form that contain url input and a button for submit
-  const form = document.createElement("form");
-  const input = document.createElement("input");
-  const button = document.createElement("button");
-
-  input.setAttribute("type", "text");
-  input.setAttribute("placeholder", "https://example.com");
-  button.setAttribute("type", "submit");
-  button.innerText = "Submit";
+import {
+  Hyperlink,
+  hideCurrentToolbar,
+  normalizeHref,
+  validateURL,
+  type CreateHyperlinkOptions
+} from '@docs.plus/extension-hyperlink'
+
+function createHyperlink(options: CreateHyperlinkOptions): HTMLElement {
+  const { editor, extensionName, validate } = options
+  const form = document.createElement('form')
+
+  const input = document.createElement('input')
+  input.type = 'url'
+  input.placeholder = 'https://example.com'
+
+  const submit = document.createElement('button')
+  submit.type = 'submit'
+  submit.textContent = 'Apply'
+
+  form.append(input, submit)
+  form.addEventListener('submit', (event) => {
+    event.preventDefault()
+    const url = input.value.trim()
+    if (!validateURL(url, { customValidator: validate })) return
+
+    // Canonicalize before writing to the mark. `google.com` is a valid
+    // link, but stored verbatim it resolves against the host page's
+    // origin on click — `normalizeHref` prepends `https://` for bare
+    // domains and preserves anything already scheme-prefixed.
+    const href = normalizeHref(url)
+
+    hideCurrentToolbar()
+    editor.chain().setMark(extensionName, { href }).setMeta('preventAutolink', true).run()
+  })
+
+  return form
+}
 
-  inputsWrapper.append(input);
-  buttonsWrapper.append(button);
-  form.append(inputsWrapper, buttonsWrapper);
+Hyperlink.configure({ popovers: { createHyperlink } })
+```
 
-  hyperlinkModal.append(form);
+</details>
 
-  tippyModal.innerHTML = "";
-  tippyModal.append(hyperlinkModal);
-  tooltip.update(options.editor.view, {
-    arrow: options.roundArrow,
-  });
+Popover content can control the floating toolbar via `hideCurrentToolbar()` and `updateCurrentToolbarPosition(ref)`, both exported from the package.
 
-  // make sure
-  setTimeout(() => input.focus();, 100);
+## Styling
 
-  // event listenr for submit button
-  form.addEventListener("submit", (event) => {
-    event.preventDefault();
-    const url = input.value;
+The prebuilt popovers ship with a small, framework-agnostic stylesheet. Import it once:
 
-    if (!url) return;
+```ts
+import '@docs.plus/extension-hyperlink/styles.css'
+```
 
-    const sanitizeURL = find(url)
-      .filter((link) => link.isLink)
-      .filter((link) => {
-        if (options.validate) {
-          return options.validate(link.value);
-        }
-        return true;
-      })
-      .at(0);
+The CSS is opt-in — the extension's JavaScript never imports it, so custom UIs pay zero CSS cost.
 
-    if (!sanitizeURL?.href) return;
+### Theming
 
-    tooltip?.hide();
+Every visual token is a `--hl-*` custom property. Colors use [`light-dark()`](https://developer.mozilla.org/docs/Web/CSS/color_value/light-dark), so the popover follows the nearest ancestor's `color-scheme` — or the OS preference when none is set.
 
-    return options.editor
-      .chain()
-      .setMark(options.extentionName, { href: sanitizeURL.href })
-      .setMeta("preventautohyperlink", true)
-      .run();
-  });
+<details>
+<summary>Default values</summary>
+
+```css
+:root {
+  --hl-bg: light-dark(#ffffff, #1f2937);
+  --hl-fg: light-dark(#111827, #f3f4f6);
+  --hl-muted: light-dark(#6b7280, #9ca3af);
+  --hl-border: light-dark(#e5e7eb, #374151);
+  --hl-hover: light-dark(#f3f4f6, #374151);
+  --hl-accent: light-dark(#2563eb, #60a5fa);
+  --hl-accent-fg: light-dark(#ffffff, #0b1220);
+  --hl-danger: light-dark(#dc2626, #f87171);
+  --hl-shadow:
+    0 1px 2px light-dark(rgba(0, 0, 0, 0.06), rgba(0, 0, 0, 0.4)),
+    0 4px 12px light-dark(rgba(0, 0, 0, 0.08), rgba(0, 0, 0, 0.5));
+  --hl-radius: 6px;
+  --hl-radius-sm: 4px;
+  --hl-font: system-ui, sans-serif;
+  --hl-font-size: 14px;
+  --hl-z-index: 9999;
+  --hl-transition: 120ms ease-in-out;
 }
 ```
 
 </details>
 
+#### Switching themes
 
-<details>
-<summary>The Hyperlink styles.scss</summary>
-
-```scss
-.tippy-box {
-  .hyperlink-preview-modal,
-  .hyperlink-set-modal,
-  .hyperlink-edit-modal {
-    background-color: #fff;
-    border-radius: 10px;
-    border: 1px solid #dadce0;
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    padding: 6px 6px;
-    box-shadow: 0 1px 3px 1px rgba(60, 64, 67, 0.15);
-    margin-top: -6px;
-
-    &__metadata {
-      width: 200px;
-      display: flex;
-      align-items: center;
-      justify-content: flex-end;
-      flex-direction: row-reverse;
-      a {
-        font-size: 0.9rem;
-        margin-right: 6px;
-        white-space: nowrap;
-        overflow: hidden;
-        text-overflow: ellipsis;
-      }
-      img {
-        width: 18px;
-        height: 18px;
-        border-radius: 50%;
-        margin-right: 8px;
-      }
-    }
-
-    &__remove-button,
-    &__edit-button,
-    &__copy-button,
-    &__apply-button {
-      width: 30px;
-      height: 30px;
-      border-radius: 50%;
-      margin: 0 0.25rem;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      transition: background-color 0.1s ease-in-out;
-      &:hover {
-        background-color: #eee;
-      }
-      > svg {
-        width: 16px;
-        height: 16px;
-      }
-    }
-
-    form {
-      display: flex;
-      align-items: flex-end;
-      width: 100%;
-      input {
-        border: 1px solid #dadce0;
-        border-radius: 6px;
-        padding: 0.4rem 0.8rem;
-        margin-bottom: 0.2rem;
-        width: 100%;
-        &:last-of-type {
-          margin-bottom: 0;
-        }
-      }
-      .hyperlink-set-modal__buttons-wrapper,
-      .hyperlink-edit-modal__buttons-wrapper {
-        margin-left: 8px;
-        button {
-          border-radius: 6px;
-          padding: 4px 14px;
-          width: 70px;
-          margin-bottom: 0.2rem;
-          color: #1a73e8;
-          &:hover {
-            background: rgba(26, 115, 232, 0.04);
-            color: #174ea6;
-          }
-        }
-      }
-    }
-  }
+If your app has a light/dark toggle, set `color-scheme` on the theme root — the popover follows along:
 
-  .tippy-svg-arrow {
-    top: -6px !important;
-  }
+```css
+html[data-theme='light'] {
+  color-scheme: light;
+}
+html[data-theme='dark'] {
+  color-scheme: dark;
 }
 ```
 
-</details>
+> **Bundler note.** Some CSS minifiers (lightningcss, for one) down-level `light-dark()` into a `@media (prefers-color-scheme: dark)` block, which pins colors to the OS preference. If that happens, re-declare the tokens on each branch — the attribute selector wins over the media query:
+>
+> ```css
+> html[data-theme='light'] {
+>   --hl-bg: #ffffff;
+>   --hl-fg: #111827; /* … */
+> }
+> html[data-theme='dark'] {
+>   --hl-bg: #1f2937;
+>   --hl-fg: #f3f4f6; /* … */
+> }
+> ```
 
+### Class names
 
-````ts
-import {
-  Hyperlink,
-  previewHyperlinkModal,
-  setHyperlinkModal
-} from "@docs.plus/extension-hyperlink";
+Stable class names for consumers who want to write their own rules:
 
-Hyperlink.configure({
-  modals: {
-    previewHyperlink: (data) => {
-      return previewHyperlinkModal(data);
-    },
-    setHyperlink: (data) => {
-      return setHyperlinkModal(data);
-    },
-  },
-})
-````
-
-> Note: The `previewHyperlinkModal` and `setHyperlinkModal` modals are prebuilt modal boxes. You can use them or create your own modal boxes. To learn how to create your own modal boxes, please check the [source code](https://github.com/HMarzban/extension-hyperlink/tree/main/packages/extension-hyperlink/src/modals)
-
-<Su>
-
-
-
-### Removing and overriding existing html attributes
-
-You can add `rel: null` to HTMLAttributes to remove the default `rel="noopener noreferrer nofollow"`. You can also override the default by using `rel: "your-value"`.
-
-This can also be used to change the `target` from the default value of `_blank`.
-
-````js
-Hyperlink.configure({
-  HTMLAttributes: {
-    // Change rel to different value
-    // Allow search engines to follow links(remove nofollow)
-    rel: 'noopener noreferrer',
-    // Remove target entirely so links open in current tab
-    target: null,
-  },
-})
-````
+| Class                        | Element                                              |
+| ---------------------------- | ---------------------------------------------------- |
+| `.floating-toolbar`          | Toolbar container (adds `.visible` after mount).     |
+| `.floating-toolbar-arrow`    | Arrow pointing at the reference element.             |
+| `.floating-toolbar-content`  | Content wrapper inside the toolbar.                  |
+| `.hyperlink-create-popover`  | Create-link popover root.                            |
+| `.hyperlink-preview-popover` | Preview popover root.                                |
+| `.hyperlink-edit-popover`    | Edit popover root.                                   |
+| `.inputs-wrapper`            | Input group container (adds `.error` on validation). |
+| `.buttons-wrapper`           | Button group container.                              |
+| `.search-icon`               | Leading icon inside an input group.                  |
+| `.error-message`             | Validation error text (shown with `.show`).          |
 
-### validate
+## URL handling
 
-A function that validates every autolinked link. If it exists, it will be called with the link href as argument. If it returns `false`, the link will be removed.
+Every write path canonicalizes hrefs before storing them:
 
-Can be used to set rules for example excluding or including certain domains, tlds, etc.
+- **Bare domains** get `https://` prepended: `google.com` → `https://google.com`.
+- **Explicit schemes** pass through as typed: `http://`, `ftp://`, `whatsapp://`, `mailto:`.
+- **Protocol-relative URLs** stay as-is: `//example.com`.
 
-````js
-// only autolink urls with a protocol
-Hyperlink.configure({
-  validate: href => /^https?:\/\//.test(href),
-})
-````
+The create popover, markdown input rule, autolink, and paste all produce the same `href` for the same input.
 
-## Commands
+Validation also rejects scheme-prefixed typos with no real host. `https://googlecom` fails; `http://localhost`, `https://127.0.0.1`, and any registered custom scheme pass.
 
-### editHyperLinkText(), editHyperLinkHref(), editHyperlink()
+Two helpers are exported for custom popovers:
 
-These commands allow you to edit the text and href value of a hyperlink.
+| Helper                    | Use when                                             |
+| ------------------------- | ---------------------------------------------------- |
+| `normalizeHref(raw)`      | You have a raw URL string.                           |
+| `normalizeLinkifyHref(m)` | You have a linkifyjs match (e.g. from `find(text)`). |
 
-```js
-this.editor.commands.editHyperLinkText('New Text');
-this.editor.commands.editHyperLinkHref('https://new-url.com');
-this.editor.commands.editHyperlink({
-  newText: 'New Text',
-  newURL: 'https://new-url.com'
-});
-```
+## Security
 
-### setHyperlink()
+Dangerous schemes (`javascript:`, `data:`, `vbscript:`) are blocked everywhere a link enters or leaves the editor:
 
-Links the selected text.
+- `parseHTML` strips matching `<a>` tags on document load and paste.
+- The markdown input rule rejects `[text](javascript:…)` at creation.
+- The click handler and preview popover short-circuit `window.open(…)` when the stored href matches.
 
-````js
-this.editor.commands.setHyperlink({
-  href: '<https://example.com>'
-});
+On the read side, both handlers prefer the stored mark attribute over the DOM `link.href` property — so a relative href injected via `setContent` won't resolve against the host page's origin.
 
-this.editor.commands.setHyperlink({
-  href: '<https://example.com>',
-  target: '_blank'
-});
+The shared `DANGEROUS_SCHEME_RE` regex is exported for custom popovers that need the same check.
 
-this.editor.commands.unsetHyperlink();
-````
+## TypeScript
 
-### unsetHyperlink()
+Definitions are bundled. Public types: `HyperlinkOptions`, `HyperlinkAttributes`, `PreviewHyperlinkOptions`, `CreateHyperlinkOptions`, `EditHyperlinkModalOptions`, `LinkProtocolOptions`, `FloatingToolbarOptions`, `FloatingToolbarInstance`, `LinkifyMatchLike`.
 
-Removes a Hyperlink.
+## Testing
 
-````js
-this.editor.commands.unsetHyperlink();
-````
+Cypress runs against the built `dist/` output in a tiny `Bun.serve` playground — the same bytes an npm consumer installs.
 
-## Keyboard shortcuts
-
-Doesn’t have a keyboard shortcut
-This extension doesn’t bind a specific keyboard shortcut. You would probably open your custom UI on `Mod-k` though.
-
-## Get the current value
-
-Did you know that you can use `getAttributes` to find out which attributes, for example which href, is currently set? Don’t confuse it with a <u>command</u> (which changes the state), it’s just a method. Here is how that could look like:
-
-```js
-this.editor.getAttributes('link').href
+```sh
+bun run test             # build + run Cypress headless
+bun run test:open        # build + open the Cypress runner
+bun run playground       # just the playground at http://127.0.0.1:5173
+bun run docs:screenshots # regenerate README hero PNGs in docs/screenshots/
 ```
 
-## Sorce code and Example
+Append `?popover=custom` to the playground URL to swap in minimal BYO factories — that's how `custom-popover.cy.ts` exercises the public contract.
+
+| Spec                   | Covers                                                                 |
+| ---------------------- | ---------------------------------------------------------------------- |
+| `create.cy.ts`         | `Mod+K`, Apply state, href canonicalization, host validation, dismiss. |
+| `preview-edit.cy.ts`   | Click → preview → edit/copy/remove, Back, Escape lifecycle.            |
+| `autolink.cy.ts`       | Autolink, paste, and `mailto:` all produce the same `href`.            |
+| `xss-guards.cy.ts`     | `javascript:` / `data:` / `vbscript:` blocked at every entry point.    |
+| `styling.cy.ts`        | `styles.css` loaded, `--hl-*` tokens resolve, `light-dark()` branch.   |
+| `custom-popover.cy.ts` | BYO factory contract — options, mount lifecycle, exports.              |
 
-- Demo:
-[packages/extension-hyperlink](https://github.com/HMarzban/extension-hyperlink)
-- Extension:
-[packages/extension-hyperlink](https://github.com/HMarzban/extension-hyperlink/tree/main/packages/extension-hyperlink)
-- Usage:  [packages/nextjs/src/components/Tiptap.tsx](https://github.com/HMarzban/extension-hyperlink/blob/59f45eba1886202f4840eb2112c34574c16fe68a/packages/nextjs/src/components/Tiptap.tsx#L19-L29)
+The suite also runs from the repo root via `bun run test:all`, alongside the Jest and webapp Cypress suites.
 
-## Inspiration and Acknowledgment, Let's Connect
+## License
 
-Thank you for exploring our Hyperlink extension from docs.plus! We aim to make collaboration and knowledge sharing not just easy, but also enjoyable.
+MIT
 
-Our extension is inspired by Tiptap's [extension-link](https://github.com/ueberdosis/tiptap/tree/main/packages/extension-link). While we've incorporated our own enhancements, we'd like to tip our hats to Tiptap for pioneering the "headless" approach that we admire greatly.
-> Please note: We're not affiliated with Tiptap, but we believe in recognizing foundational work.
+## Credits
 
-Your feedback and interest in docs.plus are invaluable to us. Share your thoughts, suggestions, or dive deeper into our mission at the [docs.plus](https://github.com/docs-plus/docs.plus) repository. Wish to converse? Connect with us [here](https://github.com/docs-plus/docs.plus#-connect-with-us).
+Inspired by Tiptap's [@tiptap/extension-link](https://github.com/ueberdosis/tiptap/tree/main/packages/extension-link). Part of [docs.plus](https://github.com/docs-plus/docs.plus).