Компоненти фронтенду: кнопки «Копіювати» та блоки коду, що не ламаються в продакшені

Що насправді ламається (і чому це завжди в продакшені)

«Кнопка копіювання на блоці коду» звучить як вирішена задача, поки ви не перерахуєте, що означає продакшен:
різні браузери, закриті корпоративні налаштування, непослідовні жести користувача (клавіатура проти миші), iframe з іншого походження,
переклади, які змінюють ширину кнопки, великий трафік, який робить підсвітку синтаксису дорогою, і найгірше з обмежень:
ваша документація тепер — інтерфейс, від якого люди залежать, щоб безпечно виконувати команди.

Шаблони поломок зазвичай групуються в п’ять відер:

1) Проблеми з дозволами буфера обміну та жестом користувача

Сучасний Clipboard API (navigator.clipboard.writeText) чудовий, поки ні. Він може відмовитись, бо:
сторінка не подається через HTTPS, виклик не ініційований «дією користувача», політика браузера блокує його, або сторінка
вбудована й дозволи не передаються так, як ви припускали. Результат — або мовчазний збій, або відхилена проміс, яку ваш код забуває обробити.

2) Копіюється не те

Бібліотеки підсвітки часто переписують DOM. MDX трансформи коду блоки. Деякі реалізації копіюють відрендерений HTML-текст
(з дивними пробілами) замість оригінального джерела. Інші випадково включають номери рядків, промпти або приховані спани.
Люди вставляють це в продакшен-термінали — і звіт про інцидент пишеться сам.

3) Зсув макета та лаги сторінки

Кнопка «Копіювати», що з’являється лише після гідратації, викликає зсув макета. Блок коду, що перелаштовується після підвантаження шрифту, додає ще.
Коли ви множите це по довгій документації, ваші показники Largest Contentful Paint та Cumulative Layout Shift виглядають як монітор серцевого ритму.

4) Невдачі доступності

«Копіювати» має бути доступним з клавіатури, має повідомляти про успіх/провал і не красти фокус так, щоб користувачі застрягали.
Більшість «кнопок копіювання» в інтернеті — це еквівалент доступності «за плечима». У регульованих середовищах це може стати питанням закупівель, а не лише UX.

5) Безпека та обробка даних

Копіювати секрети легко. Логувати, що користувач натиснув «Копіювати», теж легко. Помилково логувати скопійований вміст — також просто.
Якщо ваша документація включає конфігураційні фрагменти, токени або ідентифікатори клієнтів, інструментація копіювання може стати каналом витоку даних.
Ви хочете спостережуваність без стеження.

Перефразована ідея від Werner Vogels: ви побудували це — ви запускаєте це, отже проєктуйте фічі під відмову, бо відмова — це стан за замовчуванням у складних системах.

Жарт №1: Кнопка копіювання, що мовчки відмовляє, фактично — розподілена система: ніхто не знає, що сталося, і всі звинувачують DNS.

Цікаві факти та історичний контекст

• Доступ до буфера обміну колись був Диким Заходом. Ранні веб-хаки клалися на Flash або привілейовані API браузерів; сучасні браузери жорстко посилили це задля приватності.
• Ера execCommand('copy') тривала довше, ніж визнають. Вона стала де-факто обхідним шляхом на роки, і багато корпоративних браузерів досі покладаються на неї як на фолбек.
• «User activation» тепер — першокласна концепція безпеки. Браузери явно моделюють, чи підпадає жест під цю умову, і асинхронні межі можуть випадково її втратити.
• Підсвітка синтаксису починалася як серверне форматування тексту. До сайтів з важким JS багато документацій генерували підсвічений HTML на етапі збірки, щоб уникнути клієнтських витрат.
• Prism популяризував клієнтську підсвітку для документаційних сайтів. Це зробило «просто підключити скрипт» дефолтом, що чудово, поки у вас не 200 блоків на сторінці.
• Моноширинні шрифти на різних платформах не однакові. Переноси рядків і вирівнювання колонок можуть відрізнятися між macOS, Windows і Linux, що впливає на очікування копіювання/вставки.
• Номери рядків виявилися дивно поляризуючою темою. Деякі команди їх люблять для підтримки; інші ненавидять, бо вони забруднюють скопійовані команди, якщо їх не відділити ретельно.
• Content Security Policy стала мейнстрімом через біль. Це один з небагатьох браузерних механізмів безпеки, що зменшує радіус ураження, але ламає інлайн-скрипти та деякі сторонні віджети.
• Гідратаційні невідповідності — сучасний режим відмови. SSR-фреймворки ввели новий клас багів «в локалі працює, у продакшені відмовляє», коли клієнтський вихід відрізняється від серверного.

Спроєктуйте компонент як контракт

Переможна ментальна модель: ваш компонент блоку коду — це контейнер даних із UI-обгорткою. Копіювання — це детерміністичний експорт.
Ваше завдання — зберегти точні байти, які мав на увазі автор (плюс контрольована нормалізація), і робити відмови явними.

Явно визначте payload для копіювання

Не копіюйте з відрендереного DOM, якщо можете цього уникнути. Текст у DOM вже «інтерпретований» браузером: згортування пробілів,
приховані спани, псевдо-елементи та обгортки з номерами рядків можуть заважати.

Натомість зберігайте сирий рядок коду в data-атрибуті або як проп компонента і копіюйте його.
Якщо контент створено в markdown/MDX, у вас вже є сирий рядок перед підсвіткою. Збережіть його.

Нормалізуйте тільки коли це потрібно

Визначте, як ви обробляєте:

• Кінцевий перенос рядка: Деякі CLI очікують його; деякі shell-і його не мають значення; деякі робочі процеси «копіювати → вставити в YAML» його потребують.
• Windows-кінець рядка: Якщо ви генеруєте документи на Windows, переконайтесь, що не впроваджуєте несподівані \r\n у копію.
• Префікси промптів: Якщо ви показуєте $ або #, кнопка копіювання має або їх видаляти, або пропонувати «копіювати без промптів».
• Перенос рядків у візуальному відображенні: Перенесені рядки мають копіюватися як не перенесені. Якщо ви візуально переносите, зберігайте оригінальний рядок.

Зробіть «копіювання» ідемпотентним і спостережуваним

Натискання «Копіювати» двічі не має переводити в дивні стани або ламати виділення. Воно повинно копіювати той самий вміст щоразу
і показувати короткий індикатор успіху. Якщо воно провалюється — покажіть повідомлення про помилку з підказкою (наприклад, вручну виділити текст).

Не дозволяйте DOM-перетворенням підсвітки змінювати експорт

Бібліотеки підсвітки часто обгортають токени в <span> елементи. Це підходить для відображення; це отрута
для експорту, якщо ви копіюєте через DOM. Тримайте одне джерело правди: сирий рядок коду. DOM — це вигляд.

Механіка буферу обміну: неприємна правда

Потрібен багаторівневий підхід, бо поведінка браузерів різниться, і корпоративні блокування — реальність.
Побудуйте pipeline копіювання з:

1. Переважний шлях: navigator.clipboard.writeText(text), коли доступний і дозволений.
2. Фолбек: document.execCommand('copy') з тимчасовим <textarea> і виділенням.
3. Остаточний фолбек: виділіть код і підкажіть «Натисніть Ctrl/Cmd+C.»

Важливо: user activation крихкий

Якщо ви робите щось асинхронне перед викликом writeText (наприклад, очікуєте аналітику або стан),
деякі браузери вважають, що user activation було «витрачено». Тоді виклики до буфера обміну відмовляють. Виправлення нудне:
викликайте копіювання безпосередньо в обробнику кліку, а все інше робіть після.

Обробляйте відмови свідомо

Ставтеся до невдач буфера обміну як до нормального стану виконання, а не до виключення. UI має показувати «Не вдалося скопіювати»,
а не ламати дерево компонентів. Також: не робіть нескінченних повторів; ви тільки спамитимете користувача і, можливо, викликатимете підказки дозволів браузера.

CSP і сторонні скрипти

Якщо кнопка копіювання залежить від інлайн-скриптів або інжектованих обробників подій, CSP закриє її в добре налаштованому продакшені.
Прикріпляйте обробники в коді застосунку, уникайте onclick="..." і перевіряйте сторонні markdown-рендерери, що вбудовують скрипти.

Два режими «копіювання» варті уваги

У продакшен-доках розгляньте:

• Копіювати фрагмент: точний код, без промптів, без номерів рядків.
• Копіювати для терміналу: опціонально видаляє провідні $ та #, і може прибирати коментарі або символи продовження, якщо ви їх використовуєте.

Це рідкісний випадок, коли додавання функції зменшує кількість інцидентів. Воно запобігає копіюванню презентаційних артефактів у команди.

Доступність: копіювання — не прикраса

Якщо ваша кнопка копіювання не може бути використана без миші — це не функція, а пропозиція. Зробіть її справжнім контролом:
елементом <button>, до якого можна дістатися з клавіатури, з чіткою підписом.

Вимоги, які слід дотримуватися

• Клавіатура: Табом до кнопки, Enter/Space запускає копіювання.
• Екрани зчитувача: Підпис кнопки має містити контекст, наприклад «Копіювати код» або «Копіювати команду bash».
• Оголошення статусу: Використовуйте регіон з aria-live="polite", щоб оголосити «Скопійовано» або «Не вдалося скопіювати».
• Поведінка фокусу: Не перемикайте фокус назад на блок коду після копіювання; це дезорієнтує.
• Ціль натискання: Зробіть кнопку достатньо великою. У реальному житті люди клікають під час прокручування.

Не покладайтеся лише на колір

Якщо ваш стан «Скопійовано» — лише тонкий зелений відтінок, багато користувачів і багато моніторів цього не помітять. Використовуйте текстові зміни
(«Скопійовано») і, опціонально, іконку, але текст — найнадійніша частина.

SSR/MDX/гідратація: де хороші компоненти поводяться дивно

SSR — це торг на користь надійності: швидший перший рендер, але більше рухомих частин. Блоки коду відомі своїми гідратаційними невідповідностями, бо
підсвітка може виконуватись на сервері, клієнті або обох — і ці шляхи рідко дають біт-ідентичний HTML.

Виберіть одну стратегію рендерингу і дотримуйтеся її

Вам потрібен один із цих варіантів:

• Підсвітка на етапі збірки: Найкращий дефолт для документації. Стабільний HTML, немає гідратаційних невідповідностей, мінімальна CPU-навантаження на клієнті.
• Підсвітка на сервері під час запиту: Прийнятно, якщо кешується агресивно. Слідкуйте за затримками та CPU.
• Клієнтська підсвітка: Лише якщо це абсолютно необхідно (код, згенерований користувачем, динамічна зміна мови). Ставте це як фічу продуктивності, яку треба бюджетувати.

MDX-трансформи можуть «з’їсти» ваш сирий рядок

Багато MDX-пайплайнів токенізують блоки коду, потім емізують React-елементи. Якщо ваш код копіювання читає з відрендерених children,
ви можете отримати нормалізовані пробіли або HTML-декодовані сутності замість оригіналу. Виправте це, передаючи сирий рядок
як проп і копіюючи саме це значення.

Симптоми гідратаційної невідповідності

У продакшені невідповідність може виявлятися так:

• Кнопка копіювання показується двічі (сервер відрендерив одну, клієнт — іншу).
• Кнопка не відповідає, поки не відбудеться повторний рендер.
• Попередження в консолі, які ваша система моніторингу ігнорує… доти, поки конверсії не впадуть.

Зробіть компонент блоку коду детерміністичним і уникайте читання з window або API, доступних лише в браузері, під час серверного рендеру.
Код буфера обміну повинен виконуватися лише під час взаємодії користувача на клієнті.

Продуктивність і рендеринг: не підсвітлюйте себе в кратер

Підсвітка синтаксису — це робота CPU. На сторінці з десятками блоків клієнтська токенізація може домінувати над часом до інтерактивності,
особливо на середніх ноутбуках і корпоративних VDI. Це не теоретично; це поширений інцидент із повільною документацією.

Що робити

• Віддавайте перевагу підсвітці під час збірки. Вашим користувачам не потрібні розкручені вентилятори, щоб читати bash.
• Обмежуйте бандли мов. Завантаження «всіх мов» — це спосіб відправити мегабайт жалю.
• Віртуалізуйте довгі сторінки. Для величезної документації розгляньте рендер тільки того, що видно, але слідкуйте за доступністю payload для копіювання.
• Відкладіть некритичну підсвітку. Ви можете спочатку відрендерити простий <pre> і потім покращити його, але переконайтесь, що це не викликає зсуву макета.

Запобігайте зсуву макета

Блоки коду високі; вони домінують у CLS, коли змінюють висоту після завантаження. Загальні причини:
пізня заміна веб-шрифтів, номера рядків, які додають після гідратації, та контейнери кнопок копіювання, що розширюються.
Резервуйте місце для кнопки. Використовуйте стабільний line-height. Обережно застосовуйте font-display: swap для моноширинних шрифтів.

Прокрутка та виділення теж впливають на продуктивність

Важкий DOM у блоці коду (сотні спанів на рядок) робить виділення повільним. Люди намагаються виділяти вручну, коли копіювання відмовляє.
Якщо виділення стає болючим — ви перетворили дрібний баг у збій юзабіліті.

Жарт №2: Клієнтська підсвітка на сторінці з 200 блоками — це як RAID 0: швидко, доки не потрібно, щоб це було надійно.

Безпека та управління: CSP, приватність і «корисні» логи

Якщо ваш продукт використовується в корпоративному середовищі, передбачайте:
жорсткий CSP, закриті браузери, розширення DLP і групи безпеки, що аудитуїють поведінку з буфером обміну.
Ваш компонент блоку коду має бути «нудно безпечним». Це комплімент.

CSP-безпечна реалізація

Уникайте інлайн-скриптів і стилів, які потребують 'unsafe-inline'. Не просіть відділ безпеки послабити CSP, щоб ваша кнопка працювала.
Прив’язуйте обробники у вашому JS-бандлі. Використовуйте nonce, якщо потрібно інжектувати, але, ймовірно, це не потрібно.

Вміст буфера обміну може бути чутливим

Ставтеся до копійованого контенту як до потенційно секретного. Не робіть наступного:

• Логувати скопійований рядок у аналітику.
• Прикріплювати його до звітів про помилки.
• Відправляти його в інструменти відтворення сесій (session replay).

Натомість логируйте метадані: мова, довжина блоку, чи були промпти, і чи вдалося копіювання.
Якщо вам потрібні додаткові деталі для відладки — робіть це через явний режим налагодження і чистіть дані ретельно.

Корпоративні DLP і блокувальники буфера

Деякі середовища блокують програмне записування в буфер обміну. Ваш UI має деградувати граціозно:
показуйте тултіп «Копіювання заблоковано політикою браузера. Виділіть та скопіюйте вручну.» Не говоріть «Скопійовано!», коли насправді нічого не сталося.

Обсервабельність: міряйте копіювання, не зливаючи секрети

Ви не можете покращити те, чого не вимірюєте, але також не можете створювати головний біль для комплаєнсу. Інструментуйте кнопку копіювання
як продакшен-фічу:

• Коефіцієнт успіху: скільки копіювань пройшло успішно проти невдалих (за браузером, ОС, контекстом вбудовування).
• Латентність: час від кліку до завершеного копіювання (зазвичай малий; сплески вказують на блокування дозволів або зупинки головного потоку).
• Rage clicks: кілька кліків копіювання в короткий проміжок вказують на провал або незрозумілий фідбек.
• Використання фолбеків: як часто спрацьовує execCommand-фолбек.

Захистіться від випадкового збору даних

Якщо ви використовуєте інструменти session replay, переконайтесь, що контент блоків коду замаскований або виключений.
Фрагменти коду можуть містити API-ключі навіть якщо автори обіцяють, що їх нема. Автори — не межа безпеки.

Три корпоративні міні-історії з передової

Міні-історія 1: Інцидент через неправильне припущення

Команда випустила оновлену документацію з новим компонентом блоку коду. Вони припустили, що відрендерений текст у блоці коду
ідентичний сирому рядку. Це було не так. Підсвітка синтаксису вставляла спани з номерами рядків і використовувала CSS для вирівнювання.
Виглядало ідеально.

Їхня кнопка «Копіювати» брала innerText з підсвіченого DOM. У деяких браузерах innerText включав
номери рядків. В інших — ні, залежно від лейауту і властивостей відображення. Та сама сторінка документації давала різний скопійований результат
у різних браузерах.

Радіус ураження був реальним. Популярний фрагмент «запустіть цю команду» став «1 sudo …» і «2 systemctl …». Підтримка завалилися квитками
від клієнтів, чиї автоматизаційні скрипти почали падати. Декілька клієнтів вставили номери рядків у виробничі термінали та отримали плутані помилки «command not found».
Команду документації розбудили, бо «доки» тепер стали залежністю продакшену.

Виправлення було простим і трохи принизливим: припинити копіювати з DOM, нести сирий код як дані й імплементувати явний «copy payload».
Також додали unit-тест, який перевіряє, що payload для копіювання не містить цифр на початку рядків, коли номери рядків увімкнені.
Цей один тест окупився негайно.

Міні-історія 2: Оптимізація, що відкотилася

Інша організація хотіла швидших завантажень сторінок. Хтось запропонував відкладати підсвітку синтаксису на клієнт і lazy-load highlighter
лише коли блоки коду прокручуються у видимість. Здавалося виграшем: менше початкового JS, вища відчутна швидкість.

У продакшені документацію споживали у довгих сесіях. Користувачі швидко скролили, що спричинило хвилю операцій підсвітки на головному потоці.
Скролл переривався. Кнопка копіювання, що залежала від наявності підсвіченого DOM, іноді спрацьовувала до завершення підсвітки і копіювала
усічений контент. Інтермітентно. Нерепродукується у спокійному локальному середовищі.

Моніторинг показав зростання довгих задач і падіння подій «copy success». Команда намагалася заклеїти проблему ретраями і затримками перед копіюванням.
Це тільки зробило гірше. Затримки спалювали «user activation» в деяких браузерах, через що запис у буфер обміну відмовлявся зовсім.
Чим більше вони намагались виправити — тим менше браузер їм довіряв. Гарне резюме людських стосунків також.

Вони відкотилися на підсвітку під час збірки для статичної документації і залишили клієнтську підсвітку лише для «пісочниці», де код генерується користувачем.
Мораль: оптимізувати без чіткого контракту (копія має експортувати сирий рядок) — означає просто пересунути місце відмови.

Міні-історія 3: Нудна, але правильна практика, що врятувала день

Велика корпоративна команда підтримувала бібліотеку компонентів, що використовувалась у маркетингу, документації та внутрішніх runbook-ах. Їхній компонент блоку коду мав
нудний чекліст: стабільна розмітка між SSR і клієнтом, жодних інлайн-скриптів, сирий код зберігається як дані, і суворе правило «не логувати копійований контент».
Ніхто про це не хвалився.

Потім команда безпеки посилила CSP по всьому домену, прибравши дозволи, що тяглися від легасі-віджетів. Передбачувано,
багато випадкових фіч порухались. Попапи померли. Деякі сторонні embed-и перестали рендеритись. Звичайний парад.

Кнопка копіювання в блоці коду не зламалась. Вона не мала інлайн-хендлерів, не залежала від зовнішньої бібліотеки з сумнівним eval, і не залежала
від DOM-мутацій. Вона використовувала стандартний Clipboard API з фолбеком і показувала чітке повідомлення, якщо було заблоковано.
Підтримка не отримала квитків. Ось як виглядає «врятований день» у корпоративному житті: ніхто не помічає, бо нічого не загорілося.

Нагорода команди теж була нудною: їхній компонент став еталоном для інших UI-контролів. Іноді найкращий інцидент — це той, якого не довелося писати.

Плейбук швидкої діагностики

Коли хтось повідомляє «копіювання не працює» або «блоки коду повільні», потрібна швидка, відтворювана трасировка.
Не починайте з переписування компонента. Розпочніть із пошуку вузького місця.

Перший крок: визначте клас відмови

• Невдача буфера обміну: кліки по кнопці, але нічого не потрапляє у буфер; можливо коротка помилка.
• Невірний payload: у буфер потрапляє контент, але він містить промпти/номери рядків/дивні пробіли.
• UI-збій: кнопка неклікабельна, невидима, дублюється або викликає зсув макета.
• Продуктивність: сторінка лагує, прокрутка стрибкоподібна, копіювання затримується.

Другий крок: перевірте середовище й політики

• Браузер і версія (особливо Safari і корпоративний Chrome).
• HTTPS і контекст вбудовування (iframe, портали, knowledge base).
• Заголовки CSP і помилки блокування скриптів.
• Розширення: менеджери паролів, DLP інструменти, «панелі безпеки».

Третій крок: відтворіть з інструментацією, а не з відчуттів

• Чи логина ваш додаток успіх/провал копіювання (без вмісту)?
• Чи бачите ви відхилені проміси буфера обміну?
• Чи є довгі задачі навколо підсвітки?
• Чи є попередження про гідратацію?

Четвертий крок: ізолюйте джерело payload для копіювання

• Якщо копіювання читаєтсья з DOM-тексту: очікуйте непослідовності і виправте це першочергово.
• Якщо копіювання використовує збережений сирий рядок: перевірте нормалізацію (переноси рядків, промпти).
• Якщо копіювання асинхронне: забезпечте, щоб виклик буфера обміну відбувався синхронно в обробнику жесту.

Типові помилки: симптом → корінь → виправлення

1) «Копіювання» працює локально, відмовляє в продакшені

Симптоми: Немає змін у буфері, іноді помилки в консолі, вищий рівень відмов у вбудованих контекстах.

Корінь: Clipboard API заблоковано політикою дозволів, немає HTTPS, або user activation втрачається через асинхронну роботу.

Виправлення: Викликайте запис у буфер одразу на клік; додайте фолбек до execCommand; покажіть користувацьке повідомлення про помилку; перевірте Permissions-Policy і HTTPS.

2) Скопійований текст включає номери рядків

Симптоми: Користувачі вставляють команди з провідними цифрами, скрипти падають, тикети до підтримки з «command not found».

Корінь: Копіювання innerText з DOM, що містить елементи номерів рядків.

Виправлення: Копіюйте зі сирого рядка; якщо потрібні номери рядків для відображення — рендерьте їх окремо і виключайте з payload.

3) Скопійований текст втрачає відступи

Симптоми: YAML/Makefile фрагменти ламаються після копіювання; користувачі кажуть «виглядає правильно, але не працює».

Корінь: Копіювання відрендереного HTML-тексту з нормалізацією пробілів або артефактами переносу.

Виправлення: Зберігайте сирий рядок; використовуйте лише <pre> для відображення; ніколи не відновлюйте код з DOM.

4) Кнопка копіювання викликає зсув макета

Симптоми: Сторінка стрибає при появі кнопки; CLS погіршується; користувачі помилково клікають.

Корінь: Кнопка вставляється лише після гідратації або при hover; місце не зарезервовано.

Виправлення: Рендерити контейнер кнопки на SSR; резервувати фіксоване місце; уникати зміни висоти блоку.

5) Кнопка копіювання працює, але індикація успіху ненадійна

Симптоми: Користувачі клікають кілька разів; «Скопійовано» блимає занадто швидко або не з’являється.

Корінь: Гонки станів; фідбек прив’язаний до виконання промісу без обробки відмов; фокус/hover приховують його.

Виправлення: Використовуйте явні стани успіху/помилки з мінімальним часом відображення; оголошуйте через aria-live; логируйте лише результат.

6) Сторінка повільніє на документації з великою кількістю блоків

Симптоми: Прокрутка лагає, CPU завантажений, довгі задачі, мобільні пристрої страждають.

Корінь: Клієнтська підсвітка на багатьох блоках; занадто багато спанів; важкі бандли мов.

Виправлення: Робіть підсвітку під час збірки; зменшуйте кількість мов; уникайте обгорток на кожному рядку; розгляньте готовий HTML.

7) Попередження гідратації, дубльований UI

Симптоми: Попередження в консолі, дубльована кнопка копіювання, обробники подій не працюють до повторного рендера.

Корінь: Сервер і клієнт рендерять різну розмітку через клієнтську підсвітку або динамічні ID.

Виправлення: Зробіть розмітку блоку коду детерміністичною; генеруйте стабільні ID; уникайте клієнтських перезаписів DOM для статичного контенту.

8) Користувачі повідомляють «копіює нічого» тільки в Safari

Симптоми: Користувачі Safari відмовляють; у Chrome працює.

Корінь: Відмінності Clipboard API, вимоги до жестів або блокування асинхронного потоку.

Виправлення: Додайте execCommand-фолбек; забезпечте негайний виклик буфера обміну; тестуйте на реальному Safari, а не лише в WebKit-in-a-box.

Практичні завдання з командами (і як вирішувати)

Це ті завдання, які я реально виконую під час дебагу «простих» UI-компонентів, що перетворюються на продакшн-проблеми.
Кожне завдання містить: команду, приклад виводу, що це означає, і рішення, яке ви приймаєте.

Завдання 1: Перевірте, що ви віддаєте через HTTPS (вимога Clipboard)

cr0x@server:~$ curl -I https://docs.example.internal/ | sed -n '1,12p'
HTTP/2 200
date: Tue, 04 Feb 2026 10:21:11 GMT
content-type: text/html; charset=utf-8
strict-transport-security: max-age=31536000; includeSubDomains
content-security-policy: default-src 'self'

Вивід означає: Сайт під HTTPS з HSTS. Хороша база для Clipboard API.

Рішення: Якщо це було б HTTP або відсутній HSTS в корпоративному середовищі — спочатку виправте транспорт; не ганяйтесь за UI-привидами.

Завдання 2: Перевірте Content Security Policy на блокування inline/eval

cr0x@server:~$ curl -I https://docs.example.internal/ | grep -i content-security-policy
content-security-policy: default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self'

Вивід означає: Інлайн-скрипти та eval не дозволені, якщо явно не вказано.

Рішення: Якщо ваша кнопка копіювання залежить від інлайн-хендлерів або сторонніх скриптів — вона зламається. Перенесіть обробники в бандл JS і приберіть інлайн.

Завдання 3: Перевірте Permissions-Policy, що може впливати на clipboard у вбудованих контекстах

cr0x@server:~$ curl -I https://docs.example.internal/ | grep -i permissions-policy
permissions-policy: clipboard-write=(self), clipboard-read=()

Вивід означає: Запис у буфер дозволено для same-origin; читання буфера заблоковано.

Рішення: Якщо ви вбудовані в iframe з іншого походження — clipboard-write може бути відмовлено. Вирішіть, чи підтримувати embed-и через дозволені origins або деградувати граціозно.

Завдання 4: Підтвердіть, що SSR-розмітка стабільна між деплоями (виявлення випадкового churn)

cr0x@server:~$ curl -s https://docs.example.internal/guide/install | sha256sum
d3f1c98f9c0e9d7d6a1e8a7c8e6b5d7b8c0a4f5f6e7d8c9b0a1f2e3d4c5b6a7  -

Вивід означає: Хеш контенту для відрендереного HTML. Якщо це змінюється несподівано між ідентичними збірками — ймовірна недетермінованість (часові мітки, випадкові ID).

Рішення: Якщо хеші відрізняються між однаковими збірками — перевірте компонент блоку коду на нестабільні ID та клієнтські мутації.

Завдання 5: Перевірте, що збірки не постачають гігантський highlighter-бандл

cr0x@server:~$ ls -lh dist/assets | sort -hk5 | tail -n 5
-rw-r--r-- 1 cr0x cr0x  88K Feb  4 10:10 app-7f3d1c.js
-rw-r--r-- 1 cr0x cr0x 140K Feb  4 10:10 vendor-22ab9e.js
-rw-r--r-- 1 cr0x cr0x 620K Feb  4 10:10 prism-all-languages-9c8a1b.js
-rw-r--r-- 1 cr0x cr0x 1.2M Feb  4 10:10 replay-sdk-1d0aa1.js
-rw-r--r-- 1 cr0x cr0x 2.4M Feb  4 10:10 analytics-bundle-3aa12c.js

Вивід означає: Ви відправляєте важкий JS. «All languages» highlighter — червона зона для документаційних сторінок.

Рішення: Розбити за мовами або підсвітити на етапі збірки. Також вирішіть, чи потрібні replay і аналітика на документації взагалі.

Завдання 6: Знайдіть використання execCommand як фолбек і переконайтесь, що він обмежений

cr0x@server:~$ rg "execCommand\\('copy'\\)" -n src/
src/components/CodeBlock/clipboard.ts:42:  const ok = document.execCommand('copy')

Вивід означає: Маєте шлях-фолбек. Це ок.

Рішення: Переконайтесь, що він використовується лише коли Clipboard API недоступний/відмовив, і що не виконується під час SSR.

Завдання 7: Підтвердіть, що ви не копіюєте з innerText/outerText

cr0x@server:~$ rg "innerText|outerText|textContent" -n src/components/CodeBlock
src/components/CodeBlock/CodeBlock.tsx:88: const payload = preRef.current?.innerText ?? ''

Вивід означає: Ви копіюєте з DOM-тексту. Це запах ненадійності.

Рішення: Замініть на сирий проп або data-атрибут. DOM-текст — це вигляд, а не контракт.

Завдання 8: Перевірте кінці рядків у джерелах markdown/коду

cr0x@server:~$ file docs/snippets/install.sh
docs/snippets/install.sh: Bourne-Again shell script, ASCII text, with CRLF line terminators

Вивід означає: Фрагмент використовує CRLF. Копію/вставка в деякі shell-і або інструменти може поводитися дивно.

Рішення: Нормалізуйте в LF під час збірки або нормалізуйте payload при копіюванні, зберігаючи відображення стабільним. Оберіть один підхід і документуйте його.

Завдання 9: Виявлення промптів у фрагментах (часта причина невдалих вставок)

cr0x@server:~$ rg -n "^(\\$|#) " docs/snippets
docs/snippets/setup.txt:12:$ curl -fsSL example | bash
docs/snippets/setup.txt:13:# systemctl restart myservice

Вивід означає: Фрагменти містять промпти.

Рішення: Або видаляйте промпти в payload за замовчуванням, або надавайте опцію «копіювати без промптів». Не припускайте, що користувачі видалять їх вручну.

Завдання 10: Перевірте логи сервера на попередження гідратації (SSR-фреймворки)

cr0x@server:~$ journalctl -u docs-web --since "2 hours ago" | grep -i "hydration" | tail -n 5
Feb 04 09:11:03 web-1 docs-web[2187]: Warning: Text content did not match. Server: "Copy" Client: "Copied"
Feb 04 09:11:03 web-1 docs-web[2187]: Warning: An error occurred during hydration. The server HTML was replaced with client content.

Вивід означає: У вас є розбіжність SSR/клієнт, що впливає на UI копіювання.

Рішення: Зробіть серверну розмітку детерміністичною: не рендерте стан «Скопійовано» на сервері, уникайте випадкових ID, і тримайте стратегію підсвітки консистентною.

Завдання 11: Заміряйте довгі задачі, що вказують на проблеми з клієнтською підсвіткою

cr0x@server:~$ node -e "const fs=require('fs');const a=JSON.parse(fs.readFileSync('perf-longtasks.json'));console.log(a.filter(x=>x.duration>50).slice(0,5))"
[
  {"name":"longtask","duration":183.4,"at":"CodeHighlight.run"},
  {"name":"longtask","duration":121.7,"at":"Prism.highlightAll"},
  {"name":"longtask","duration":96.2,"at":"layout"},
  {"name":"longtask","duration":88.9,"at":"CodeHighlight.run"},
  {"name":"longtask","duration":73.1,"at":"Prism.highlightElement"}
]

Вивід означає: Підсвітка спричиняє довгі задачі > 50ms, що користувачі відчувають як лаґ.

Рішення: Перенесіть підсвітку на етап збірки/сервер, зменшіть кількість мов або підсвіткуйте лише видимі блоки — при цьому payload для копіювання має бути незалежним від часу підсвітки.

Завдання 12: Переконайтесь, що аналітичні події не містять скопійованого контенту

cr0x@server:~$ rg -n "copy.*(payload|text|code)" src/analytics
src/analytics/events.ts:55: track('code_copy', { language, length, ok })

Вивід означає: Ви відстежуєте тільки метадані (мова, довжина, результат). Це хороша гігієна.

Рішення: Залишайтеся на цьому шляху. Якщо знайдете «payload» або «text» у логах — видаліть та замініть, і протріть старі логи, які могли захопити секрети.

Завдання 13: Перевірте, що кнопка доступна з клавіатури (базовий smoke test)

cr0x@server:~$ npx playwright test tests/codeblock-a11y.spec.ts --reporter=line
Running 1 test using 1 worker
✓  1 tests/codeblock-a11y.spec.ts:4:1 › Copy button is focusable and announces status (2.3s)

Вивід означає: Ваш тест перевіряє фокусованість кнопки та оголошення статусу.

Рішення: Якщо це падає — вважайте це блокером релізу для бібліотеки компонентів. Регресії доступності стають інцидентами на корпоративному UI.

Завдання 14: Підтвердіть, що порушень CSP немає в pipeline логів браузера

cr0x@server:~$ journalctl -u csp-report-collector --since "6 hours ago" | tail -n 6
Feb 04 08:22:41 csp-1 collector[991]: blocked-uri='inline' violated-directive='script-src' document-uri='https://docs.example.internal/guide/install'
Feb 04 08:22:41 csp-1 collector[991]: blocked-uri='inline' violated-directive='script-src' document-uri='https://docs.example.internal/guide/install'

Вивід означає: Щось все ще намагається виконати інлайн-скрипти на цій сторінці.

Рішення: Знайдіть проблемний компонент або markdown-рендерер. Якщо це ваша кнопка копіювання — виправте її. Якщо це сторонній код — ізолюйте або видаліть його.

Чеклісти / поетапний план

Покроково: випустіть production-grade блок коду з копіюванням

1. Визначте контракт payload для копіювання. Сирий рядок — джерело істини; вирішіть правила для переносів і обробки промптів.
2. Відрендерте стабільну розмітку на SSR. Контейнер кнопки існує на сервері; жодних клієнтських інжекцій, що міняють лейаут.
3. Прикріпляйте обробники в JS-бандлі. Без інлайн-скриптів; CSP-безпечно за замовчуванням.
4. Імплементуйте багаторівневу стратегію буфера обміну. Clipboard API → execCommand-фолбек → ручний фолбек з інструкцією для користувача.
5. Зробіть фідбек явним. Видимий стан «Скопійовано» з мінімальним часом відображення; оголошення через aria-live.
6. Тримайте підсвітку незалежною. Відображення може змінюватись; payload для копіювання не має цього залежати.
7. Бюджетуйте продуктивність. Віддавайте перевагу підсвітці під час збірки; мінімізуйте бандли мов; уникайте span-важкого DOM на великих блоках.
8. Інструментуйте лише результати. Успіх/провал, довжина блоку, мова; ніколи не логируйте payload.
9. Тестуйте режими відмови. Safari, вбудовані iframe, заблокований буфер, жорсткий CSP, лише клавіатура.
10. Напишіть план відкату. Фіче-флаг для кнопки копіювання або фолбек-біхевіору, щоб швидко зупинити витік крові.

Перевірка перед релізом (версія «не будьте на мене зателефонуйте»)

• Копіювання працює з Clipboard API і з execCommand-фолбеком.
• Копія ніколи не включає номери рядків або промпти, якщо користувач цього не обрав.
• Попереджень гідратації немає на репрезентативних сторінках.
• CLS не регресує через появу кнопки або зміну підсвітки.
• Перевірено доступ до клавіатури; перевірено оголошення для screen reader-ів.
• Звіти CSP не показують інлайн/eval-порушень від цього компонента.
• Аналітика не містить вмісту коду.
• Великі сторінки документації залишаються відзивчивими; немає довгих задач через підсвітку.

Чекліст інциденту: користувачі повідомляють «копіювання зламалося»

1. Перевірте, чи помилки корелюють з певним браузером/версією.
2. Перевірте зміни CSP/Permissions-Policy в останньому деплої.
3. Підтвердіть, чи сторінка вбудована (iframe) і чи дозволи дозволяють clipboard-write.
4. Перевірте попередження гідратації навколо блоків коду.
5. Перевірте, чи payload копіювання походить з DOM або зі сирого рядка.
6. Тимчасово включіть повідомлення з ручним фолбеком, якщо буфер заблоковано.
7. Якщо потрібно — відключіть «копіювання» через feature flag, залишивши блоки коду читабельними.

Поширені питання

1) Користуватись navigator.clipboard.writeText чи execCommand('copy')?

Використовуйте navigator.clipboard.writeText як основний шлях. Тримайте execCommand як фолбек, бо корпоративні середовища
та старі браузери все ще існують. Якщо обидва відмовляють — підкажіть користувачу ручне копіювання.

2) Чому не просто копіювати innerText з <pre>?

Бо це недетерміновано. Підсвітка обгортає токени, номери рядків додають вузли, CSS впливає на те, що вважається «текстом», і браузери різняться.
Копіюйте з сирого рядка, який у вас вже є.

3) Чи має payload для копіювання містити кінцевий перенос рядка?

Виберіть одну поведінку і стандартизуйте її. Для shell-команд кінцевий перенос зазвичай прийнятний і часто корисний. Для конфігів (YAML/JSON)
зберігайте точно те, що написав автор, якщо немає сильної причини нормалізувати.

4) Як запобігти копіюванню номерів рядків, при цьому показуючи їх?

Рендерьте номери рядків у окремому елементі, що не включений у payload для копіювання, і ніколи не відновлюйте рядок з DOM-тексту.
Або використовуйте CSS counters тільки для відображення, але все одно копіюйте зі сирого рядка.

5) Чому копіювання відмовляє тільки коли включена аналітика?

Бо хтось дочікувався аналітики перед записом у буфер, втративши user activation. Записи в буфер мають відбуватись одразу в обробнику кліку.
Аналітику відправляйте після або fire-and-forget.

6) Чи потрібно турбуватись про CSP для кнопки копіювання?

Так. Якщо реалізація використовує інлайн-хендлери або інжектує скрипти/стилі, строгий CSP це поламає. Реалізуйте це як нормальний код застосунку з правильним бандлінгом.

7) Яка краща стратегія підсвітки для документації?

Підсвітка під час збірки — найнадійніша і найшвидша для статичної документації. Підсвітка на сервері під час запиту може працювати з кешуванням.
Клієнтську підсвітку залишайте для динамічних або користувацьких сценаріїв і тримайте копіювання незалежним.

8) Як зробити toast «Скопійовано» доступним?

Використовуйте aria-live регіон з polite оголошеннями, тримайте повідомлення достатньо довго, щоб його помітили, і не крадіть фокус.
Також переконайтесь, що підпис кнопки описовий.

9) Як відстежити, чи копіювання працює, не логуючи текст?

Логируйте успіх/провал, мову блоку, приблизну довжину і чи використовувався фолбек. Це достатньо, щоб помітити регресії без збору контенту.

10) А якщо потрібно копіювати рихлий текст (зі стилями) замість plain text?

Для блоків коду за замовчуванням має бути plain text. Рихле копіювання ускладнює справи і може вводити невидимі символи. Якщо потрібно підтримувати разом,
робіть це як окрему фічу з суворими тестами.

Висновок: наступні кроки, які можна відправити цього тижня

Компоненти продакшен-класу не про гарний UI. Вони про усунення двозначностей: що копіюється, коли копіюється,
що відбувається, якщо не вдалося, і як ви діагностуєте помилку. Блоки коду — це не декор; це операційні інтерфейси.

Практичні наступні кроки:

• Рефакторинг копіювання на використання сирого рядка як джерела правди, а не DOM-тексту.
• Реалізуйте багаторівневу обробку буфера обміну з явним фідбеком про помилки.
• Перенесіть підсвітку на етап збірки для статичної документації і сильно обережно скоротіть бандли мов.
• Закріпіть сумісність з CSP і перевірте, що інлайн-скрипти не потрібні.
• Додайте інструментацію, яка фіксує результати і фолбеки, а не вміст.
• Напишіть два тести: один — «немає номерів рядків у копії», інший — «при відмові буфера показано інструкцію вручну».

Якщо ви зробите лише це, ваша кнопка копіювання перестане бути генератором заявок в підтримку і стане тим, чим завжди мала бути:
надійною функцією експорту з приємним інтерфейсом.