@riebeckite/plugin-ux 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright Rerurate_514
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,119 @@
+# @riebeckite/plugin-ux
+
+Client-side progressive enhancements for reading. The plugin leaves the built
+article HTML untouched and adds a reading progress bar, a back-to-top button,
+table-of-contents scroll-spy, and code copy buttons at runtime.
+
+[日本語](./README_ja.md)
+
+## Features
+
+- **Reading progress bar** — a thin fixed bar (`.rb-ux__progress`) that follows
+  the scroll position through the article.
+- **Back-to-top button** — a real `button` (`.rb-ux__back-to-top`) with an
+  `aria-label` that appears after scrolling and smooth-scrolls to the top.
+- **TOC scroll-spy** — observes `a[href^="#"]` links inside the article table of
+  contents with `IntersectionObserver` and marks the active link with
+  `.rb-ux__toc-active`.
+- **Code copy buttons** — wraps each `pre > code` in `.rb-ux__code` and adds a
+  copy button (`.rb-ux__copy`) with a transient "copied" state.
+
+Every feature is a no-op when the relevant DOM is absent, and `initUx()` is
+idempotent.
+
+## Usage
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { uxPlugin } from "@riebeckite/plugin-ux";
+
+export default defineConfig({
+  // ...
+  plugins: [
+    uxPlugin({
+      progress: true,
+      backToTop: true,
+      tocScrollSpy: true,
+      codeCopy: true,
+      backToTopLabel: "Back to top",
+      copyLabel: "Copy",
+      copiedLabel: "Copied",
+    }),
+  ],
+});
+```
+
+The factory is also exported as `ux`.
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `progress` | `boolean` | `true` | Show the reading progress bar |
+| `backToTop` | `boolean` | `true` | Show the back-to-top button |
+| `tocScrollSpy` | `boolean` | `true` | Highlight the active table-of-contents link |
+| `codeCopy` | `boolean` | `true` | Add a copy button to each code block |
+| `backToTopLabel` | `string` | `"Back to top"` | `aria-label` for the back-to-top button |
+| `copyLabel` | `string` | `"Copy"` | Label of the copy button |
+| `copiedLabel` | `string` | `"Copied"` | Transient label shown after copying |
+
+## How configuration reaches the client
+
+Client initializers are bundled statically and cannot receive plugin options.
+At build time the plugin prepends an inert JSON element to each article HTML:
+
+```html
+<script type="application/json" id="rb-ux-config" data-rb-ux-config>{...}</script>
+```
+
+`initUx()` reads that element to restore the options; when it is missing, every
+feature falls back to its enabled default. Injection happens in
+`onPostProcessed` (the object `getProcessedContent()` caches and renders) and is
+mirrored onto remaining manifest entries in `onManifestCreated`. The
+`data-rb-ux-config` attribute doubles as the marker that keeps the element from
+being inserted twice per page.
+
+## Emitted HTML / CSS hooks
+
+| Class | Target |
+| --- | --- |
+| `rb-ux__progress` | Progress bar track (`role="progressbar"`) |
+| `rb-ux__progress-bar` | Bar scaled with `scaleX` |
+| `rb-ux__back-to-top` | Back-to-top button |
+| `rb-ux__back-to-top--visible` | Added while the button is visible |
+| `rb-ux__toc-active` | Active table-of-contents link |
+| `rb-ux__code` | Code block wrapper |
+| `rb-ux__copy` | Copy button |
+| `rb-ux__copy--copied` | Transient copied state |
+
+Styles ship as `@riebeckite/plugin-ux/style.css` and use the theme's
+`--rb-color-*` tokens so they do not fight the existing theme.
+
+## Accessibility
+
+- The back-to-top control is a `button` with an `aria-label`.
+- The progress bar exposes `role="progressbar"` with `aria-valuemin`,
+  `aria-valuemax`, and `aria-valuenow`.
+- The active table-of-contents link receives `aria-current="true"`.
+- Under `prefers-reduced-motion: reduce`, progress and back-to-top transitions
+  are disabled and the back-to-top jump becomes an immediate scroll.
+- Progress bar, buttons, and copy buttons are hidden when printing.
+
+## Limitations
+
+- Client-only: without JavaScript nothing is added.
+- No SPA support; a full page load re-initializes the enhancements.
+- The TOC scroll-spy looks for `.rr-table-of-contents`, `.table-of-contents`,
+  or `[data-rb-toc]` as the table-of-contents container.
+- Copy buttons are skipped inside `.rr-code` blocks (managed by the
+  code-enhance plugin) to avoid duplicate copy UI.
+
+## Exports
+
+- `uxPlugin(options?)` / `ux(options?)` — plugin factory
+- `initUx` — browser initializer
+- Types: `UxOptions`, `UxResolvedConfig`
+
+## See also
+
+- [Plugin guide](../../../docs/en/plugin-system.md)

package/README_ja.md

@@ -0,0 +1,100 @@
+# @riebeckite/plugin-ux
+
+記事の読みやすさを高めるクライアント側のプログレッシブ・エンハンスメントをまとめたプラグインです。ビルド後の記事 HTML はそのままに、読み進捗バー・トップへ戻るボタン・目次のスクロール連動ハイライト・コードのコピーボタンを追加します。
+
+[English](./README.md)
+
+## できること
+
+- **読み進捗バー**: 画面上部に固定した細いバー（`.rb-ux__progress`）が記事のスクロール量に追従します。
+- **トップへ戻るボタン**: 一定量スクロールすると表示される button 要素（`.rb-ux__back-to-top`）。`aria-label` を持ち、スムーズスクロールで先頭へ戻ります。
+- **目次のスクロール連動**: 記事の目次コンテナ内の `a[href^="#"]` を `IntersectionObserver` で監視し、現在位置の見出しリンクに `.rb-ux__toc-active` を付けます。
+- **コードのコピーボタン**: 各 `pre > code`（`.rb-ux__code` でラップ）にコピーボタン（`.rb-ux__copy`）を追加します。コピー直後は一時的に「コピーしました」表示へ切り替わります。
+
+いずれも対応する DOM が無いページでは何もしません。`initUx()` は何度呼んでも二重に初期化しません。
+
+## 使い方
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { uxPlugin } from "@riebeckite/plugin-ux";
+
+export default defineConfig({
+  // ...
+  plugins: [
+    uxPlugin({
+      progress: true,
+      backToTop: true,
+      tocScrollSpy: true,
+      codeCopy: true,
+      backToTopLabel: "トップへ戻る",
+      copyLabel: "コピー",
+      copiedLabel: "コピーしました",
+    }),
+  ],
+});
+```
+
+`uxPlugin` は `ux` という別名でもエクスポートしています。
+
+## オプション
+
+| 項目 | 型 | 既定値 | 説明 |
+| --- | --- | --- | --- |
+| `progress` | `boolean` | `true` | 読み進捗バーを表示する |
+| `backToTop` | `boolean` | `true` | トップへ戻るボタンを表示する |
+| `tocScrollSpy` | `boolean` | `true` | 目次のスクロール連動ハイライトを有効にする |
+| `codeCopy` | `boolean` | `true` | コードのコピーボタンを追加する |
+| `backToTopLabel` | `string` | `"Back to top"` | トップへ戻るボタンの `aria-label` |
+| `copyLabel` | `string` | `"Copy"` | コピーボタンのラベル |
+| `copiedLabel` | `string` | `"Copied"` | コピー成功時に一時表示するラベル |
+
+## 設定がクライアントへ渡る仕組み
+
+クライアント側の初期化コードは静的にバンドルされ、プラグインのオプションを直接受け取れません。そのためこのプラグインは、ビルド時に各記事 HTML の先頭へ次の不活性な JSON 要素を挿入します。
+
+```html
+<script type="application/json" id="rb-ux-config" data-rb-ux-config>{...}</script>
+```
+
+`initUx()` はこの要素を読み取って設定を復元します。要素が無い場合は全機能が有効な既定値で動作します。挿入は `onPostProcessed` で行い、`onManifestCreated` でも未挿入の記事エントリへ反映し、`getProcessedContent()` が返すキャッシュ済み HTML も同時に更新します。挿入はページごとに一度だけで、`data-rb-ux-config` を目印に重複挿入を防ぎます。
+
+## 出力される HTML / CSS フック
+
+| クラス | 対象 |
+| --- | --- |
+| `rb-ux__progress` | 進捗バーのトラック（`role="progressbar"`） |
+| `rb-ux__progress-bar` | 進捗に応じて `scaleX` されるバー |
+| `rb-ux__back-to-top` | トップへ戻る button |
+| `rb-ux__back-to-top--visible` | 表示状態のとき付与 |
+| `rb-ux__toc-active` | 現在位置の目次リンク |
+| `rb-ux__code` | コードブロックのラッパー |
+| `rb-ux__copy` | コピーボタン |
+| `rb-ux__copy--copied` | コピー直後の一時状態 |
+
+スタイルは `@riebeckite/plugin-ux/style.css` として配布し、テーマの `--rb-color-*` トークンを参照するため既存テーマと競合しません。
+
+## アクセシビリティ
+
+- トップへ戻るボタンは `button` 要素で、`aria-label` を持ちます。
+- 進捗バーは `role="progressbar"` と `aria-valuemin` / `aria-valuemax` / `aria-valuenow` を持ちます。
+- 目次の現在位置には `aria-current="true"` を付けます。
+- `prefers-reduced-motion: reduce` では進捗バーとトップへ戻るボタンのアニメーションを無効化し、トップへ戻る動作も即時スクロールへ切り替えます。
+- 印刷時は進捗バー・ボタン・コピーボタンを非表示にします。
+
+## 制限事項
+
+- クライアント専用です。JavaScript が無効な環境では何も追加されません。
+- SPA ナビゲーションには対応しません。ページ遷移後は再読み込み時に初期化されます。
+- 目次のスクロール連動は `.rr-table-of-contents`、`.table-of-contents`、`[data-rb-toc]` のいずれかを目次コンテナとして探します。
+- コードのコピーボタンは `.rr-code`（code-enhance プラグインが管理するブロック）には追加しません。二重のコピー UI を避けるためです。
+
+## 主なエクスポート
+
+- `uxPlugin(options?)` / `ux(options?)`: プラグインを作成する
+- `initUx`: クライアント側の初期化
+- 型: `UxOptions`、`UxResolvedConfig`
+
+## 関連資料
+
+- [プラグインシステム](../../../docs/ja/plugin-system.md)

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+export { initUx } from "./src/init.js";
+export type { UxOptions, UxResolvedConfig } from "./src/options.js";

package/dist/client.js

@@ -0,0 +1,286 @@
+// src/options.ts
+var UX_CONFIG_ELEMENT_ID = "rb-ux-config";
+var DEFAULT_UX_CONFIG = {
+  progress: true,
+  backToTop: true,
+  tocScrollSpy: true,
+  codeCopy: true,
+  backToTopLabel: "Back to top",
+  copyLabel: "Copy",
+  copiedLabel: "Copied"
+};
+
+// src/init.ts
+var PROGRESS_CLASS = "rb-ux__progress";
+var PROGRESS_BAR_CLASS = "rb-ux__progress-bar";
+var BACK_TO_TOP_CLASS = "rb-ux__back-to-top";
+var BACK_TO_TOP_VISIBLE_CLASS = "rb-ux__back-to-top--visible";
+var TOC_ACTIVE_CLASS = "rb-ux__toc-active";
+var CODE_CLASS = "rb-ux__code";
+var COPY_CLASS = "rb-ux__copy";
+var COPY_COPIED_CLASS = "rb-ux__copy--copied";
+var BACK_TO_TOP_THRESHOLD = 320;
+var COPIED_STATE_DURATION = 1500;
+var started = false;
+var copiedTimers = /* @__PURE__ */ new WeakMap();
+function initUx() {
+  if (started) return;
+  started = true;
+  const config = readUxConfig();
+  const run = () => {
+    if (config.progress) setupProgress();
+    if (config.backToTop) setupBackToTop(config);
+    if (config.tocScrollSpy) setupTocScrollSpy();
+    if (config.codeCopy) setupCodeCopy(config);
+  };
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", run, { once: true });
+  } else {
+    run();
+  }
+}
+function readUxConfig() {
+  const element = document.getElementById(UX_CONFIG_ELEMENT_ID);
+  const parsed = parseConfig(element?.textContent ?? null);
+  if (!parsed) return { ...DEFAULT_UX_CONFIG };
+  return {
+    progress: readBoolean(parsed.progress, DEFAULT_UX_CONFIG.progress),
+    backToTop: readBoolean(parsed.backToTop, DEFAULT_UX_CONFIG.backToTop),
+    tocScrollSpy: readBoolean(
+      parsed.tocScrollSpy,
+      DEFAULT_UX_CONFIG.tocScrollSpy
+    ),
+    codeCopy: readBoolean(parsed.codeCopy, DEFAULT_UX_CONFIG.codeCopy),
+    backToTopLabel: readString(
+      parsed.backToTopLabel,
+      DEFAULT_UX_CONFIG.backToTopLabel
+    ),
+    copyLabel: readString(parsed.copyLabel, DEFAULT_UX_CONFIG.copyLabel),
+    copiedLabel: readString(parsed.copiedLabel, DEFAULT_UX_CONFIG.copiedLabel)
+  };
+}
+function parseConfig(raw) {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function readBoolean(value, fallback) {
+  return typeof value === "boolean" ? value : fallback;
+}
+function readString(value, fallback) {
+  return typeof value === "string" && value.trim().length > 0 ? value : fallback;
+}
+function setupProgress() {
+  const article = findArticle();
+  if (!article || hasElement(PROGRESS_CLASS)) return;
+  const track = document.createElement("div");
+  track.className = PROGRESS_CLASS;
+  track.setAttribute("role", "progressbar");
+  track.setAttribute("aria-label", "Reading progress");
+  track.setAttribute("aria-valuemin", "0");
+  track.setAttribute("aria-valuemax", "100");
+  const fill = document.createElement("span");
+  fill.className = PROGRESS_BAR_CLASS;
+  track.append(fill);
+  document.body.append(track);
+  const update = () => {
+    const ratio = readingProgress(article);
+    fill.style.transform = `scaleX(${ratio})`;
+    track.setAttribute("aria-valuenow", String(Math.round(ratio * 100)));
+  };
+  scheduleOnScroll(update);
+}
+function readingProgress(article) {
+  const top = article.getBoundingClientRect().top + window.scrollY;
+  const end = top + article.offsetHeight - window.innerHeight;
+  if (end <= top) return window.scrollY >= top ? 1 : 0;
+  return clamp((window.scrollY - top) / (end - top), 0, 1);
+}
+function setupBackToTop(config) {
+  if (hasElement(BACK_TO_TOP_CLASS)) return;
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = BACK_TO_TOP_CLASS;
+  button.setAttribute("aria-label", config.backToTopLabel);
+  button.textContent = "↑";
+  button.addEventListener("click", () => {
+    window.scrollTo({
+      top: 0,
+      behavior: prefersReducedMotion() ? "auto" : "smooth"
+    });
+  });
+  document.body.append(button);
+  const threshold = () => Math.max(BACK_TO_TOP_THRESHOLD, window.innerHeight * 0.5);
+  const update = () => {
+    button.classList.toggle(
+      BACK_TO_TOP_VISIBLE_CLASS,
+      window.scrollY >= threshold()
+    );
+  };
+  scheduleOnScroll(update);
+}
+function setupTocScrollSpy() {
+  const container = document.querySelector(
+    ".rr-table-of-contents, .table-of-contents, [data-rb-toc]"
+  );
+  if (!container || container.dataset.rbUxToc === "true") return;
+  const links = Array.from(
+    container.querySelectorAll('a[href^="#"]')
+  );
+  if (links.length === 0) return;
+  const linksById = /* @__PURE__ */ new Map();
+  for (const link of links) {
+    const id = hashToId(link.getAttribute("href"));
+    if (!id) continue;
+    const existing = linksById.get(id) ?? [];
+    existing.push(link);
+    linksById.set(id, existing);
+  }
+  const headings = Array.from(linksById.keys()).map((id) => document.getElementById(id)).filter((heading) => heading !== null);
+  if (headings.length === 0) return;
+  container.dataset.rbUxToc = "true";
+  const activate = (id) => {
+    for (const link of links) {
+      link.classList.remove(TOC_ACTIVE_CLASS);
+      link.removeAttribute("aria-current");
+    }
+    for (const link of linksById.get(id) ?? []) {
+      link.classList.add(TOC_ACTIVE_CLASS);
+      link.setAttribute("aria-current", "true");
+    }
+  };
+  const visible = /* @__PURE__ */ new Map();
+  let activeId = null;
+  const updateActive = () => {
+    let nextId = null;
+    if (visible.size > 0) {
+      let bestTop = Number.POSITIVE_INFINITY;
+      for (const [id, top] of visible) {
+        if (top < bestTop) {
+          bestTop = top;
+          nextId = id;
+        }
+      }
+    } else {
+      for (const heading of headings) {
+        if (heading.getBoundingClientRect().top <= 0) nextId = heading.id;
+      }
+    }
+    nextId ??= headings[0]?.id ?? null;
+    if (nextId && nextId !== activeId) {
+      activeId = nextId;
+      activate(nextId);
+    }
+  };
+  if (typeof IntersectionObserver === "function") {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          const id = entry.target.id;
+          if (!id) continue;
+          if (entry.isIntersecting) {
+            visible.set(id, entry.boundingClientRect.top);
+          } else {
+            visible.delete(id);
+          }
+        }
+        updateActive();
+      },
+      { rootMargin: "-10% 0px -60% 0px", threshold: [0, 1] }
+    );
+    for (const heading of headings) observer.observe(heading);
+  }
+  scheduleOnScroll(updateActive);
+}
+function setupCodeCopy(config) {
+  const blocks = Array.from(document.querySelectorAll("pre > code"));
+  for (const code of blocks) {
+    const pre = code.parentElement;
+    if (!pre || pre.dataset.rbUxCopy === "true") continue;
+    if (pre.closest(".rr-code")) continue;
+    pre.dataset.rbUxCopy = "true";
+    const wrapper = document.createElement("div");
+    wrapper.className = CODE_CLASS;
+    pre.replaceWith(wrapper);
+    wrapper.append(pre);
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = COPY_CLASS;
+    button.setAttribute("aria-label", config.copyLabel);
+    button.textContent = config.copyLabel;
+    button.addEventListener("click", () => {
+      void copyCode(button, code, config);
+    });
+    wrapper.append(button);
+  }
+}
+async function copyCode(button, code, config) {
+  const text = code.textContent ?? "";
+  const clipboard = navigator.clipboard;
+  if (text.length === 0 || !clipboard) return;
+  try {
+    await clipboard.writeText(text);
+  } catch {
+    return;
+  }
+  showCopiedState(button, config);
+}
+function showCopiedState(button, config) {
+  const previous = copiedTimers.get(button);
+  if (previous !== void 0) window.clearTimeout(previous);
+  button.textContent = config.copiedLabel;
+  button.classList.add(COPY_COPIED_CLASS);
+  const timer = window.setTimeout(() => {
+    button.textContent = config.copyLabel;
+    button.classList.remove(COPY_COPIED_CLASS);
+    copiedTimers.delete(button);
+  }, COPIED_STATE_DURATION);
+  copiedTimers.set(button, timer);
+}
+function findArticle() {
+  return document.querySelector(
+    ".rb-article-body, .article-shell__body, [data-slot='article-body'], article"
+  );
+}
+function hasElement(className) {
+  return document.querySelector(`.${className}`) !== null;
+}
+function hashToId(href) {
+  if (typeof href !== "string" || href.length < 2) return null;
+  if (!href.startsWith("#")) return null;
+  const raw = href.slice(1);
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+function prefersReducedMotion() {
+  return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+function scheduleOnScroll(update) {
+  let frame = 0;
+  const schedule = () => {
+    if (frame) return;
+    frame = requestAnimationFrame(() => {
+      frame = 0;
+      update();
+    });
+  };
+  window.addEventListener("scroll", schedule, { passive: true });
+  window.addEventListener("resize", schedule);
+  update();
+}
+export {
+  initUx
+};

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { type UxOptions } from "./src/options.js";
+export type { UxOptions, UxResolvedConfig } from "./src/options.js";
+/**
+ * Client-only progressive enhancements: a reading progress bar, a
+ * back-to-top button, table-of-contents scroll-spy, and code copy buttons.
+ *
+ * None of the features change the rendered article markup, so the plugin
+ * only injects a JSON config element and registers a browser initializer.
+ */
+export declare function uxPlugin(options?: UxOptions): import("@riebeckite/core").RiebeckitePlugin<UxOptions>;
+/** Alias kept for naming symmetry with the other plugin factories. */
+export declare const ux: typeof uxPlugin;

package/dist/index.js

@@ -0,0 +1,104 @@
+// index.ts
+import {
+  createClientEntry,
+  createStyleAsset,
+  definePlugin,
+  isPublished
+} from "@riebeckite/core";
+
+// src/options.ts
+var UX_CONFIG_ELEMENT_ID = "rb-ux-config";
+var UX_CONFIG_ATTRIBUTE = "data-rb-ux-config";
+var DEFAULT_UX_CONFIG = {
+  progress: true,
+  backToTop: true,
+  tocScrollSpy: true,
+  codeCopy: true,
+  backToTopLabel: "Back to top",
+  copyLabel: "Copy",
+  copiedLabel: "Copied"
+};
+function resolveUxConfig(options = {}) {
+  return {
+    progress: options.progress ?? DEFAULT_UX_CONFIG.progress,
+    backToTop: options.backToTop ?? DEFAULT_UX_CONFIG.backToTop,
+    tocScrollSpy: options.tocScrollSpy ?? DEFAULT_UX_CONFIG.tocScrollSpy,
+    codeCopy: options.codeCopy ?? DEFAULT_UX_CONFIG.codeCopy,
+    backToTopLabel: normalizeLabel(
+      options.backToTopLabel,
+      DEFAULT_UX_CONFIG.backToTopLabel
+    ),
+    copyLabel: normalizeLabel(options.copyLabel, DEFAULT_UX_CONFIG.copyLabel),
+    copiedLabel: normalizeLabel(
+      options.copiedLabel,
+      DEFAULT_UX_CONFIG.copiedLabel
+    )
+  };
+}
+function normalizeLabel(value, fallback) {
+  return typeof value === "string" && value.trim().length > 0 ? value : fallback;
+}
+
+// src/inject.ts
+function renderUxConfigElement(config) {
+  const json = JSON.stringify(config).replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+  return `<script type="application/json" id="${UX_CONFIG_ELEMENT_ID}" ${UX_CONFIG_ATTRIBUTE}>${json}</script>`;
+}
+function injectUxConfig(html, config) {
+  if (html.includes(UX_CONFIG_ATTRIBUTE)) return html;
+  return `${renderUxConfigElement(config)}${html}`;
+}
+
+// index.ts
+function uxPlugin(options = {}) {
+  const config = resolveUxConfig(options);
+  const tracked = /* @__PURE__ */ new Map();
+  return definePlugin({
+    name: "ux",
+    options,
+    validateOptions: validateUxOptions,
+    assets: [createStyleAsset("ux")],
+    clientEntries: [createClientEntry("ux", "initUx")],
+    onPostProcessed: (context) => {
+      context.content.html = injectUxConfig(context.content.html, config);
+      tracked.set(context.slug, context.content);
+    },
+    onManifestCreated: (context) => {
+      const siteConfig = context.config;
+      for (const entry of context.manifest.entries) {
+        if (siteConfig && !isPublished(siteConfig, entry.frontmatter)) continue;
+        const html = injectUxConfig(entry.html, config);
+        if (html === entry.html) continue;
+        entry.html = html;
+        const content = tracked.get(entry.slug);
+        if (content) content.html = html;
+      }
+    }
+  });
+}
+var ux = uxPlugin;
+function validateUxOptions(options) {
+  if (!options) return [];
+  const issues = [];
+  for (const key of [
+    "progress",
+    "backToTop",
+    "tocScrollSpy",
+    "codeCopy"
+  ]) {
+    if (options[key] !== void 0 && typeof options[key] !== "boolean") {
+      issues.push({ path: key, message: "Expected a boolean." });
+    }
+  }
+  for (const key of ["backToTopLabel", "copyLabel", "copiedLabel"]) {
+    const value = options[key];
+    if (value !== void 0 && (typeof value !== "string" || value.trim() === "")) {
+      issues.push({ path: key, message: "Expected a non-empty string." });
+    }
+  }
+  return issues;
+}
+export {
+  ux,
+  uxPlugin
+};

package/dist/src/init.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Initializes every enabled UX enhancement. Safe to call more than once and a
+ * no-op when the relevant DOM elements are absent.
+ */
+export declare function initUx(): void;

package/dist/src/inject.d.ts

@@ -0,0 +1,16 @@
+import { type UxResolvedConfig } from "./options.js";
+/**
+ * Serializes the resolved options into an inert JSON script element.
+ *
+ * Client initializers are static and receive no plugin options, so the build
+ * injects this element into the article HTML and reads it back at runtime.
+ * `<` and `>` are escaped so labels can never terminate the script element.
+ */
+export declare function renderUxConfigElement(config: UxResolvedConfig): string;
+/**
+ * Prepends the configuration element exactly once.
+ *
+ * The attribute doubles as the idempotency marker, so repeated calls (for
+ * example from both `onPostProcessed` and `onManifestCreated`) are no-ops.
+ */
+export declare function injectUxConfig(html: string, config: UxResolvedConfig): string;

package/dist/src/options.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Public option and configuration types for the UX plugin.
+ *
+ * This module is imported by both the build-time plugin and the browser
+ * initializer, so it must stay free of Node-only and Riebeckite-only imports.
+ */
+export type UxOptions = {
+    /** Show a fixed reading-progress bar for the article. Defaults to `true`. */
+    progress?: boolean;
+    /** Show a back-to-top button after scrolling. Defaults to `true`. */
+    backToTop?: boolean;
+    /** Highlight the active entry in the article table of contents. Defaults to `true`. */
+    tocScrollSpy?: boolean;
+    /** Add a copy button to every code block. Defaults to `true`. */
+    codeCopy?: boolean;
+    /** Accessible label for the back-to-top button. */
+    backToTopLabel?: string;
+    /** Label for the code copy button. */
+    copyLabel?: string;
+    /** Transient label shown after a successful copy. */
+    copiedLabel?: string;
+};
+/** Options after defaults have been applied. Serialized into the page. */
+export type UxResolvedConfig = {
+    progress: boolean;
+    backToTop: boolean;
+    tocScrollSpy: boolean;
+    codeCopy: boolean;
+    backToTopLabel: string;
+    copyLabel: string;
+    copiedLabel: string;
+};
+/** Id of the JSON configuration element injected into each article. */
+export declare const UX_CONFIG_ELEMENT_ID = "rb-ux-config";
+/** Attribute used both to stamp the config element and to detect it. */
+export declare const UX_CONFIG_ATTRIBUTE = "data-rb-ux-config";
+/** Defaults used when an option is omitted or the config element is absent. */
+export declare const DEFAULT_UX_CONFIG: UxResolvedConfig;
+/** Applies defaults to the user-provided options. */
+export declare function resolveUxConfig(options?: UxOptions): UxResolvedConfig;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@riebeckite/plugin-ux",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./index.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "source": "./client.ts",
+      "default": "./dist/client.js"
+    },
+    "./style.css": "./style.css"
+  },
+  "dependencies": {
+    "@riebeckite/core": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README_ja.md",
+    "dist",
+    "style.css"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rerurate514/riebeckite.git",
+    "directory": "packages/plugins/ux"
+  },
+  "homepage": "https://github.com/Rerurate514/riebeckite#readme",
+  "bugs": {
+    "url": "https://github.com/Rerurate514/riebeckite/issues"
+  },
+  "description": "Reading experience enhancements for Riebeckite sites.",
+  "keywords": [
+    "riebeckite",
+    "plugin",
+    "user-experience",
+    "progressive-enhancement"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "sideEffects": [
+    "./style.css"
+  ],
+  "scripts": {
+    "build": "node ../../../scripts/build_package.mjs"
+  }
+}

package/style.css

@@ -0,0 +1,127 @@
+.rb-ux__progress {
+  position: fixed;
+  inset-block-start: 0;
+  inset-inline: 0;
+  z-index: 60;
+  height: 3px;
+  pointer-events: none;
+  background: color-mix(
+    in srgb,
+    var(--rb-color-ink, #1c1a17) 8%,
+    transparent
+  );
+}
+
+.rb-ux__progress-bar {
+  display: block;
+  width: 100%;
+  height: 100%;
+  transform: scaleX(0);
+  transform-origin: left center;
+  background: var(--rb-color-accent, #686868);
+  transition: transform 100ms linear;
+}
+
+.rb-ux__back-to-top {
+  position: fixed;
+  inset-block-end: 1.5rem;
+  inset-inline-end: 1.5rem;
+  z-index: 60;
+  display: grid;
+  place-items: center;
+  width: 2.75rem;
+  height: 2.75rem;
+  padding: 0;
+  border: 1px solid
+    var(--rb-color-border-strong, var(--rb-color-border, #d0ccc4));
+  border-radius: 999px;
+  background: var(--rb-color-surface, var(--rb-color-paper, #ffffff));
+  color: var(--rb-color-ink, #1c1a17);
+  font-size: 1.15rem;
+  line-height: 1;
+  cursor: pointer;
+  opacity: 0;
+  visibility: hidden;
+  transform: translateY(0.5rem);
+  transition:
+    opacity 150ms ease,
+    transform 150ms ease,
+    visibility 150ms ease;
+}
+
+.rb-ux__back-to-top--visible {
+  opacity: 1;
+  visibility: visible;
+  transform: none;
+}
+
+.rb-ux__back-to-top:hover {
+  background: var(--rb-color-surface-hover, var(--rb-color-surface, #f4f2ee));
+}
+
+.rb-ux__back-to-top:focus-visible {
+  outline: 2px solid var(--rb-color-accent, #686868);
+  outline-offset: 2px;
+}
+
+.rb-ux__toc-active {
+  color: var(--rb-color-accent, #686868);
+  font-weight: 600;
+}
+
+.rb-ux__code {
+  position: relative;
+}
+
+.rb-ux__copy {
+  position: absolute;
+  inset-block-start: 0.5rem;
+  inset-inline-end: 0.5rem;
+  z-index: 1;
+  padding: 0.2rem 0.5rem;
+  border: 1px solid
+    var(--rb-color-border, color-mix(in srgb, currentColor 20%, transparent));
+  border-radius: 4px;
+  background: var(--rb-color-surface, var(--rb-color-paper, #ffffff));
+  color: var(--rb-color-muted, #69645c);
+  font-size: 0.75rem;
+  line-height: 1.4;
+  cursor: pointer;
+  opacity: 0.9;
+  transition:
+    opacity 120ms ease,
+    color 120ms ease,
+    border-color 120ms ease;
+}
+
+.rb-ux__copy:hover,
+.rb-ux__copy:focus-visible {
+  opacity: 1;
+  color: var(--rb-color-ink, #1c1a17);
+}
+
+.rb-ux__copy:focus-visible {
+  outline: 2px solid var(--rb-color-accent, #686868);
+  outline-offset: 2px;
+}
+
+.rb-ux__copy--copied {
+  color: var(--rb-color-accent, #686868);
+  border-color: var(--rb-color-accent, #686868);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .rb-ux__progress-bar,
+  .rb-ux__back-to-top,
+  .rb-ux__copy {
+    transition: none;
+  }
+}
+
+@media print {
+  .rb-ux__progress,
+  .rb-ux__back-to-top,
+  .rb-ux__copy {
+    display: none;
+  }
+}