/**
 * cjk-autospace — CJK ↔ Latin 邊界自動間距 shim（Pangu.js v7.2.1 風格）。
 *
 * 用法：
 * ```ts
 * import { createCjkAutospace } from "./cjk-autospace.js";
 *
 * const autospace = createCjkAutospace({
 *     pillSelector: "code, kbd, .cjk-pill",
 * });
 * autospace.apply(document.body);
 * ```
 */

export interface CjkAutospaceOptions {
    /** 行內塊（PILL）選擇器。預設 `"code, kbd"`。 */
    pillSelector?: string;

    /** 樣式標籤集合（shim 透明走過）。tagName 用大寫。 */
    styleInlines?: readonly string[];

    /** 段落級標籤集合（Pass A run 邊界）。tagName 用大寫。 */
    blockTags?: readonly string[];

    /** Skip-ancestor 標籤集合（subtree 整個跳過）。tagName 用大寫。 */
    skipTags?: readonly string[];

    /** Marker span 之 class 名。預設 `"cjk-autospace"`。 */
    autospaceClass?: string;

    /** Skip-ancestor 額外屬性檢查（任一祖先帶此屬性則 skip）。預設 `"data-md-key"`。 */
    skipAttribute?: string;

    /** 自訂 skip 判定（在內建判定前先檢查）。回傳 true 表示應跳過。 */
    isSkipped?: (node: Node) => boolean;

    /**
     * Pass C（**預設啟用**）：把 `[A-Za-z]{minLength,}` 之長英文段包進
     * `<span lang="…">`，讓瀏覽器原生 `hyphens: auto` 可斷詞並渲染連字
     * 符（連字符純由 CSS 渲染，DOM 內不存在 → 複製不污染原文）。需消費
     * 端 CSS 配：
     *
     * ```css
     * [lang|="en"] {
     *     hyphens: auto;
     *     -webkit-hyphens: auto;
     *     hyphenate-limit-chars: 6 3 3;  // 詞長 / 斷點前 / 斷點後最少字符
     * }
     * ```
     *
     * 傳 `false` 顯式關閉；`true` 或省略等同 `{ minLength: 6, lang: "en" }`。
     */
    longWordWrap?: boolean | {
        /** 觸發包裝之最短字母串長度。預設 6。 */
        minLength?: number;
        /** 包裝 span 之 `lang` 屬性值。預設 `"en"`。 */
        lang?: string;
    };
}

export interface CjkAutospaceInstance {
    /**
     * 對指定 root（預設 `document.body`）套用 Pass A + Pass B。
     * 在已注入 marker 之 DOM 上重跑為冪等（會跳過既有 `.cjk-autospace`）。
     */
    apply(root?: ParentNode | Document): void;
}

export function createCjkAutospace(options?: CjkAutospaceOptions): CjkAutospaceInstance;

declare global {
    var createCjkAutospace: typeof createCjkAutospace;
}