@docs.plus/extension-hyperlink 2.0.0 → 2.1.0

package/dist/index.d.cts

@@ -6,7 +6,7 @@ export { registerCustomProtocol } from 'linkifyjs';
 /**
  * Canonicalize a user-supplied href so stored marks point somewhere
  * absolute (bare `google.com` would otherwise resolve against
- * `document.baseURI` at render time). See README → Normalization for
+ * `document.baseURI` at render time). See docs/url-handling.md for
  * the full pipeline order.
  */
 declare const normalizeHref: (raw: string, defaultProtocol?: string) => string;
@@ -22,18 +22,14 @@ type LinkifyMatchLike = {
 };
 
 /**
- * Schemes blocked at every write boundary: `javascript:` / `vbscript:`
- * (script execution), `data:` (arbitrary HTML), `file:` (local FS),
- * `blob:` (in-page memory; never legitimate in stored content).
- *
- * Twin of `extension-hypermultimedia`'s copy. Adding a scheme to one and not
- * the other opens a hole in the twin, so preflight diffs them byte-for-byte.
+ * Blocked schemes: `javascript:`/`vbscript:` (script), `data:`, `file:`, `blob:`.
+ * Twin of hypermultimedia's copy — preflight diffs them byte-for-byte.
  */
 declare const DANGEROUS_SCHEME_RE: RegExp;
 /**
  * Single XSS gate used at every read/write boundary. Returns `false`
  * for nullish/empty hrefs and any scheme matched by
- * {@link DANGEROUS_SCHEME_RE}. See README → Security.
+ * {@link DANGEROUS_SCHEME_RE}. See docs/security.md.
  */
 declare const isSafeHref: (href: string | null | undefined) => href is string;
 type ValidateURLOptions = {
@@ -42,7 +38,7 @@ type ValidateURLOptions = {
 /**
  * Shape-validate a URL: web schemes with a plausible host, app schemes from
  * the `getSpecialUrlInfo` catalog, and bare E.164 phones. Rejects schemes
- * matched by {@link DANGEROUS_SCHEME_RE}. See README → Validation.
+ * matched by {@link DANGEROUS_SCHEME_RE}. See docs/url-handling.md.
  */
 declare const validateURL: (url: string, options?: ValidateURLOptions) => boolean;
 
@@ -85,14 +81,12 @@ interface URLDecisions {
     detect(text: string): boolean;
 }
 
-/** Deps every interaction (input rule, paste rule, autolink, paste handler, click handler) reads. */
 interface LinkContext {
     type: MarkType;
     editor: Editor;
-    /** URL Decisions pipeline; one per `createLinkContext` call (the extension allocates one per editor, cached on `storage.context`). */
+    /** One URL Decisions pipeline per editor (cached on `storage.context`). */
     urls: URLDecisions;
     options: HyperlinkOptions;
-    /** Convenience accessor for `options.validate`. */
     validate?: (url: string) => boolean;
     /** Preview popover factory, or `null` when the host opted out. */
     previewPopover: ((options: PreviewHyperlinkOptions) => HTMLElement | null) | null;
@@ -111,13 +105,12 @@ type EditHyperlinkAttributes = {
     image?: string;
 };
 interface HyperlinkPublicCommands<ReturnType> {
-    /** Write the hyperlink mark; returns `false` when `href` is missing or fails the gate. See README → Commands. */
+    /** Write the hyperlink mark; returns `false` when `href` is missing or fails the gate. See docs/api.md → Commands. */
     setHyperlink: (attributes: SetHyperlinkAttributes) => ReturnType;
-    /** Remove the hyperlink mark from the current selection. */
     unsetHyperlink: () => ReturnType;
-    /** Toggle the hyperlink mark; same gates as `setHyperlink`. */
+    /** Toggle; same gates as `setHyperlink`. */
     toggleHyperlink: (attributes: SetHyperlinkAttributes) => ReturnType;
-    /** Open the create popover (configured `popovers.createHyperlink` or the prebuilt fallback); no-op only when the factory returns `null`. See README → Commands. */
+    /** Open the create popover (configured `popovers.createHyperlink` or the prebuilt fallback); no-op only when the factory returns `null`. See docs/api.md → Commands. */
     openCreateHyperlinkPopover: (attributes?: Partial<HyperlinkAttributes>) => ReturnType;
     editHyperlinkText: (text: string) => ReturnType;
     editHyperlinkHref: (href: string) => ReturnType;
@@ -149,7 +142,7 @@ type IsAllowedUriContext = {
 };
 /**
  * `Extra` extends the built-ins with consumer-typed fields; it defaults to
- * `Record<string, unknown>` to keep the v2 open index signature. Example: README → TypeScript.
+ * `Record<string, unknown>` to keep the v2 open index signature. Example: docs/api.md → TypeScript.
  */
 type HyperlinkAttributes<Extra extends Record<string, unknown> = Record<string, unknown>> = {
     href: string | null;
@@ -199,7 +192,7 @@ interface HyperlinkOptions {
         createHyperlink?: ((options: CreateHyperlinkOptions) => HTMLElement | null) | null;
     };
     validate?: (url: string) => boolean;
-    /** Scheme used by `normalizeHref` to promote bare domains. Default `'https'`. See README → Options. */
+    /** Scheme used by `normalizeHref` to promote bare domains. Default `'https'`. See docs/api.md → Options. */
     defaultProtocol: string;
     /** URI policy hook — runs AFTER `isSafeHref`, BEFORE the mark is written. Mirrors `@tiptap/extension-link`. */
     isAllowedUri?: (uri: string, ctx: IsAllowedUriContext) => boolean;
@@ -207,7 +200,7 @@ interface HyperlinkOptions {
     shouldAutoLink?: (uri: string) => boolean;
     /** Click inside a link selects the whole mark range (editable mode only). Mirrors `@tiptap/extension-link`. */
     enableClickSelection: boolean;
-    /** ArrowRight at the right edge of a link exits the mark. Mirrors `@tiptap/extension-link`. */
+    /** ArrowRight at the right edge of a link drops a stored link mark. Mirrors `@tiptap/extension-link`. */
     exitable: boolean;
 }
 /** Extension storage; one slot per editor instance. */
@@ -220,46 +213,6 @@ interface HyperlinkStorage {
 }
 declare const Hyperlink: Mark<HyperlinkOptions, HyperlinkStorage>;
 
-interface BuildPreviewOptionsFromAnchorArgs {
-    editor: Editor;
-    link: HTMLAnchorElement;
-    /** Prefer this ProseMirror position before falling back to DOM similarity. */
-    nodePos?: number;
-    /** Forwarded onto the returned options; usually the configured `validate` option. */
-    validate?: (url: string) => boolean;
-    /** Preserve the host's composed navigation gate when rebuilding preview from edit/back. */
-    isAllowedUri?: (uri: string) => boolean;
-    /** Mark name to look up; defaults to `'hyperlink'`. Override only if the schema mark was renamed. */
-    markName?: string;
-}
-/**
- * Exists so the edit popover's Back button and BYO `editHyperlink` factories
- * share one `posAtDOM → mark.attrs` lookup. The DOM `link.href` property is
- * never the raw-href fallback — it resolves relative hrefs against
- * `document.baseURI`, leaking the host origin into a stored attribute.
- */
-declare function buildPreviewOptionsFromAnchor({ editor, link, nodePos: preferredNodePos, validate, isAllowedUri, markName }: BuildPreviewOptionsFromAnchorArgs): PreviewHyperlinkOptions;
-
-/**
- * Open the create-hyperlink popover anchored to the current selection.
- * Returns `false` when the host opted out (factory returned `null`).
- */
-declare function openCreateHyperlink(editor: Editor, attributes?: Partial<HyperlinkAttributes>): boolean;
-
-/**
- * Open the edit popover anchored to a hyperlink. The prebuilt popover's
- * Back button closes over `opts`, so no extra wiring is needed to
- * return to the preview.
- */
-declare function openEditHyperlink(opts: EditHyperlinkOptions): void;
-
-/**
- * Returns `false` when the host opted out (factory returned `null`, e.g. a
- * mobile bottom sheet). The click handler gates caret placement on it —
- * `.focus()` on an opting-out host makes iOS Safari scroll the editor.
- */
-declare function openPreviewHyperlink(opts: PreviewHyperlinkOptions): boolean;
-
 type PopoverKind = 'preview' | 'edit' | 'create' | (string & {});
 type VirtualCoordinates = {
     getBoundingClientRect: () => {
@@ -276,9 +229,7 @@ interface ManagedPopover {
     updateReference: (referenceElement?: HTMLElement, coordinates?: VirtualCoordinates) => void;
 }
 type AdoptMetadata = {
-    /** The popover's root element — what subscribers attach focus rings, scroll-freezes, or DOM observers to. */
     element: HTMLElement;
-    /** The anchor the popover is glued to — `null` for virtual-coords popovers (e.g. selection-anchored create). */
     referenceElement: HTMLElement | null;
 };
 type ControllerState = {
@@ -354,10 +305,44 @@ interface Popover {
 declare const DEFAULT_OFFSET = 8;
 declare function createPopover(options: PopoverOptions): Popover;
 
-/** Hide the shared tooltip bubble and cancel any pending show. */
-declare function hideTooltip(): void;
-/** Show `label` above `target` after a short hover/focus delay. Returns a detach function for surfaces that re-render in place. */
-declare function attachTooltip(target: HTMLElement, label: string): () => void;
+interface BuildPreviewOptionsFromAnchorArgs {
+    editor: Editor;
+    link: HTMLAnchorElement;
+    /** Prefer this ProseMirror position before falling back to DOM similarity. */
+    nodePos?: number;
+    validate?: (url: string) => boolean;
+    /** Preserve the host's composed navigation gate when rebuilding preview from edit/back. */
+    isAllowedUri?: (uri: string) => boolean;
+    /** Mark name to look up; defaults to `'hyperlink'`. Override only if the schema mark was renamed. */
+    markName?: string;
+}
+/**
+ * Exists so the edit popover's Back button and BYO `editHyperlink` factories
+ * share one `posAtDOM → mark.attrs` lookup. The DOM `link.href` property is
+ * never the raw-href fallback — it resolves relative hrefs against
+ * `document.baseURI`, leaking the host origin into a stored attribute.
+ */
+declare function buildPreviewOptionsFromAnchor({ editor, link, nodePos: preferredNodePos, validate, isAllowedUri, markName }: BuildPreviewOptionsFromAnchorArgs): PreviewHyperlinkOptions;
+
+/**
+ * Open the create-hyperlink popover anchored to the current selection.
+ * Returns `false` when the host opted out (factory returned `null`).
+ */
+declare function openCreateHyperlink(editor: Editor, attributes?: Partial<HyperlinkAttributes>): boolean;
+
+/**
+ * Open the edit popover anchored to a hyperlink. The prebuilt popover's
+ * Back button closes over `opts`, so no extra wiring is needed to
+ * return to the preview.
+ */
+declare function openEditHyperlink(opts: EditHyperlinkOptions): void;
+
+/**
+ * Returns `false` when the host opted out (factory returned `null`, e.g. a
+ * mobile bottom sheet). The click handler gates caret placement on it —
+ * `.focus()` on an opting-out host makes iOS Safari scroll the editor.
+ */
+declare function openPreviewHyperlink(opts: PreviewHyperlinkOptions): boolean;
 
 declare function createHyperlinkPopover(options: CreateHyperlinkOptions): HTMLElement;
 
@@ -365,11 +350,13 @@ declare function editHyperlinkPopover(options: EditHyperlinkOptions): HTMLElemen
 
 declare function previewHyperlinkPopover(options: PreviewHyperlinkOptions): HTMLElement;
 
+declare function hideTooltip(): void;
+/** Returns a detach function for surfaces that re-render in place. */
+declare function attachTooltip(target: HTMLElement, label: string): () => void;
+
 /**
- * `window.open` features string for safe navigation — every
- * `window.open(href, '_blank', …)` call needs this explicit arg or the
- * opened tab can read `window.opener` and the Referer leaks. Re-exported
- * so downstream popovers pin the same value.
+ * Required `window.open` features. Without this arg the opened tab can
+ * read `window.opener` and the Referer leaks. Re-exported so popovers pin it.
  */
 declare const SAFE_WINDOW_FEATURES: "noopener,noreferrer";
 
@@ -385,17 +372,10 @@ declare const Copy: ({ size, fill }?: IconProps) => string;
 declare const LinkOff: ({ size, fill }?: IconProps) => string;
 declare const Pencil: ({ size, fill }?: IconProps) => string;
 
+/** Catalog of app schemes and well-known domains. Source: https://github.com/bhagyas/app-urls */
 /**
- * Special URL schemes and well-known domains the extension classifies
- * for the preview popover.
- *
- * Catalog source: https://github.com/bhagyas/app-urls
- */
-/**
- * String-literal union so consumers can declare a
- * `Partial<Record<SpecialUrlType, …>>` icon map with exhaustive
- * autocomplete — type-only, zero runtime bytes. Naming convention lives
- * in this package's AGENTS.md.
+ * Type-only union for consumer icon maps (`Partial<Record<SpecialUrlType, …>>`).
+ * Zero runtime bytes. Naming convention is in this package's AGENTS.md.
  */
 type SpecialUrlType = 'email' | 'phone' | 'sms' | 'facetime' | 'facetime-audio' | 'whatsapp' | 'telegram' | 'discord' | 'skype' | 'slack' | 'twitter' | 'facebook' | 'instagram' | 'linkedin' | 'snapchat' | 'reddit' | 'tiktok' | 'zoom' | 'teams' | 'webex' | 'meet' | 'calendar' | 'reminders' | 'contacts' | 'maps' | 'music' | 'apple-tv' | 'notes' | 'photos' | 'shortcuts' | 'app-store' | 'github' | 'gitlab' | 'vscode' | 'notion' | 'obsidian' | 'figma' | 'youtube' | 'spotify' | 'netflix' | 'twitch' | 'amazon' | 'uber' | 'lyft';
 type SpecialUrlInfo = {
@@ -404,10 +384,8 @@ type SpecialUrlInfo = {
     category: 'communication' | 'social' | 'productivity' | 'entertainment' | 'shopping' | 'development' | 'apple' | 'other';
 };
 /**
- * Classify `url` against the catalog (scheme prefix or host suffix).
- * Returns `null` for plain web URLs — the consumer should fall back to
- * a generic favicon. Mapping `type`/`category` to an icon is the
- * consumer's job; the extension stays brand-neutral on purpose.
+ * Classify `url` against the catalog. `null` means a plain web URL (favicon).
+ * Icon mapping is the consumer's job; this package stays brand-neutral.
  */
 declare const getSpecialUrlInfo: (url: string) => SpecialUrlInfo | null;
 

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { registerCustomProtocol } from 'linkifyjs';
 /**
  * Canonicalize a user-supplied href so stored marks point somewhere
  * absolute (bare `google.com` would otherwise resolve against
- * `document.baseURI` at render time). See README → Normalization for
+ * `document.baseURI` at render time). See docs/url-handling.md for
  * the full pipeline order.
  */
 declare const normalizeHref: (raw: string, defaultProtocol?: string) => string;
@@ -22,18 +22,14 @@ type LinkifyMatchLike = {
 };
 
 /**
- * Schemes blocked at every write boundary: `javascript:` / `vbscript:`
- * (script execution), `data:` (arbitrary HTML), `file:` (local FS),
- * `blob:` (in-page memory; never legitimate in stored content).
- *
- * Twin of `extension-hypermultimedia`'s copy. Adding a scheme to one and not
- * the other opens a hole in the twin, so preflight diffs them byte-for-byte.
+ * Blocked schemes: `javascript:`/`vbscript:` (script), `data:`, `file:`, `blob:`.
+ * Twin of hypermultimedia's copy — preflight diffs them byte-for-byte.
  */
 declare const DANGEROUS_SCHEME_RE: RegExp;
 /**
  * Single XSS gate used at every read/write boundary. Returns `false`
  * for nullish/empty hrefs and any scheme matched by
- * {@link DANGEROUS_SCHEME_RE}. See README → Security.
+ * {@link DANGEROUS_SCHEME_RE}. See docs/security.md.
  */
 declare const isSafeHref: (href: string | null | undefined) => href is string;
 type ValidateURLOptions = {
@@ -42,7 +38,7 @@ type ValidateURLOptions = {
 /**
  * Shape-validate a URL: web schemes with a plausible host, app schemes from
  * the `getSpecialUrlInfo` catalog, and bare E.164 phones. Rejects schemes
- * matched by {@link DANGEROUS_SCHEME_RE}. See README → Validation.
+ * matched by {@link DANGEROUS_SCHEME_RE}. See docs/url-handling.md.
  */
 declare const validateURL: (url: string, options?: ValidateURLOptions) => boolean;
 
@@ -85,14 +81,12 @@ interface URLDecisions {
     detect(text: string): boolean;
 }
 
-/** Deps every interaction (input rule, paste rule, autolink, paste handler, click handler) reads. */
 interface LinkContext {
     type: MarkType;
     editor: Editor;
-    /** URL Decisions pipeline; one per `createLinkContext` call (the extension allocates one per editor, cached on `storage.context`). */
+    /** One URL Decisions pipeline per editor (cached on `storage.context`). */
     urls: URLDecisions;
     options: HyperlinkOptions;
-    /** Convenience accessor for `options.validate`. */
     validate?: (url: string) => boolean;
     /** Preview popover factory, or `null` when the host opted out. */
     previewPopover: ((options: PreviewHyperlinkOptions) => HTMLElement | null) | null;
@@ -111,13 +105,12 @@ type EditHyperlinkAttributes = {
     image?: string;
 };
 interface HyperlinkPublicCommands<ReturnType> {
-    /** Write the hyperlink mark; returns `false` when `href` is missing or fails the gate. See README → Commands. */
+    /** Write the hyperlink mark; returns `false` when `href` is missing or fails the gate. See docs/api.md → Commands. */
     setHyperlink: (attributes: SetHyperlinkAttributes) => ReturnType;
-    /** Remove the hyperlink mark from the current selection. */
     unsetHyperlink: () => ReturnType;
-    /** Toggle the hyperlink mark; same gates as `setHyperlink`. */
+    /** Toggle; same gates as `setHyperlink`. */
     toggleHyperlink: (attributes: SetHyperlinkAttributes) => ReturnType;
-    /** Open the create popover (configured `popovers.createHyperlink` or the prebuilt fallback); no-op only when the factory returns `null`. See README → Commands. */
+    /** Open the create popover (configured `popovers.createHyperlink` or the prebuilt fallback); no-op only when the factory returns `null`. See docs/api.md → Commands. */
     openCreateHyperlinkPopover: (attributes?: Partial<HyperlinkAttributes>) => ReturnType;
     editHyperlinkText: (text: string) => ReturnType;
     editHyperlinkHref: (href: string) => ReturnType;
@@ -149,7 +142,7 @@ type IsAllowedUriContext = {
 };
 /**
  * `Extra` extends the built-ins with consumer-typed fields; it defaults to
- * `Record<string, unknown>` to keep the v2 open index signature. Example: README → TypeScript.
+ * `Record<string, unknown>` to keep the v2 open index signature. Example: docs/api.md → TypeScript.
  */
 type HyperlinkAttributes<Extra extends Record<string, unknown> = Record<string, unknown>> = {
     href: string | null;
@@ -199,7 +192,7 @@ interface HyperlinkOptions {
         createHyperlink?: ((options: CreateHyperlinkOptions) => HTMLElement | null) | null;
     };
     validate?: (url: string) => boolean;
-    /** Scheme used by `normalizeHref` to promote bare domains. Default `'https'`. See README → Options. */
+    /** Scheme used by `normalizeHref` to promote bare domains. Default `'https'`. See docs/api.md → Options. */
     defaultProtocol: string;
     /** URI policy hook — runs AFTER `isSafeHref`, BEFORE the mark is written. Mirrors `@tiptap/extension-link`. */
     isAllowedUri?: (uri: string, ctx: IsAllowedUriContext) => boolean;
@@ -207,7 +200,7 @@ interface HyperlinkOptions {
     shouldAutoLink?: (uri: string) => boolean;
     /** Click inside a link selects the whole mark range (editable mode only). Mirrors `@tiptap/extension-link`. */
     enableClickSelection: boolean;
-    /** ArrowRight at the right edge of a link exits the mark. Mirrors `@tiptap/extension-link`. */
+    /** ArrowRight at the right edge of a link drops a stored link mark. Mirrors `@tiptap/extension-link`. */
     exitable: boolean;
 }
 /** Extension storage; one slot per editor instance. */
@@ -220,46 +213,6 @@ interface HyperlinkStorage {
 }
 declare const Hyperlink: Mark<HyperlinkOptions, HyperlinkStorage>;
 
-interface BuildPreviewOptionsFromAnchorArgs {
-    editor: Editor;
-    link: HTMLAnchorElement;
-    /** Prefer this ProseMirror position before falling back to DOM similarity. */
-    nodePos?: number;
-    /** Forwarded onto the returned options; usually the configured `validate` option. */
-    validate?: (url: string) => boolean;
-    /** Preserve the host's composed navigation gate when rebuilding preview from edit/back. */
-    isAllowedUri?: (uri: string) => boolean;
-    /** Mark name to look up; defaults to `'hyperlink'`. Override only if the schema mark was renamed. */
-    markName?: string;
-}
-/**
- * Exists so the edit popover's Back button and BYO `editHyperlink` factories
- * share one `posAtDOM → mark.attrs` lookup. The DOM `link.href` property is
- * never the raw-href fallback — it resolves relative hrefs against
- * `document.baseURI`, leaking the host origin into a stored attribute.
- */
-declare function buildPreviewOptionsFromAnchor({ editor, link, nodePos: preferredNodePos, validate, isAllowedUri, markName }: BuildPreviewOptionsFromAnchorArgs): PreviewHyperlinkOptions;
-
-/**
- * Open the create-hyperlink popover anchored to the current selection.
- * Returns `false` when the host opted out (factory returned `null`).
- */
-declare function openCreateHyperlink(editor: Editor, attributes?: Partial<HyperlinkAttributes>): boolean;
-
-/**
- * Open the edit popover anchored to a hyperlink. The prebuilt popover's
- * Back button closes over `opts`, so no extra wiring is needed to
- * return to the preview.
- */
-declare function openEditHyperlink(opts: EditHyperlinkOptions): void;
-
-/**
- * Returns `false` when the host opted out (factory returned `null`, e.g. a
- * mobile bottom sheet). The click handler gates caret placement on it —
- * `.focus()` on an opting-out host makes iOS Safari scroll the editor.
- */
-declare function openPreviewHyperlink(opts: PreviewHyperlinkOptions): boolean;
-
 type PopoverKind = 'preview' | 'edit' | 'create' | (string & {});
 type VirtualCoordinates = {
     getBoundingClientRect: () => {
@@ -276,9 +229,7 @@ interface ManagedPopover {
     updateReference: (referenceElement?: HTMLElement, coordinates?: VirtualCoordinates) => void;
 }
 type AdoptMetadata = {
-    /** The popover's root element — what subscribers attach focus rings, scroll-freezes, or DOM observers to. */
     element: HTMLElement;
-    /** The anchor the popover is glued to — `null` for virtual-coords popovers (e.g. selection-anchored create). */
     referenceElement: HTMLElement | null;
 };
 type ControllerState = {
@@ -354,10 +305,44 @@ interface Popover {
 declare const DEFAULT_OFFSET = 8;
 declare function createPopover(options: PopoverOptions): Popover;
 
-/** Hide the shared tooltip bubble and cancel any pending show. */
-declare function hideTooltip(): void;
-/** Show `label` above `target` after a short hover/focus delay. Returns a detach function for surfaces that re-render in place. */
-declare function attachTooltip(target: HTMLElement, label: string): () => void;
+interface BuildPreviewOptionsFromAnchorArgs {
+    editor: Editor;
+    link: HTMLAnchorElement;
+    /** Prefer this ProseMirror position before falling back to DOM similarity. */
+    nodePos?: number;
+    validate?: (url: string) => boolean;
+    /** Preserve the host's composed navigation gate when rebuilding preview from edit/back. */
+    isAllowedUri?: (uri: string) => boolean;
+    /** Mark name to look up; defaults to `'hyperlink'`. Override only if the schema mark was renamed. */
+    markName?: string;
+}
+/**
+ * Exists so the edit popover's Back button and BYO `editHyperlink` factories
+ * share one `posAtDOM → mark.attrs` lookup. The DOM `link.href` property is
+ * never the raw-href fallback — it resolves relative hrefs against
+ * `document.baseURI`, leaking the host origin into a stored attribute.
+ */
+declare function buildPreviewOptionsFromAnchor({ editor, link, nodePos: preferredNodePos, validate, isAllowedUri, markName }: BuildPreviewOptionsFromAnchorArgs): PreviewHyperlinkOptions;
+
+/**
+ * Open the create-hyperlink popover anchored to the current selection.
+ * Returns `false` when the host opted out (factory returned `null`).
+ */
+declare function openCreateHyperlink(editor: Editor, attributes?: Partial<HyperlinkAttributes>): boolean;
+
+/**
+ * Open the edit popover anchored to a hyperlink. The prebuilt popover's
+ * Back button closes over `opts`, so no extra wiring is needed to
+ * return to the preview.
+ */
+declare function openEditHyperlink(opts: EditHyperlinkOptions): void;
+
+/**
+ * Returns `false` when the host opted out (factory returned `null`, e.g. a
+ * mobile bottom sheet). The click handler gates caret placement on it —
+ * `.focus()` on an opting-out host makes iOS Safari scroll the editor.
+ */
+declare function openPreviewHyperlink(opts: PreviewHyperlinkOptions): boolean;
 
 declare function createHyperlinkPopover(options: CreateHyperlinkOptions): HTMLElement;
 
@@ -365,11 +350,13 @@ declare function editHyperlinkPopover(options: EditHyperlinkOptions): HTMLElemen
 
 declare function previewHyperlinkPopover(options: PreviewHyperlinkOptions): HTMLElement;
 
+declare function hideTooltip(): void;
+/** Returns a detach function for surfaces that re-render in place. */
+declare function attachTooltip(target: HTMLElement, label: string): () => void;
+
 /**
- * `window.open` features string for safe navigation — every
- * `window.open(href, '_blank', …)` call needs this explicit arg or the
- * opened tab can read `window.opener` and the Referer leaks. Re-exported
- * so downstream popovers pin the same value.
+ * Required `window.open` features. Without this arg the opened tab can
+ * read `window.opener` and the Referer leaks. Re-exported so popovers pin it.
  */
 declare const SAFE_WINDOW_FEATURES: "noopener,noreferrer";
 
@@ -385,17 +372,10 @@ declare const Copy: ({ size, fill }?: IconProps) => string;
 declare const LinkOff: ({ size, fill }?: IconProps) => string;
 declare const Pencil: ({ size, fill }?: IconProps) => string;
 
+/** Catalog of app schemes and well-known domains. Source: https://github.com/bhagyas/app-urls */
 /**
- * Special URL schemes and well-known domains the extension classifies
- * for the preview popover.
- *
- * Catalog source: https://github.com/bhagyas/app-urls
- */
-/**
- * String-literal union so consumers can declare a
- * `Partial<Record<SpecialUrlType, …>>` icon map with exhaustive
- * autocomplete — type-only, zero runtime bytes. Naming convention lives
- * in this package's AGENTS.md.
+ * Type-only union for consumer icon maps (`Partial<Record<SpecialUrlType, …>>`).
+ * Zero runtime bytes. Naming convention is in this package's AGENTS.md.
  */
 type SpecialUrlType = 'email' | 'phone' | 'sms' | 'facetime' | 'facetime-audio' | 'whatsapp' | 'telegram' | 'discord' | 'skype' | 'slack' | 'twitter' | 'facebook' | 'instagram' | 'linkedin' | 'snapchat' | 'reddit' | 'tiktok' | 'zoom' | 'teams' | 'webex' | 'meet' | 'calendar' | 'reminders' | 'contacts' | 'maps' | 'music' | 'apple-tv' | 'notes' | 'photos' | 'shortcuts' | 'app-store' | 'github' | 'gitlab' | 'vscode' | 'notion' | 'obsidian' | 'figma' | 'youtube' | 'spotify' | 'netflix' | 'twitch' | 'amazon' | 'uber' | 'lyft';
 type SpecialUrlInfo = {
@@ -404,10 +384,8 @@ type SpecialUrlInfo = {
     category: 'communication' | 'social' | 'productivity' | 'entertainment' | 'shopping' | 'development' | 'apple' | 'other';
 };
 /**
- * Classify `url` against the catalog (scheme prefix or host suffix).
- * Returns `null` for plain web URLs — the consumer should fall back to
- * a generic favicon. Mapping `type`/`category` to an icon is the
- * consumer's job; the extension stays brand-neutral on purpose.
+ * Classify `url` against the catalog. `null` means a plain web URL (favicon).
+ * Icon mapping is the consumer's job; this package stays brand-neutral.
  */
 declare const getSpecialUrlInfo: (url: string) => SpecialUrlInfo | null;