RubyGems - copy_tuner_client - Versions diffs - 1.5.0 → 2.1.0 - Mend

copy_tuner_client 1.5.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

checksums.yaml +4 -4
data/.gitattributes +2 -2
data/.github/workflows/rspec.yml +1 -1
data/CHANGELOG.md +27 -0
data/CLAUDE.md +6 -4
data/README.md +6 -27
data/UPGRADING.md +201 -0
data/app/assets/javascripts/copytuner.js +162 -250
data/biome.json +39 -0
data/index.html +9 -11
data/lib/copy_tuner_client/cache.rb +0 -2
data/lib/copy_tuner_client/configuration.rb +23 -37
data/lib/copy_tuner_client/copyray/marker.rb +24 -0
data/lib/copy_tuner_client/copyray/rewriter.rb +113 -0
data/lib/copy_tuner_client/copyray.rb +11 -4
data/lib/copy_tuner_client/copyray_middleware.rb +10 -8
data/lib/copy_tuner_client/engine.rb +1 -1
data/lib/copy_tuner_client/helper_extension.rb +0 -3
data/lib/copy_tuner_client/i18n_backend.rb +5 -12
data/lib/copy_tuner_client/version.rb +1 -1
data/mise.toml +3 -0
data/package.json +9 -13
data/pnpm-lock.yaml +600 -0
data/skills/copy-tuner/SKILL.md +37 -6
data/skills/copy-tuner-to-locales-cleanup/SKILL.md +4 -4
data/skills/copy-tuner-to-locales-migrate-prefix/references/local-first-regexp.md +4 -9
data/skills/copy-tuner-to-t-migrate/SKILL.md +131 -0
data/skills/copy-tuner-to-t-migrate/scripts/migrate_tt.rb +189 -0
data/spec/copy_tuner_client/cache_spec.rb +2 -10
data/spec/copy_tuner_client/client_spec.rb +1 -0
data/spec/copy_tuner_client/configuration_spec.rb +16 -16
data/spec/copy_tuner_client/copyray/marker_spec.rb +41 -0
data/spec/copy_tuner_client/copyray/rewriter_spec.rb +216 -0
data/spec/copy_tuner_client/copyray_middleware_spec.rb +88 -0
data/spec/copy_tuner_client/copyray_spec.rb +22 -39
data/spec/copy_tuner_client/helper_extension_spec.rb +18 -5
data/spec/copy_tuner_client/i18n_backend_spec.rb +8 -15
data/spec/support/client_spec_helpers.rb +0 -1
data/src/copyray-overlay.ts +125 -0
data/src/copytuner-bar.ts +153 -0
data/src/main.ts +33 -26
data/src/{copyray.css → styles.ts} +112 -136
data/src/util.ts +9 -1
data/tsconfig.json +5 -10
data/vite.config.ts +0 -1
metadata +15 -8
data/.eslintrc.js +0 -12
data/app/assets/stylesheets/copytuner.css +0 -1
data/src/copyray.ts +0 -130
data/src/copytuner_bar.ts +0 -115
data/src/specimen.ts +0 -84
data/yarn.lock +0 -2540

data/spec/copy_tuner_client/copyray/rewriter_spec.rb ADDED Viewed

@@ -0,0 +1,216 @@
+require 'spec_helper'
+require 'copy_tuner_client/copyray/marker'
+require 'copy_tuner_client/copyray/rewriter'
+describe CopyTunerClient::Copyray::Rewriter do
+  def marker(key)
+    CopyTunerClient::Copyray::Marker.encode(key)
+  end
+  def ascii8(str)
+    str.dup.force_encoding(Encoding::ASCII_8BIT)
+  end
+  describe '.rewrite' do
+    # NOTE: rewrite は [html, skipped] を返すが、既存テストの大半は html だけを検証する。
+    # 1 回の呼び出しを let でメモ化して共有し、result は html、skipped は 2 要素目を指す。
+    let(:rewritten) { described_class.rewrite(html) }
+    subject(:result) { rewritten.first }
+    let(:skipped) { rewritten.last }
+    context '要素直下の単純なテキストノード' do
+      let(:html) { "<html><body><p>#{marker('a.b')}Hello</p></body></html>" }
+      it '親要素に data-copyray-key を付与する' do
+        expect(result).to include('data-copyray-key="a.b"')
+      end
+      it 'マーカートークンを除去する' do
+        expect(result).not_to match CopyTunerClient::Copyray::Marker::SCAN_REGEXP
+        expect(result).to include('>Hello<')
+      end
+      it 'skipped が false を返す（属性付与に成功した）' do
+        expect(skipped).to be false
+      end
+    end
+    context 'ActionView が body を html エスケープした平文訳文（トークンは無傷）' do
+      # NOTE: 平文訳文は ActionView がエスケープするため body の & < > はエンティティ化するが、
+      # トークンの区切り記号 ⟦⟧ は HTML 特殊文字ではないので無傷で残る。Rewriter はこれを拾えること。
+      let(:html) { "<html><body><p>#{marker('plain.key')}Hello &amp; &lt;World&gt;</p></body></html>" }
+      it '要素に属性を付与しトークンを除去するが、エスケープ済み body はそのまま残す' do
+        expect(Nokogiri::HTML(result).at_css('p')['data-copyray-key']).to eq 'plain.key'
+        expect(result).not_to match CopyTunerClient::Copyray::Marker::SCAN_REGEXP
+        expect(result).to include('Hello &amp; &lt;World&gt;')
+      end
+    end
+    context 'ネストしたインライン要素内のマーカー' do
+      let(:html) { "<html><body><p>foo <a>#{marker('link.key')}Hi</a> bar</p></body></html>" }
+      it '最も近い親要素（<a>）に属性を付与する' do
+        fragment = Nokogiri::HTML(result)
+        a = fragment.at_css('a')
+        expect(a['data-copyray-key']).to eq 'link.key'
+        expect(fragment.at_css('p')['data-copyray-key']).to be_nil
+      end
+    end
+    context 'テキスト中間に置かれたマーカー' do
+      let(:html) { "<html><body><p>foo #{marker('mid.key')}Hi</p></body></html>" }
+      it '内包する要素に属性を付与する' do
+        expect(Nokogiri::HTML(result).at_css('p')['data-copyray-key']).to eq 'mid.key'
+      end
+    end
+    context '属性値の中のマーカー' do
+      let(:html) { %(<html><body><input placeholder="#{marker('search.placeholder')}検索"></body></html>) }
+      it '要素自身に data-copyray-key を付与する' do
+        expect(Nokogiri::HTML(result).at_css('input')['data-copyray-key']).to eq 'search.placeholder'
+      end
+      it '属性値からトークンを除去する' do
+        placeholder = Nokogiri::HTML(result).at_css('input')['placeholder']
+        expect(placeholder).to eq '検索'
+      end
+    end
+    context 'head（title）の中のマーカー' do
+      let(:html) { "<html><head><title>#{marker('page.title')}タイトル</title></head><body></body></html>" }
+      it 'トークンを除去する' do
+        expect(result).not_to match CopyTunerClient::Copyray::Marker::SCAN_REGEXP
+        expect(Nokogiri::HTML(result).at_css('title').text).to eq 'タイトル'
+      end
+    end
+    context '同一テキストノード内の複数マーカー' do
+      let(:html) { "<html><body><p>#{marker('first.key')}A#{marker('second.key')}B</p></body></html>" }
+      it 'すべてのキーをカンマ区切りで data-copyray-key に保持する' do
+        expect(Nokogiri::HTML(result).at_css('p')['data-copyray-key']).to eq 'first.key,second.key'
+      end
+      it 'すべてのトークンを除去する' do
+        expect(result).not_to match CopyTunerClient::Copyray::Marker::SCAN_REGEXP
+      end
+    end
+    context '同一属性値内の複数マーカー' do
+      let(:html) { %(<html><body><input placeholder="#{marker('a.key')}x#{marker('b.key')}y"></body></html>) }
+      it 'すべてのキーをカンマ区切りで data-copyray-key に保持する' do
+        expect(Nokogiri::HTML(result).at_css('input')['data-copyray-key']).to eq 'a.key,b.key'
+      end
+      it '属性値からすべてのトークンを除去する' do
+        expect(Nokogiri::HTML(result).at_css('input')['placeholder']).to eq 'xy'
+      end
+    end
+    context 'マーカーが無い html' do
+      let(:html) { '<html><body><p>Nothing to see</p></body></html>' }
+      it 'html を無変形で返す（no-op 高速パス）' do
+        expect(result).to eq html
+      end
+      it 'skipped が false を返す（変形していない）' do
+        expect(skipped).to be false
+      end
+    end
+    context 'HTML が閾値（MAX_REWRITE_BYTESIZE）を超える場合' do
+      # NOTE: マーカーを含みつつ閾値超のサイズにするため、padding でかさ増しする。
+      let(:padding) { '<span>x</span>' * ((described_class::MAX_REWRITE_BYTESIZE / 14) + 1) }
+      let(:html) { "<html><body><p>#{marker('big.key')}Hello</p>#{padding}</body></html>" }
+      it '閾値を超えるサイズである（前提確認）' do
+        expect(html.bytesize).to be > described_class::MAX_REWRITE_BYTESIZE
+      end
+      it 'マーカートークンを除去する' do
+        expect(result).not_to match CopyTunerClient::Copyray::Marker::SCAN_REGEXP
+      end
+      it 'data-copyray-key を付与しない（Nokogiri を通さない）' do
+        expect(result).not_to include(described_class::DATA_ATTR)
+      end
+      it 'skipped が true を返す' do
+        expect(skipped).to be true
+      end
+    end
+    context 'ASCII-8BIT に転落したがマーカーを含む body' do
+      let(:html) { ascii8("<html><body><p>#{marker('a.b')}日本語</p></body></html>") }
+      it '例外を投げず親要素に属性を付与する' do
+        expect { result }.not_to raise_error
+        expect(Nokogiri::HTML(result).at_css('p')['data-copyray-key']).to eq 'a.b'
+        expect(result).not_to match CopyTunerClient::Copyray::Marker::SCAN_REGEXP
+      end
+    end
+    context 'マーカーが無い ASCII-8BIT の body' do
+      let(:html) { ascii8('<html><body><p>日本語</p></body></html>') }
+      it '例外を投げず無変形で返す' do
+        expect { result }.not_to raise_error
+      end
+      it '渡された文字列のエンコーディングを破壊しない' do
+        result
+        expect(html.encoding).to eq Encoding::ASCII_8BIT
+      end
+    end
+    context 'rewrite が内部で例外を投げる' do
+      # NOTE: 壊れた HTML 等で Nokogiri 処理が例外を投げる状況を模す。
+      #       Copyray は開発支援機能なので、ここでページを 500 にしない（フォールバック動作）。
+      let(:html) { "<html><body><p>#{marker('a.b')}Hello</p></body></html>" }
+      before do
+        allow(described_class).to receive(:rewrite_with_nokogiri).and_raise(RuntimeError, 'boom')
+      end
+      it '例外を伝播させずトークンだけ除去して返す' do
+        expect { result }.not_to raise_error
+        expect(result).not_to match CopyTunerClient::Copyray::Marker::SCAN_REGEXP
+        expect(result).to include('<p>Hello</p>')
+      end
+      it 'skipped が true を返す（属性付与できなかった）' do
+        expect(skipped).to be true
+      end
+      it 'logger.warn で例外内容を記録する' do
+        logger = double('logger')
+        allow(CopyTunerClient.configuration).to receive(:logger).and_return(logger)
+        expect(logger).to receive(:warn).with(/Rewriter failed.*RuntimeError.*boom/)
+        result
+      end
+      it 'logger が nil でもフォールバックが落ちない' do
+        allow(CopyTunerClient.configuration).to receive(:logger).and_return(nil)
+        expect { result }.not_to raise_error
+        expect(result).not_to match CopyTunerClient::Copyray::Marker::SCAN_REGEXP
+      end
+    end
+    context '出力にマーカートークンが一切残らない' do
+      let(:html) do
+        "<html><head><title>#{marker('t')}T</title></head>" \
+          "<body><input placeholder=\"#{marker('p')}x\"><p>#{marker('a')}A<a>#{marker('b')}B</a></p></body></html>"
+      end
+      it 'シリアライズ後の出力にトークンが残っていない' do
+        expect(result).not_to match CopyTunerClient::Copyray::Marker::SCAN_REGEXP
+      end
+    end
+  end
+end

data/spec/copy_tuner_client/copyray_middleware_spec.rb ADDED Viewed

@@ -0,0 +1,88 @@
+require 'spec_helper'
+require 'copy_tuner_client/copyray_middleware'
+require 'copy_tuner_client/copyray/marker'
+require 'copy_tuner_client/translation_log'
+describe CopyTunerClient::CopyrayMiddleware do
+  def marker(key)
+    CopyTunerClient::Copyray::Marker.encode(key)
+  end
+  let(:headers) { { 'Content-Type' => 'text/html' } }
+  let(:app) { ->(_env) { [status, headers, [body]] } }
+  let(:status) { 200 }
+  subject(:middleware) { described_class.new(app) }
+  before do
+    CopyTunerClient.configure do |configuration|
+      configuration.project_id = 1
+      configuration.client = FakeClient.new
+    end
+    # NOTE: JS 挿入は Rails の ActionController::Base.helpers に依存するため、
+    # Rewriter の効果だけを検証できるよう no-op にスタブする。
+    allow(middleware).to receive(:append_js) { |html, *| html }
+  end
+  context 'マーカートークンを含む HTML レスポンスのとき' do
+    let(:body) { "<html><body><p>#{marker('a.b')}Hello</p></body></html>" }
+    it 'マーカーを data-copyray-key 属性に書き換え、トークンを除去する' do
+      _status, _headers, response = middleware.call({})
+      result = response.join
+      expect(result).to include('data-copyray-key="a.b"')
+      expect(result).not_to match CopyTunerClient::Copyray::Marker::SCAN_REGEXP
+    end
+    it '書き換え後のボディから Content-Length を再計算する' do
+      _status, out_headers, response = middleware.call({})
+      expect(out_headers['Content-Length']).to eq response.join.bytesize.to_s
+    end
+  end
+  context 'HTML 以外のレスポンスのとき' do
+    let(:headers) { { 'Content-Type' => 'application/json' } }
+    let(:body) { "{\"x\":\"#{marker('a.b')}\"}" }
+    it '書き換えずにそのまま通過させる' do
+      _status, _headers, response = middleware.call({})
+      expect(response.join).to eq body
+    end
+  end
+  describe '#append_js' do
+    # NOTE: append_js は private かつ Rails の view ヘルパー（javascript_tag 等）に依存する。
+    # トップレベルの no-op スタブを外して実体を呼び、ヘルパーは渡された script 本文をそのまま
+    # 返す最小フェイクに差し替えて、window.CopyTuner に keysSkipped が埋まることだけ検証する。
+    subject(:script) { middleware.__send__(:append_js, '<html><body></body></html>', nil, skipped: skipped) }
+    let(:fake_helpers) do
+      Class.new {
+        def javascript_tag(content, **_opts) = content
+        def javascript_include_tag(*, **) = ''
+      }.new
+    end
+    before do
+      allow(middleware).to receive(:append_js).and_call_original
+      allow(middleware).to receive(:helpers).and_return(fake_helpers)
+    end
+    context 'skipped が true のとき' do
+      let(:skipped) { true }
+      it 'window.CopyTuner に keysSkipped: true を出力する' do
+        expect(script).to include('keysSkipped: true')
+      end
+    end
+    context 'skipped が false のとき' do
+      let(:skipped) { false }
+      it 'window.CopyTuner に keysSkipped: false を出力する' do
+        expect(script).to include('keysSkipped: false')
+      end
+    end
+  end
+end

data/spec/copy_tuner_client/copyray_spec.rb CHANGED Viewed

@@ -7,62 +7,45 @@ describe CopyTunerClient::Copyray do
     let(:key) { 'en.test.key' }
-    shared_examples 'Not escaped' do
-      it { is_expected.to be_html_safe }
-      it { is_expected.to eq "<!--COPYRAY #{key}--><b>Hello</b>" }
-    end
-    context 'html_escape option is false' do
-      before do
-        CopyTunerClient.configure do |configuration|
-          configuration.html_escape = false
-          configuration.client = FakeClient.new
-        end
+    before do
+      CopyTunerClient.configure do |configuration|
+        configuration.project_id = 1
+        configuration.client = FakeClient.new
       end
+    end
-      context 'string not marked as html safe' do
-        let(:source) { FakeHtmlSafeString.new('<b>Hello</b>') }
+    context 'when the source is html_safe (e.g. _html key)' do
+      let(:source) { FakeHtmlSafeString.new('<b>Hello</b>').html_safe }
-        it_behaves_like 'Not escaped'
+      it 'keeps the html_safe flag so the translation is not re-escaped' do
+        is_expected.to be_html_safe
       end
-      context 'string marked as html safe' do
-        let(:source) { FakeHtmlSafeString.new('<b>Hello</b>').html_safe }
-        it_behaves_like 'Not escaped'
+      it 'prepends the visible marker token without escaping' do
+        is_expected.to eq '⟦CT:en.test.key⟧<b>Hello</b>'
       end
     end
-    context 'html_escape option is true' do
-      before do
-        CopyTunerClient.configure do |configuration|
-          configuration.html_escape = true
-          configuration.client = FakeClient.new
-        end
-      end
-      context 'string not marked as html safe' do
-        let(:source) { FakeHtmlSafeString.new('<b>Hello</b>') }
+    context 'when the source is plain text (not html_safe)' do
+      let(:source) { FakeHtmlSafeString.new('Hello & <World>') }
-        it { is_expected.to be_html_safe }
-        it { is_expected.to eq "<!--COPYRAY #{key}-->&lt;b&gt;Hello&lt;/b&gt;" }
-      end
-      context 'string marked as html safe' do
-        let(:source) { FakeHtmlSafeString.new('<b>Hello</b>').html_safe }
-        it_behaves_like 'Not escaped'
+      it 'prepends the marker but keeps the source non html_safe so ActionView still escapes the body' do
+        is_expected.to eq '⟦CT:en.test.key⟧Hello & <World>'
+        is_expected.not_to be_html_safe
       end
     end
     context 'when the key matches local_first_key_regexp' do
-      let(:source) { 'Hello' }
       let(:key) { 'views.foo' }
       before { CopyTunerClient.configuration.local_first_key_regexp = /\Aviews\./ }
-      it 'does not inject the overlay marker' do
-        is_expected.to eq 'Hello'
+      it 'does not inject the marker into a plain source' do
+        expect(CopyTunerClient::Copyray.augment_template('Hello', key)).to eq 'Hello'
+      end
+      it 'does not inject the marker into an html_safe source' do
+        expect(CopyTunerClient::Copyray.augment_template('Hello'.html_safe, key)).to eq 'Hello'
       end
     end
   end

data/spec/copy_tuner_client/helper_extension_spec.rb CHANGED Viewed

@@ -26,8 +26,11 @@ describe CopyTunerClient::HelperExtension do
   module KeywordArgumentsHelper
     attr_writer :controller
+    # NOTE: ActionView の TranslationHelper を模し、.html/_html キーのみ html_safe な訳文を返す。
+    # マーカーは平文・html_safe どちらにも注入されるが、html_safe フラグの引き継ぎを検証できるよう両方返し分ける。
     def translate(key, **options)
-      "Hello, #{options[:name]}"
+      source = "Hello, #{options[:name]}"
+      key.to_s.end_with?('.html', '_html') ? source.html_safe : source
     end
     def controller
@@ -54,7 +57,17 @@ describe CopyTunerClient::HelperExtension do
   end
   it 'works with keyword argument method' do
-    expect(view.translate('some.key', name: 'World')).to eq '<!--COPYRAY some.key-->Hello, World'
+    expect(view.translate('some.key_html', name: 'World')).to eq '⟦CT:some.key_html⟧Hello, World'
+  end
+  it 'injects the marker into a plain (non html_safe) translation, keeping it non html_safe' do
+    result = view.translate('some.key', name: 'World')
+    expect(result).to eq '⟦CT:some.key⟧Hello, World'
+    expect(result).not_to be_html_safe
+  end
+  it 'keeps the html_safe flag for an _html key so the body is not re-escaped' do
+    expect(view.translate('some.key_html', name: 'World')).to be_html_safe
   end
   it 'does not inject the overlay marker for a local_first key' do
@@ -62,9 +75,9 @@ describe CopyTunerClient::HelperExtension do
     expect(view.translate('views.foo', name: 'World')).to eq 'Hello, World'
   end
-  context 'injection guard by request format' do
-    it 'injects the marker when request.format is html' do
-      expect(view.translate('some.key', name: 'World')).to eq '<!--COPYRAY some.key-->Hello, World'
+  context 'injection guard by rendering context' do
+    it 'injects the marker when request.format is :html' do
+      expect(view.translate('some.key', name: 'World')).to eq '⟦CT:some.key⟧Hello, World'
     end
     %i[json text csv pdf].each do |format|

data/spec/copy_tuner_client/i18n_backend_spec.rb CHANGED Viewed

@@ -138,12 +138,20 @@ describe 'CopyTunerClient::I18nBackend' do
     expect(cache['en.test.key']).to eq 'default %{interpolate}'
   end
+  # NOTE: backend は html_safe 化をしない（.html/_html キーの html_safe 化は ActionView の
+  # TranslationHelper が担う）。html_escape 設定の有無に関わらず素の content を返す i18n 標準準拠の挙動。
   it 'html safeを付与しないこと' do
     cache['en.test.key'] = FakeHtmlSafeString.new("Hello")
     backend = build_backend
     expect(backend.translate('en', 'test.key')).to_not be_html_safe
   end
+  it 'html_safe な値を渡しても backend が独自に html_safe 化しないこと' do
+    cache['en.test.key'] = FakeHtmlSafeString.new("Hello").html_safe
+    backend = build_backend
+    expect(backend.translate('en', 'test.key')).to be_html_safe
+  end
   it 'defaultが配列の場合に順に検索できること' do
     cache['en.key.one'] = "Expected"
     backend = build_backend
@@ -151,21 +159,6 @@ describe 'CopyTunerClient::I18nBackend' do
       to eq('Expected')
   end
-  context 'html_escapeオプションがtrueの場合' do
-    before do
-      CopyTunerClient.configure do |configuration|
-        configuration.html_escape = true
-        configuration.client = FakeClient.new
-      end
-    end
-    it 'html safeを付与しないこと' do
-      cache['en.test.key'] = FakeHtmlSafeString.new("Hello")
-      backend = build_backend
-      expect(backend.translate('en', 'test.key')).not_to be_html_safe
-    end
-  end
   context '非文字列キーの場合' do
     it 'キャッシュに登録されないこと' do
       expect { subject.translate('en', {}) }.to throw_symbol(:exception)

data/spec/support/client_spec_helpers.rb CHANGED Viewed

@@ -4,7 +4,6 @@ module ClientSpecHelpers
     CopyTunerClient.configure(false) do |config|
       config.api_key = 'abc123'
       config.s3_host = 'copy-tuner.com'
-      config.html_escape = true
     end
   end
 end

data/src/copyray-overlay.ts ADDED Viewed

@@ -0,0 +1,125 @@
+import { OVERLAY_STYLES } from './styles'
+import { computeBoundingBox } from './util'
+type OpenCallback = (key: string) => void
+type Blurb = {
+  keys: string[]
+  element: Element
+}
+const findBlurbs = (): Blurb[] =>
+  Array.from(document.querySelectorAll('[data-copyray-key]')).map((element) => ({
+    // 1 要素に複数キーがカンマ区切りで入りうる（同一テキストノードに複数訳文が連結された場合）
+    keys: (element.getAttribute('data-copyray-key') ?? '').split(',').filter(Boolean),
+    element,
+  }))
+// オーバーレイ背景・翻訳要素のハイライト枠（specimen）・トグルボタンをまとめて Shadow DOM 内に描画する。
+export class CopyrayOverlay extends HTMLElement {
+  #onOpen: OpenCallback = () => {}
+  #onToggle: () => void = () => {}
+  #backdrop: HTMLDivElement
+  #specimens: HTMLDivElement
+  #toggleButton: HTMLAnchorElement
+  constructor() {
+    super()
+    const shadow = this.attachShadow({ mode: 'open' })
+    const style = document.createElement('style')
+    style.textContent = OVERLAY_STYLES
+    shadow.append(style)
+    this.#backdrop = document.createElement('div')
+    this.#backdrop.classList.add('backdrop')
+    this.#backdrop.addEventListener('click', () => this.hide())
+    // specimen をページ座標基準で absolute 配置するコンテナ
+    this.#specimens = document.createElement('div')
+    this.#specimens.classList.add('specimens')
+    this.#toggleButton = document.createElement('a')
+    this.#toggleButton.classList.add('toggle-button')
+    this.#toggleButton.textContent = 'Open CopyTuner'
+    // 旧実装ではトグルボタンが overlay と bar の両方を表示していた。show() ではなく onToggle 経由で表示する。
+    this.#toggleButton.addEventListener('click', () => this.#onToggle())
+    shadow.append(this.#backdrop, this.#specimens, this.#toggleButton)
+    // 初期は非表示（背景と specimen を隠す）。トグルボタンは常時表示のため :host([hidden]) は使わず個別制御する。
+    this.hide()
+  }
+  set onOpen(callback: OpenCallback) {
+    this.#onOpen = callback
+  }
+  set onToggle(callback: () => void) {
+    this.#onToggle = callback
+  }
+  get isShowing(): boolean {
+    return !this.#backdrop.hidden
+  }
+  show() {
+    this.reset()
+    this.#backdrop.hidden = false
+    for (const { element, keys } of findBlurbs()) {
+      const box = this.makeBox(element, keys)
+      if (box) {
+        this.#specimens.append(box)
+      }
+    }
+  }
+  hide() {
+    this.reset()
+    this.#backdrop.hidden = true
+  }
+  reset() {
+    this.#specimens.replaceChildren()
+  }
+  private makeBox(element: Element, keys: string[]): HTMLDivElement | null {
+    const bounds = computeBoundingBox(element)
+    if (bounds === null) return null
+    const box = document.createElement('div')
+    box.classList.add('specimen')
+    box.style.left = `${bounds.left}px`
+    box.style.top = `${bounds.top}px`
+    box.style.width = `${bounds.width}px`
+    box.style.height = `${bounds.height}px`
+    const { position, top, left } = getComputedStyle(element)
+    if (position === 'fixed') {
+      box.style.position = 'fixed'
+      box.style.top = top
+      box.style.left = left
+    }
+    // box 全体のクリックは先頭キーを開く（広いクリック領域を維持）。複数キー時は各ラベルから個別に開ける
+    box.addEventListener('click', () => this.#onOpen(keys[0]))
+    for (const key of keys) {
+      box.append(this.makeLabel(key))
+    }
+    return box
+  }
+  private makeLabel(key: string): HTMLDivElement {
+    const label = document.createElement('div')
+    label.classList.add('specimen-handle')
+    label.textContent = key
+    // ラベルのクリックはそのキーを開く。box への伝播を止めて先頭キーとの二重発火を防ぐ
+    label.addEventListener('click', (event) => {
+      event.stopPropagation()
+      this.#onOpen(key)
+    })
+    return label
+  }
+}