feat(extension-hyperlink): add publish guards and v4 migration docs

Wire the prepublishOnly + prepack lifecycle hooks for the
@docs.plus/extension-hyperlink@4.3.0 npm publish:

- scripts/preflight.ts (prepublishOnly) asserts the publisher is
  Bun (peerDeps use catalog: which only Bun resolves), all dist
  artifacts are present, and no literal "catalog:" string leaked
  into bundles.
- scripts/prepack.ts (prepack) copies the canonical root LICENSE
  into the package directory before pack. Symlinks fail (bun pack
  drops them) and hard links fail (git stores as drifting copies);
  copy-on-pack is the only reliable option.
- publishConfig.access: "public" so scoped publishes don't 402.
- files array picks up CHANGELOG.md and LICENSE for the tarball.

README.md gains a v4 migration banner; CHANGELOG.md gains a
"Migrating from v1.x to v4.x" section so consumers landing on
the npm page understand the breaking surface.

Made-with: Cursor

Author: HMarzban

packages/extension-hyperlink/.gitignore

@@ -7,3 +7,8 @@ dist
 cypress/screenshots
 cypress/videos
 cypress/downloads
+
+# Generated by scripts/prepack.ts before each `bun publish` / `bun pm pack`.
+# Single source of truth lives at the monorepo root.
+# Anchored to package root so a vendored dep's nested LICENSE isn't silently ignored.
+/LICENSE

packages/extension-hyperlink/CHANGELOG.md

@@ -5,6 +5,125 @@
 All notable changes to `@docs.plus/extension-hyperlink` are documented here.
 This project follows [Semantic Versioning](https://semver.org/) and [Conventional Commits](https://conventionalcommits.org). Section headings (`Added` / `Changed` / `Fixed` / `Security`) intentionally repeat per version, per the [Keep a Changelog](https://keepachangelog.com/) convention.
 
+---
+
+## Migrating from v1.x to v4.x
+
+The last npm-published v1 release was `1.5.2`. Versions `2.x` and `3.x` were internal monorepo refactors and were never published. If you are upgrading from `^1.5.2` directly to `4.x`, the API has been substantially redesigned. This section is the short, actionable diff; the full per-version detail lives under [4.0.0](#400--2026-04-15) (renames + popover contract), [4.1.0](#410--2026-04-15) (XSS hardening + bug fixes), [4.2.0](#420--2026-04-15) (stylesheet + clean-room test harness), and [4.3.0](#430--2026-04-16) (unified href canonicalization).
+
+### What changed at a glance
+
+- **Options renamed** to align with Tiptap conventions
+  (`autoHyperlink` → `autolink`, `hyperlinkOnPaste` → `linkOnPaste`).
+- **Commands renamed** with consistent casing
+  (`editHyperLinkText` → `editHyperlinkText`, `editHyperLinkHref` → `editHyperlinkHref`).
+- **CSS classes renamed** from camelCase to kebab-case
+  (`.hyperlinkCreatePopover` → `.hyperlink-create-popover`, …).
+- **Default stylesheet ships separately** — `import '@docs.plus/extension-hyperlink/styles.css'`.
+  v1 inlined CSS via JS; v4 ships a small opt-in CSS file so fully-custom UIs pay zero cost.
+- **Popover contract changed** — `createHyperlink` callback now returns
+  `HTMLElement | null` (was `void`); the extension owns positioning, you own content.
+- **Meta key renamed** — `tr.setMeta('preventAutoHyperlink', …)` → `tr.setMeta('preventAutolink', …)`.
+- **Type augmentation fixed** — commands are augmented under `hyperlink:` (was `link:`).
+- **Hardened XSS guards** — `javascript:`, `data:`, and `vbscript:` are now blocked
+  at every entry point (parse, paste, input rule, click, popover open). If you
+  intentionally stored such URLs, they will now be rejected.
+- **Plausible-host validation** — `validateURL` now rejects typo URLs like
+  `https://googlecom` (no TLD dot, not localhost, not an IP literal).
+
+### Code diff
+
+```diff
+ Hyperlink.configure({
+-  autoHyperlink: true,
+-  hyperlinkOnPaste: true,
++  autolink: true,
++  linkOnPaste: true,
+   popovers: {
+     previewHyperlink: myPreviewFn,
+-    createHyperlink: myCreateFn,   // was (options) => void
++    createHyperlink: myCreateFn,   // now (options) => HTMLElement | null
+   }
+ })
+
+ // Commands
+-editor.commands.editHyperLinkText('New Text')
+-editor.commands.editHyperLinkHref('https://example.com')
++editor.commands.editHyperlinkText('New Text')
++editor.commands.editHyperlinkHref('https://example.com')
+
+ // Meta key in transactions
+-tr.setMeta('preventAutoHyperlink', true)
++tr.setMeta('preventAutolink', true)
+```
+
+```css
+/* CSS selectors */
+- .hyperlinkCreatePopover  { … }
+- .hyperlinkPreviewPopover { … }
+- .hyperlinkEditPopover    { … }
+- .buttonsWrapper { … }
+- .inputsWrapper  { … }
+- .textWrapper    { … }
+- .hrefWrapper    { … }
+- .backButton     { … }
+- .btn_applyModal { … }
++ .hyperlink-create-popover  { … }
++ .hyperlink-preview-popover { … }
++ .hyperlink-edit-popover    { … }
++ .buttons-wrapper { … }
++ .inputs-wrapper  { … }
++ .text-wrapper    { … }
++ .href-wrapper    { … }
++ .back-button     { … }
++ .apply-button    { … }
+```
+
+```ts
+// Popover types — no more hand-rolled types
+import type {
+  PreviewHyperlinkOptions,
+  CreateHyperlinkOptions
+} from '@docs.plus/extension-hyperlink'
+```
+
+### One-shot rename script
+
+For the rename-only changes, run this in your project root and commit the diff:
+
+```bash
+rg -l "autoHyperlink|hyperlinkOnPaste|editHyperLinkText|editHyperLinkHref|preventAutoHyperlink|hyperlinkCreatePopover|hyperlinkPreviewPopover|hyperlinkEditPopover|buttonsWrapper|inputsWrapper|textWrapper|hrefWrapper|backButton|btn_applyModal" \
+  | xargs sed -i.bak \
+    -e 's/autoHyperlink/autolink/g' \
+    -e 's/hyperlinkOnPaste/linkOnPaste/g' \
+    -e 's/editHyperLinkText/editHyperlinkText/g' \
+    -e 's/editHyperLinkHref/editHyperlinkHref/g' \
+    -e 's/preventAutoHyperlink/preventAutolink/g' \
+    -e 's/hyperlinkCreatePopover/hyperlink-create-popover/g' \
+    -e 's/hyperlinkPreviewPopover/hyperlink-preview-popover/g' \
+    -e 's/hyperlinkEditPopover/hyperlink-edit-popover/g' \
+    -e 's/buttonsWrapper/buttons-wrapper/g' \
+    -e 's/inputsWrapper/inputs-wrapper/g' \
+    -e 's/textWrapper/text-wrapper/g' \
+    -e 's/hrefWrapper/href-wrapper/g' \
+    -e 's/backButton/back-button/g' \
+    -e 's/btn_applyModal/apply-button/g'
+```
+
+The rename script handles the mechanical changes. The semantic changes that
+require code review — popover contract returning `HTMLElement | null`, the
+new `styles.css` import, and the stricter URL validation — are not safely
+automatable. Read the [4.0.0](#400--2026-04-15) and [4.1.0](#410--2026-04-15)
+sections to confirm those before shipping the upgrade.
+
+### Need help?
+
+Open an issue at <https://github.com/docs-plus/docs.plus/issues> with the
+label `extension-hyperlink` + `migration` and a snippet of the v1 config
+you're upgrading from.
+
+---
+
 ## [4.3.0] — 2026-04-16
 
 ### Added

packages/extension-hyperlink/README.md

@@ -4,6 +4,13 @@
 [![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)
 
+> [!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.
+
 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:`, …).
 
 <p align="center">

packages/extension-hyperlink/package.json

@@ -46,11 +46,18 @@
     "test:open": "bunx start-server-and-test playground http://127.0.0.1:5173 cy:open",
     "cy:run": "bunx cypress run",
     "cy:open": "bunx cypress open",
-    "docs:screenshots": "bun run build && bunx start-server-and-test playground http://127.0.0.1:5173 'bunx cypress run --config specPattern=cypress/docs/**/*.cy.ts'"
+    "docs:screenshots": "bun run build && bunx start-server-and-test playground http://127.0.0.1:5173 'bunx cypress run --config specPattern=cypress/docs/**/*.cy.ts'",
+    "prepack": "bun run scripts/prepack.ts",
+    "prepublishOnly": "bun run scripts/preflight.ts"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "tiptap",
     "tiptap extension",

packages/extension-hyperlink/scripts/preflight.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env bun
+/**
+ * Pre-publish guard for @docs.plus/extension-hyperlink.
+ *
+ * peerDependencies in package.json use the `catalog:` protocol, which is a
+ * Bun / pnpm workspace feature. Only `bun publish` (and `pnpm publish`) resolve
+ * `catalog:` to a concrete semver range at pack time. `npm publish` would
+ * ship a literal "catalog:" string in the published package.json, breaking
+ * every consumer install with `Invalid Version: catalog:`.
+ *
+ * This script runs from the `prepublishOnly` lifecycle hook (which Bun, npm,
+ * yarn, and pnpm all honor) and fails fast if anything other than Bun is
+ * driving the publish. It also asserts that the freshly built artifacts the
+ * publish will ship actually exist.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const RED = '\x1b[31m'
+const GREEN = '\x1b[32m'
+const YELLOW = '\x1b[33m'
+const RESET = '\x1b[0m'
+
+const fail = (msg: string): never => {
+  console.error(`\n${RED}✗ preflight failed${RESET} — ${msg}\n`)
+  process.exit(1)
+}
+
+const ok = (msg: string) => {
+  console.error(`${GREEN}✓${RESET} ${msg}`)
+}
+
+// ---------------------------------------------------------------------------
+// 1. Publisher check — must be Bun
+// ---------------------------------------------------------------------------
+const userAgent = process.env.npm_config_user_agent ?? ''
+if (!userAgent.startsWith('bun/')) {
+  fail(
+    [
+      `peerDependencies use the \`catalog:\` protocol, which only Bun resolves`,
+      `at pack time. Detected publisher: ${YELLOW}${userAgent || '(unknown)'}${RESET}`,
+      ``,
+      `  Run:  ${GREEN}bun publish${RESET}`,
+      `  Not:  ${RED}npm publish / yarn publish / pnpm publish${RESET}`,
+      ``,
+      `If you really need to publish from npm, substitute \`catalog:\` with the`,
+      `concrete semver range from the root package.json's \`catalog\` field first.`
+    ].join('\n  ')
+  )
+}
+ok(`publisher is Bun (${userAgent.split(' ')[0]})`)
+
+// ---------------------------------------------------------------------------
+// 2. Build artifact check — files the `exports` map points at must exist
+// ---------------------------------------------------------------------------
+const distFiles = [
+  'dist/index.js',
+  'dist/index.cjs',
+  'dist/index.d.ts',
+  'dist/index.d.cts',
+  'dist/styles.css'
+]
+
+for (const f of distFiles) {
+  if (!existsSync(join(process.cwd(), f))) {
+    fail(`missing build artifact: ${f}\n\n  Run \`bun run build\` first.`)
+  }
+}
+ok(`all ${distFiles.length} dist artifacts present`)
+
+// ---------------------------------------------------------------------------
+// 3. Defense in depth — no literal `catalog:` survived into dist
+// ---------------------------------------------------------------------------
+// tsup bundles dependencies' versions into the dist; a `catalog:` leak here
+// would mean a peerDep slipped past Bun's resolver. Cheap belt-and-suspenders.
+for (const f of ['dist/index.js', 'dist/index.cjs']) {
+  const content = readFileSync(join(process.cwd(), f), 'utf8')
+  if (content.includes('"catalog:"') || content.includes("'catalog:'")) {
+    fail(`literal "catalog:" string found in ${f} — bundle resolution failed`)
+  }
+}
+ok('no `catalog:` leakage in built bundles')
+
+console.error(`\n${GREEN}preflight passed${RESET} — safe to publish\n`)

packages/extension-hyperlink/scripts/prepack.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+/**
+ * `prepack` lifecycle hook — runs before `bun publish` AND `bun pm pack`.
+ *
+ * Syncs the canonical root `LICENSE` into the package directory so it is
+ * included in the published tarball. The per-package `LICENSE` is
+ * `.gitignore`d so the source tree has a single committed copy at the
+ * monorepo root, while every published npm tarball still ships its own
+ * `LICENSE` (npm convention; consumed by SPDX scanners and license audit
+ * tools at e.g. `node_modules/<pkg>/LICENSE`).
+ *
+ * Symlinks and hard links don't work for this:
+ *   - Symlinks: bun pack silently drops them from the tarball.
+ *   - Hard links: work locally for pack, but git stores them as two
+ *     independent files, so contributors who clone the repo would get
+ *     two copies that can drift silently.
+ *
+ * `prepack` runs in both pack flows; `prepublishOnly` runs only on
+ * publish. Keeping the LICENSE sync here (not in preflight) means
+ * `bun pm pack --dry-run` (used for verification) also produces a
+ * realistic tarball with LICENSE included.
+ */
+
+import { copyFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ROOT_LICENSE = join(import.meta.dirname, '..', '..', '..', 'LICENSE')
+const PKG_LICENSE = join(import.meta.dirname, '..', 'LICENSE')
+
+if (!existsSync(ROOT_LICENSE)) {
+  console.error(`\n\x1b[31m✗ prepack failed\x1b[0m — root LICENSE not found at ${ROOT_LICENSE}\n`)
+  process.exit(1)
+}
+
+copyFileSync(ROOT_LICENSE, PKG_LICENSE)
+console.error(`\x1b[32m✓\x1b[0m prepack: synced LICENSE from monorepo root`)