Skip to content

Add first-run onboarding flow for new installs - #453

Merged
ujiro99 merged 28 commits into
mainfrom
feat/onboarding-flow-refinements
Sep 7, 2026
Merged

ujiro99 merged 28 commits into
mainfrom
feat/onboarding-flow-refinements

Conversation

@ujiro99

@ujiro99 ujiro99 commented Aug 24, 2026

Copy link
Copy Markdown
Owner

Summary

  • New-install onboarding flow (Steps 1-4: Search, AiPrompt, LinkPreview, Customize) guiding users through the select → command → result pattern
  • Onboarding tab close now routes through the background script (BgCommand.closeTab) so hasShownOnboarding is persisted before the tab closes
  • All 14 locale messages.json files updated with the onboarding strings

Redesign pass

  • Shared OnboardingLayout (brand header, 4-segment progress + counter, fixed-position Skip) replaces per-step chrome and the old per-step spotlight overlay with a constant vignette so nothing shifts between screens
  • Persistent select → command → result OnboardingRail reinforces the mental model across Steps 1-3 and the value-shown payoff screens
  • Step1/2's sample text now demonstrates the drag-to-select gesture at runtime (useSelectionDemo, measured via Range.getClientRects() so it's correct across all 14 locales' line-wrapping, not hardcoded pixel keyframes)
  • Actionable buttons (solid fill) are now visually distinct from decorative/state elements (tinted fill) throughout
  • Step4 shows both the real settings-panel commands and Command Hub suggestions side by side (no outbound link mid-onboarding); Step5 ends with a canvas-confetti celebration and closes to "try it now" as the primary action
  • Onboarding CSS moved off Onboarding.module.css onto Tailwind (tailwind.config.js keyframes + utility classes)
  • New e2e-only screenshot tool (e2e/onboarding-shots.spec.ts, CAPTURE=1 yarn test:e2e onboarding-shots) using a ?step=&phase= dev-only override in useOnboardingState to capture every step/phase across locales for design review

Closes #452

Test plan

  • tsc --noEmit passes
  • yarn lint passes (0 errors)
  • yarn test:run passes (1057 tests, including new onboardingProgress / useSelectionDemo coverage)
  • yarn build / yarn build:e2e pass
  • Captured and visually reviewed screenshots of every step/phase in ja / en-US / de
  • Manually verify the onboarding tab opens on first install, walk through Steps 1-4, and confirm Skip/Close both close the tab without reopening onboarding on next load

🤖 Generated with Claude Code

https://claude.ai/code/session_01WaFfYLgE9pcwo3wSwEeG8D

ujiro99 and others added 2 commits August 24, 2026 19:42
Guides new users through the popup menu, AI prompt command, and link
preview right after install via a dedicated onboarding tab, with a
final Customize/Complete screen that persists hasShownOnboarding so
it only runs once.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019NHfjgYsFbd7tPbEdQSg4p
…d Hub link

Add a slow-blink hint on Step1 while waiting for the user to return from
the search command's tab, short pattern captions on Steps 1-3 to reinforce
the select-command-result mental model, and a Command Hub link on Step4.
Also route onboarding tab close through the background script (closeTab)
so the settings write completes before the tab closes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017QRxn2pRzMCWvf9nK2w7Kq
@codecov

codecov Bot commented Aug 24, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 21.58662% with 1453 lines in your changes missing coverage. Please review.
✅ Project coverage is 44.38%. Comparing base (7e0fb4d) to head (6f29e1d).

Files with missing lines Patch % Lines
.../components/onboarding/steps/StepSearchCommand.tsx 0.00% 224 Missing ⚠️
...rc/components/onboarding/steps/StepLinkPreview.tsx 0.00% 188 Missing ⚠️
...omponents/onboarding/steps/StepAiPromptCommand.tsx 0.00% 183 Missing ⚠️
...on/src/components/onboarding/useOnboardingState.ts 0.00% 125 Missing ⚠️
...nsion/src/components/onboarding/OnboardingRail.tsx 0.00% 72 Missing ⚠️
.../src/components/onboarding/steps/StepCustomize.tsx 0.00% 71 Missing ⚠️
...n/src/components/onboarding/steps/StepComplete.tsx 0.00% 63 Missing ⚠️
...src/components/onboarding/OnboardingTargetText.tsx 0.00% 55 Missing ⚠️
packages/extension/tailwind.config.js 0.00% 54 Missing ⚠️
...ion/src/components/onboarding/OnboardingLayout.tsx 2.00% 49 Missing ⚠️
... and 24 more
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #453      +/-   ##
==========================================
- Coverage   46.57%   44.38%   -2.20%     
==========================================
  Files         239      267      +28     
  Lines       25710    27488    +1778     
  Branches     2053     2145      +92     
==========================================
+ Hits        11975    12200     +225     
- Misses      13735    15288    +1553     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@claude

claude Bot commented Aug 24, 2026

Copy link
Copy Markdown

コードレビュー

新規インストール時のオンボーディングフロー追加、お疲れ様です。全体的にステップの状態管理(OnboardingStep / StepPhase)やIPC経由のタブクローズなど、既存の設計パターンを踏襲していて読みやすい実装だと思います。特に useOnboardingState.tsskip() が「設定の永続化を待ってからタブを閉じる」ことを明示的にコメントで説明している点は良い設計判断です。

以下、気になった点を挙げます。

1. StepComplete の Close ボタンで hasShownOnboarding の保存を待たずにタブを閉じてしまう(バグの疑い)

  • packages/extension/src/components/onboarding/steps/StepComplete.tsx:17-19
    useEffect(() => { complete() }, [complete])complete() を呼んでいますが、await していません。
  • packages/extension/src/components/onboarding/useOnboardingState.ts:79-84
    const complete = useCallback(() => {
      sendOnboardingEvent(ANALYTICS_EVENTS.ONBOARDING_COMPLETE, {...})
      markFinished()  // ← await していない
    }, [markFinished])
    markFinished() 内部の Settings.update("hasShownOnboarding", () => true)useOnboardingState.ts:66)は chrome.storage.sync への書き込みで非同期です。
  • StepComplete.tsx:38 の Close ボタンは onClick={() => closeOnboardingTab()} で、complete() の完了を待たずに即座にタブクローズのIPC(BgCommand.closeTab)を送ります。

つまり、skip()useOnboardingState.ts:73-77)では

const skip = useCallback(async () => {
  sendOnboardingEvent(ANALYTICS_EVENTS.ONBOARDING_SKIP, { step })
  await markFinished()
  await closeOnboardingTab()
}, [step, markFinished])

と明示的に「設定の書き込み完了を待ってからタブを閉じる」設計にしているにもかかわらず、StepComplete の Close ボタンだけはこのパターンから外れています。ユーザーがStepComplete表示直後に素早くCloseを押すと、hasShownOnboarding=true の書き込みが完了する前にタブが閉じられる可能性があります(chrome.storage.sync への書き込みはデバウンス処理もあり packages/extension/src/services/storage/index.ts:12,35-46 で10msの遅延が入っています)。

対応案としては、StepComplete の Close ボタンも skip() と同様に await complete() してから closeOnboardingTab() を呼ぶ形に統一するのが良さそうです。

2. hasShownOnboarding がどこからも読み取られていない

  • chrome.runtime.onInstalledpackages/extension/src/background_script.ts:468-475)でオンボーディングタブを開く条件は details.reason === chrome.runtime.OnInstalledReason.INSTALL のみで、hasShownOnboarding の値は一切参照されていません。
  • リポジトリ全体を検索しても、hasShownOnboarding を読み取って何かを分岐させている箇所が見当たりませんでした(書き込みのみ)。
  • USER_STATSchrome.storage.syncpackages/extension/src/services/storage/index.ts:56-62, 96-99)に保存されるため、同じGoogleアカウントで同期している状態で再インストールした場合などに意味を持ちそうですが、onInstalled 内で先に Settings.reset()background_script.ts:472)が呼ばれてデフォルト値(hasShownOnboarding: false)に戻ってしまうため、結局オンボーディングは毎回表示されるように見えます。

PR概要に「hasShownOnboarding を永続化するので一度しか実行されない」とありますが、現状のコードではこのフラグが実質的に「書くだけで読まれない」状態になっているようです。将来的な用途(オプション画面からの再表示制御など)のための先行実装であれば問題ありませんが、意図通りかどうか確認をお願いします。

3. テストカバレッジ

  • packages/extension/src/components/onboarding/ 配下(useOnboardingState.tsOnboardingPage.tsxsteps/*.tsx など、今回追加された約10ファイル)に対する単体テストが一つも見当たりません。特に useOnboardingState.ts はステップ遷移・スキップ・完了処理などロジックが集中しているので、優先的にテストを追加する価値がありそうです。
  • background_script.ts:73-84 で新規追加された closeTab ハンドラ(レスポンスをタブ削除の前に返す、という順序が重要な実装)についても、background_script.test.ts 内に専用のテストケースが見当たりませんでした。既存の IN-01IN-04 同様のテストを追加しておくと、将来のリファクタ時に順序が壊れるのを防げます。

4. その他(軽微)

  • StepSearchCommand.tsx:30commands?.find((c) => c.title === "Google") はタイトル文字列でのマッチングです。defaultSettings.ts を確認したところ、全14ロケールで "Google" という同一タイトルの検索コマンドが含まれていることを確認できたので現状は問題ありませんが、将来ユーザーがコマンドタイトルを変更した場合や、タイトルの表記が変わった場合には吹き出し(callout)の対象要素が見つからなくなります(コマンド実行自体の検知は COMMAND_TYPE.SEARCH ベースなので、フローが完全に止まるわけではなく演出上の見た目のみの影響です)。

良かった点

  • 全14ロケールの messages.jsononboarding_* キーが過不足なく追加されていることを確認しました(各ロケール27キーで一致)。
  • executor.ts / useDetectLinkCommand.ts からの dispatchCommandExecuted 発火は executor.test.ts でテストされており、オンボーディングのイベント検知の土台部分はカバーされています。
  • コメントで設計判断の理由(なぜ window.close() ではなく背景スクリプト経由か、なぜ response をタブ削除前に返すか等)が丁寧に書かれており、今後のメンテナンス性が高いです。

🤖 このレビューはClaude Codeによって自動生成されました。

ujiro99 and others added 2 commits August 25, 2026 13:09
…orcement

Replace the per-step spotlight overlay with a constant vignette, add a
persistent select-command-result progress rail, demonstrate the drag-to-
select gesture at runtime (locale-proof via Range.getClientRects), and
distinguish actionable buttons from decorative state with fill/tint. Move
CSS off Onboarding.module.css onto Tailwind, and add a canvas-confetti
celebration on the completion screen.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WaFfYLgE9pcwo3wSwEeG8D
@claude

claude Bot commented Aug 26, 2026

Copy link
Copy Markdown

コードレビュー: #453 初回インストール向けオンボーディングフロー追加

大規模な機能追加(新規ファイル約30個、全14ロケールのmessages.json更新)ですが、既存パターン(BgCommandIpcuseSettingsSender型など)に沿った実装になっており、全体的に品質は高いと感じました。テストカバレッジも新規ロジック(onboardingProgress, useSelectionDemo, background_scriptのIN-03/04など)にきちんと付与されています。細かい指摘・確認事項を以下にまとめます。

1. StepPhase.WAIT_SELECTION が未使用 (軽微)

packages/extension/src/types/onboarding.ts:17

WAIT_SELECTION = "wait_selection",

リポジトリ全体を検索しても、この値を参照している箇所が定義以外に見当たりませんでした。将来のステップ追加を見越した定義であれば問題ありませんが、現時点では未使用コードになっているので、使う予定がなければ削除、使う予定があればコメントでその旨を残すと良さそうです。

2. Step*Commandのコールアウト対象要素をポーリングで探索している (StepSearchCommand.tsx:53-68, StepAiPromptCommand.tsx:47-63)

const find = () => {
  if (cancelled) return
  const elm = document.querySelector(`[data-command-id="${...}"]`)
  if (elm) {
    setCalloutElm(elm)
  } else {
    window.setTimeout(find, 150)
  }
}

ポップアップメニューが何らかの理由(例: コマンド無効化、DOM未マウント)で永久に描画されないケースだと、cancelledがtrueになるまで(=phaseが変わるかアンマウントされるまで)150ms間隔でポーリングし続けます。実害は小さいですが、MutationObserverを使う方が「ポーリングし続ける」よりも堅牢かもしれません(必須の修正ではなく将来的な改善案です)。

3. StepSearchCommand.tsx:15 コマンドをタイトル文字列で検索

const googleCommand = commands?.find((c) => c.title === "Google")

defaultSettings.tsを確認したところ、CMD_GOOGLEtitleは全ロケール共通で"Google"固定(ローカライズされていない)なので、現状は問題なく動作します。ただし、将来Googleコマンドのタイトルがローカライズされたり、コマンドが並び替え/複製されたりした場合に壊れやすい検索方法です。onboardingCommand.tsのAIプロンプトコマンドのように、Google検索コマンド側にも固定IDを振ってidで検索する方が堅牢だと思います(テストで担保されているわけではないので気づきにくい箇所です)。

4. StepCompletecomplete()がawaitされていない (StepComplete.tsx:22-24, useOnboardingState.ts:79-84)

useEffect(() => {
  complete()
}, [complete])
const complete = useCallback(() => {
  sendOnboardingEvent(ANALYTICS_EVENTS.ONBOARDING_COMPLETE, {...})
  markFinished()  // Settings.update(...) は非同期だが await されない
}, [markFinished])

skip()ではhasShownOnboardingの書き込みをcloseOnboardingTab()呼び出し前に明示的にawaitしていますが(コメントにもその意図が書かれています)、complete()側は書き込み完了を待たずに終わります。実際にタブを閉じるのはユーザーが「閉じて使ってみる」ボタンを押した時点なので通常は書き込みが間に合いますが、もしユーザーが完了画面表示直後にタブをネイティブに閉じる(ブラウザのタブ×ボタンなど、closeOnboardingTab()を経由しない操作)と、hasShownOnboardingの永続化が間に合わない可能性があります。実害は小さい(次回以降オンボーディングが自動再表示されるトリガーがOnInstalledReason.INSTALLのみのため)ですが、skipとの非対称性は意図的か確認したいところです。

5. OnboardingConfettiのreduced-motion判定について (OnboardingConfetti.tsx)

disableForReducedMotionオプションの代わりに独自のusePrefersReducedMotionを使っている設計判断とその理由(matchMedia('(prefers-reduced-motion)')が値なしだと常にtrueになる問題を回避)がコメントで明確に説明されており、良い実装だと思います。MV3のCSP制約に対するuseWorker: falseの説明も含め、この辺りのコメントは非常に丁寧で読みやすかったです。

6. i18nメッセージのdescriptionフィールドがenロケールにのみ存在

en/messages.jsonは新規追加の全キーにdescriptionが付与されていますが、他13ロケールには付与されていません。Chrome拡張のmessages.jsonの仕様上、翻訳作業用のメタデータなので動作への影響はありませんが、既存の構造と一致しているか(他の既存キーもenのみdescriptionを持つ運用なのか)念のため確認だけしておくと良さそうです。おそらく既存の運用ルールに沿っているだけだと思います。

良かった点

  • background_script.tscloseTab実装(response()chrome.tabs.remove()より先に呼ぶことで、閉じられるタブ自身がレスポンスを待っている競合状態を回避する設計)とそのコメントは明快で、既存のgetTabId/getActiveTabIdパターンとも整合しています。
  • useSelectionDemo.tsbuildKeyframesが実測(Range.getClientRects())ベースでロケール非依存になっている点、およびそのロジックが純粋関数として切り出されテスト(useSelectionDemo.test.ts)されている点は良い設計です。
  • onboardingEvents.tsによるイベント経由の疎結合設計(executor.ts/useDetectLinkCommand.tsはオンボーディングの存在を知らなくて良い)は、コア機能への影響を最小限に抑えた良いアプローチです。
  • hasShownOnboardingのマイグレーション(ImportExport.tsx, enhancedSettings.ts, settings.ts, storage/index.ts)が一通りのレイヤーで漏れなく更新されています。

セキュリティ面では、dangerouslySetInnerHTMLやユーザー入力の直接埋め込みは見当たらず、問題ありませんでした。パフォーマンス面も、ResizeObserverRange.getClientRects()の利用は妥当な範囲で、大きな懸念はありません。

以上、大きな問題は見当たらず、上記の軽微な点をご検討いただければと思います。

Moves the context definition out of Popup.tsx and into a dedicated
hooks/usePopupContext.tsx, matching the pattern used by the other
context providers, and switches consumers to the usePopupContext()
hook instead of importing the raw context from Popup.tsx.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@ujiro99 ujiro99 changed the title Add first-run onboarding flow for new installs [WIP] Add first-run onboarding flow for new installs Aug 26, 2026
ujiro99 and others added 12 commits August 31, 2026 17:21
Shorten onboarding intro copy, add a return-hint callout, translate the
changes into every supported locale, give the callout bubble a gentle
float animation, replace hardcoded #082f49 with the equivalent
sky-950 token, and suppress the regular Tooltip while onboarding is
active or the popup is mid-transition.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…payoff

Steps 1-3 each switched their whole render tree to a separate
<OnboardingValueShown> once the payoff phase was reached, mounting a
second, independent OnboardingRail and restarting its beat animation
instead of carrying it through from the first "select" beat. Unify
each step's JSX into a single return so the rail (and its wrapping
fade-in) stays mounted at the same position across every phase, with
only its activeBeat prop changing - OnboardingValueShown is now dead
code and removed.

Also folds in a few small, related touch-ups already in progress on
this branch: an IPC broadcast fix so onboarding tabs receive
sendAllTab commands, a return-hint copy tweak, and minor button/timing
adjustments.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Propagates four ja/messages.json wording changes (step1 return-hint
clarifying the popup window auto-closes, step2 target/callout text,
and a trimmed step3 explain string) to the other 13 locales.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Simplify onboarding step phase checks into named booleans, position the
onboarding menu item toward the screen edge during onboarding, skip
analytics for commands run from extension pages, add a completion emoji
to the search step's value message, and drop the trailing punctuation
from the search step's value message across all locales.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
… copy

Give the AiPrompt (Step2) and Link Preview (Step3) steps their own
WAIT_RETURN phase - Step2 shows a brief in-flight message before the
value message, and Step3 detects the user switching back from the
preview popup/tab via visibilitychange/focus, matching Step1's pattern.
Step3's Shift+click hint now renders as an OnboardingCallout targeting
the sample link itself, like every other "do this next" hint, instead
of a static keycap graphic.

Also drops the trailing punctuation from the step2/step3 value messages
and adds the new step2WaitReturn/step3ReturnHint/step3Callout copy to
all 14 locales, removing the now-unused clickKeycap key.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…fetti timing

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Group each step's OnboardingFadeIn/OnboardingCallout delays into a
delays object keyed directly by StepPhase, and thread OnboardingTargetText's
callout delay through the same structure instead of hardcoding it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…cking per step

Rename ONBOARDING_FIRST_SELECTION/FIRST_VALUE to ONBOARDING_TEXT_SELECTION/
VALUE_REACHED, and fire VALUE_REACHED automatically per-step whenever that
step's phase reaches VALUE_SHOWN (with a step param) instead of only from
StepSearchCommand. Also guard complete() before sending ONBOARDING_COMPLETE,
since StrictMode's dev-only double effect invocation was sending it twice.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@ujiro99

ujiro99 commented Sep 4, 2026

Copy link
Copy Markdown
Owner Author
  • リンクプレビューのリンク先をかえる
  • 終了時間を計測して、イベントのパラメータに追加する
  • オンボーディング終了後、コマンド実行のイベントが送信されること
  • オンボーディング中、リンクコマンドのイベントは送らないようにし、検索コマンドと一貫性をもたせる

ujiro99 and others added 8 commits September 6, 2026 12:50
…guages

Change step3 value sub-message to emphasize returning quickly after
finding info, render completeBody as multiline, and update the
step3 link-preview sample link. Localize both message changes across
all supported languages.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Avoid sending the link_preview analytics event when running inside
the extension's own onboarding page, since that traffic doesn't
represent real user link-preview usage.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Fixes several correctness issues found while reviewing the onboarding
flow branch: unfiltered command-executed events on the search step,
an unchecked close-tab response leaving the onboarding tab open, an
uncleared setPhase timer that could fire after teardown, and an
analytics-suppression guard that blocked events on any extension page
instead of just onboarding. Also normalizes the GA4 step param to a
stable string label, renames completion_time to completion_time_sec,
dedupes the per-step PhaseDelays type, and fixes two stale comments.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…me title

Moves the per-locale title/prompt text for the onboarding AiPrompt
command out of defaultSettings.ts and into onboardingCommand.ts, so
the localized content lives alongside the command factory it belongs
to. Also extracts INSERT/InsertSymbol/toInsertTemplate into their own
insertSymbols.ts module so onboardingCommand.ts can reuse the
{{SelectedText}} placeholder symbol without pulling in pageAction's
listener/ipc side effects, and renames the command title across all
locales to reflect that it executes a prompt rather than just "asks".

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Production builds hardcoded two CSS filenames when injecting styles
into the content script's Shadow DOM, missing chunks shared with
other entry points (e.g. LinkSelector) that crxjs splits out with
content-hashed names. Inject the real, build-computed file list into
the bundle via a placeholder token instead, so styles no longer break
after `yarn build`.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
manualChunks/assetFileNames only existed to give content_script's CSS
assets fixed, predictable names so content_script.tsx could hardcode
fetch paths to them. That lookup is now dynamic, so let Rollup use its
default per-entry chunking and hashed asset names.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@ujiro99 ujiro99 changed the title [WIP] Add first-run onboarding flow for new installs Add first-run onboarding flow for new installs Sep 6, 2026
@ujiro99
ujiro99 requested a lite review from Copilot September 6, 2026 07:21

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

オンボーディング体験の安定性に直結するタブ対象URLの扱いとPopup位置決めに不具合/不整合があるため。

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

新規インストール時にオンボーディング用タブ(Step 0〜5)を自動表示し、ユーザーに「選択 → コマンド → 結果」の基本体験を短時間で提供するための実装を追加するPRです。拡張機能(packages/extension)側にオンボーディングUI・状態管理・計測・タブクローズ経路を統合し、各ロケール文字列とビルド周り(content_script CSS注入)も合わせて更新しています。

Changes:

  • 初回インストール時にオンボーディングタブを開く導線と、完了/スキップ時の永続化(hasShownOnboarding)・計測イベントを追加
  • オンボーディングUI(Layout/Rail/Callout/各Step/Confetti)と、選択デモ(Range.getClientRects ベース)を実装
  • content_script の CSS 注入方式を「ビルド後に実CSSファイル一覧をバンドルへ注入」する方式へ変更し、ハッシュ変動に強く

概要

  • 目的(Issue #452):初回ユーザーのTTV短縮を狙ったインタラクティブ・オンボーディングを提供
  • 実装は extension 内に閉じており、初回インストール判定は chrome.runtime.onInstalled の INSTALL reason を利用

懸念点

  • オンボーディング中のPopup位置決めが window.screen.width 依存のため、ウィンドウサイズ/複数モニタ環境で画面外配置になり得ます。
  • Ipc.sendAllTab の tabs.query url がオンボーディングURL(クエリ付き)にマッチしないケースがあり得ます(e2e/開発の step override 等)。
  • デザインレビュー用 e2e ツールで headless 指定が矛盾しており、環境によって挙動が不明確です。

改善提案 (type "custom")

  • Popup のオンボーディング時位置は window.innerWidth ベースにし、0以上へクランプして安全に配置する。
  • sendAllTab のオンボーディングURLはワイルドカードを付け、?step=&phase= 等の派生URLも対象にする。
  • onboarding-shots.spec.ts の headless 指定は「headless: false で統一」or「headless: true で統一」のどちらかに寄せる。
File summaries
File Description
yarn.lock canvas-confetti 関連の依存解決を反映
packages/extension/package.json canvas-confetti と型定義を追加
packages/extension/vite.config.ts onboarding entry 追加・content_script CSSファイル注入用 define を追加・ビルド出力設定更新
packages/extension/tailwind.config.js オンボーディング専用キーフレーム/アニメーションを追加
packages/extension/src/types/vite-env.d.ts __CONTENT_SCRIPT_CSS_FILES__ の型定義を追加
packages/extension/src/types/onboarding.ts OnboardingStep/StepPhase を追加
packages/extension/src/types/index.ts UserStats に hasShownOnboarding を追加
packages/extension/src/services/storage/index.ts デフォルトUserStatsに hasShownOnboarding を追加
packages/extension/src/services/settings/settings.ts 設定保存・移行対象に hasShownOnboarding を追加
packages/extension/src/services/settings/settings.test.ts hasShownOnboarding のテスト更新
packages/extension/src/services/settings/enhancedSettings.ts 初期値・マージ対象に hasShownOnboarding を追加
packages/extension/src/services/pageAction/insertSymbols.ts INSERT/テンプレート記号を副作用分離した新モジュールへ移動
packages/extension/src/services/pageAction/index.ts insertSymbols を再export する形へ変更
packages/extension/src/services/pageAction/elementWait.ts 条件評価時の debug ログ追加
packages/extension/src/services/pageAction/dispatcher.ts click 実行時の debug ログ追加
packages/extension/src/services/option/defaultSettings.ts オンボーディング用 AiPrompt コマンドを全ロケールへ追加・空設定に hasShownOnboarding を追加
packages/extension/src/services/option/defaultSettings.test.ts 全ロケールにオンボーディングAiPromptコマンドが含まれることを検証
packages/extension/src/services/ipc.ts sendAllTab の対象にオンボーディングURLを追加
packages/extension/src/services/analytics.ts onboarding 計測イベント名を追加
packages/extension/src/services/analytics.test.ts onboarding 計測イベント名のテスト追加
packages/extension/src/providers/SelectContextProvider.tsx 選択検出の有効/無効を制御できるようにし、Context に setSelectionText を公開
packages/extension/src/hooks/useSelectContext.tsx Context 型に setSelectionText / setDetectSelectionEnabled を追加
packages/extension/src/hooks/usePrefersReducedMotion.ts OSのreduce motionを取得するフックを追加
packages/extension/src/hooks/usePopupContext.tsx Popup 状態の Context を hooks 側へ分離
packages/extension/src/hooks/useDetectLinkCommand.ts オンボーディング用 command executed イベント通知・オンボーディング時は一部分析を抑制
packages/extension/src/hooks/pageAction/usePageActionRunner.ts 受信/登録の debug ログ追加
packages/extension/src/hooks/useSettings.test.tsx hasShownOnboarding のテスト更新
packages/extension/src/components/Tooltip.tsx PopupContext の取得経路変更・オンボーディング/遷移中は非表示
packages/extension/src/components/Popup.tsx PopupContext を hooks 側へ移動・ホバー中は選択検出を停止・オンボーディングフラグを提供
packages/extension/src/components/menu/MenuItem.tsx data-command-id 追加・オンボーディング時のpopup位置調整・Tooltip制御変更
packages/extension/src/components/menu/MenuFolder.tsx PopupContext の取得経路変更
packages/extension/src/components/option/Option.tsx プレビューPopupを SelectContextProvider でラップ
packages/extension/src/components/option/ImportExport.tsx import/export マイグレーションに hasShownOnboarding を反映
packages/extension/src/components/App.tsx SelectContextProvider の props を簡素化し Popup 連携を更新
packages/extension/src/content_script.tsx content_script のCSS注入を __CONTENT_SCRIPT_CSS_FILES__ ベースに変更
packages/extension/src/lib/contentScriptCss.ts CSSファイル一覧注入のためのプレースホルダ定義を追加
packages/extension/src/lib/vite-plugin-manifest.ts ビルド後に content_script CSSファイル一覧をJSへ注入する処理を追加
packages/extension/src/const.ts ONBOARDING の screen と ONBOARDING_PAGE_PATH を追加
packages/extension/src/onboarding_page.html onboarding 用のHTML entry を追加
packages/extension/src/onboarding_page.tsx onboarding の React entry を追加(Sentry/locale設定含む)
packages/extension/src/components/onboarding/OnboardingPage.tsx オンボーディングページのルート(Layout + Step切替 + Popup/LinkSelector)を追加
packages/extension/src/components/onboarding/useOnboardingState.ts step/phase管理、完了フラグ永続化、イベント送信を追加(e2e/dev override対応)
packages/extension/src/components/onboarding/onboardingAnalytics.ts onboardingイベント送信のラッパーを追加(step正規化)
packages/extension/src/components/onboarding/onboardingAnalytics.test.ts onboardingAnalytics のテスト追加
packages/extension/src/components/onboarding/onboardingEvents.ts command executed の window event と onboarding 判定を追加
packages/extension/src/components/onboarding/onboardingProgress.ts ヘッダ進捗(4ステップ)計算を追加
packages/extension/src/components/onboarding/onboardingProgress.test.ts onboardingProgress のテスト追加
packages/extension/src/components/onboarding/OnboardingLayout.tsx 共通レイアウト(ヘッダ進捗/スキップ/ビネット)を追加
packages/extension/src/components/onboarding/OnboardingRail.tsx 「select→command→result」のレールUIを追加
packages/extension/src/components/onboarding/OnboardingCallout.tsx 任意要素に紐づく吹き出しCalloutを追加
packages/extension/src/components/onboarding/OnboardingFadeIn.tsx フェードイン演出用ラッパーを追加
packages/extension/src/components/onboarding/OnboardingConfetti.tsx 完了時のconfetti演出(reduced motion対応・CSP対応)を追加
packages/extension/src/components/onboarding/OnboardingTargetText.tsx ターゲットテキストカード+選択デモ統合を追加
packages/extension/src/components/onboarding/useSelectionDemo.ts Range.getClientRects を使ったドラッグ選択デモ(WAAPI)を追加
packages/extension/src/components/onboarding/useSelectionDemo.test.ts buildKeyframes/useSelectionDemo のテスト追加
packages/extension/src/components/onboarding/textUtils.tsx i18n文字列の \\n<br> に変換するユーティリティを追加
packages/extension/src/components/onboarding/phaseDelays.ts フェーズ別遅延の共通型を追加
packages/extension/src/components/onboarding/onboardingWindow.ts BgCommand.closeTab 経由でオンボーディングタブを閉じる関数を追加
packages/extension/src/components/onboarding/onboardingCommand.ts Step2 用の固定ID AiPrompt コマンド生成を追加(全ロケール対応)
packages/extension/src/components/onboarding/steps/StepIntro.tsx Step0 追加
packages/extension/src/components/onboarding/steps/StepSearchCommand.tsx Step1 追加(Search体験)
packages/extension/src/components/onboarding/steps/StepAiPromptCommand.tsx Step2 追加(AiPrompt体験)
packages/extension/src/components/onboarding/steps/StepLinkPreview.tsx Step3 追加(Link Preview体験)
packages/extension/src/components/onboarding/steps/StepCustomize.tsx Step4 追加(カスタマイズ導線)
packages/extension/src/components/onboarding/steps/StepComplete.tsx Step5 追加(完了・confetti・クローズ)
packages/extension/src/background_script.ts INSTALL時にオンボーディングタブを開く& closeTab コマンド追加
packages/extension/src/background_script.test.ts onInstalled のオンボーディング起動有無テスト追加
packages/extension/src/action/executor.ts onboarding ページ上では分析イベントを抑制し、command executed イベントをdispatch
packages/extension/src/action/executor.test.ts onboardingページ時の分析抑制・イベントdispatch のテスト追加
packages/extension/e2e/onboarding-shots.spec.ts デザインレビュー用のスクリーンショット撮影ツールを追加(CAPTURE=1時のみ)
packages/extension/public/_locales/en/messages.json オンボーディング文言を追加
packages/extension/public/_locales/ja/messages.json オンボーディング文言を追加
packages/extension/public/_locales/de/messages.json オンボーディング文言を追加
packages/extension/public/_locales/es/messages.json オンボーディング文言を追加
packages/extension/public/_locales/fr/messages.json オンボーディング文言を追加
packages/extension/public/_locales/hi/messages.json オンボーディング文言を追加
packages/extension/public/_locales/id/messages.json オンボーディング文言を追加
packages/extension/public/_locales/it/messages.json オンボーディング文言を追加
packages/extension/public/_locales/ko/messages.json オンボーディング文言を追加
packages/extension/public/_locales/ms/messages.json オンボーディング文言を追加
packages/extension/public/_locales/pt_BR/messages.json オンボーディング文言を追加
packages/extension/public/_locales/pt_PT/messages.json オンボーディング文言を追加
packages/extension/public/_locales/ru/messages.json オンボーディング文言を追加
packages/extension/public/_locales/zh_CN/messages.json オンボーディング文言を追加
docs/design/storybook-investigation.md Storybook導入調査メモを追加
Review details
  • Files reviewed: 83/88 changed files
  • Comments generated: 3
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread packages/extension/src/components/menu/MenuItem.tsx
Comment thread packages/extension/src/services/ipc.ts
Comment thread packages/extension/e2e/onboarding-shots.spec.ts
@ujiro99

ujiro99 commented Sep 6, 2026

Copy link
Copy Markdown
Owner Author

@copilot Fix the code for all comments in this review thread.

When a review comment includes a suggested change, apply the suggestion exactly.

Do not make changes beyond what is described in the linked review thread.

Co-authored-by: ujiro99 <677231+ujiro99@users.noreply.github.com>

Copilot AI commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

@copilot Fix the code for all comments in this review thread.

When a review comment includes a suggested change, ...

レビューコメントの3点を修正しました。Popup位置計算をwindow.innerWidth基準かつ0以上にクランプし、オンボーディングURLのタブ検索パターンにクエリ対応のワイルドカードを追加し、e2eの重複したheadless指定を削除しています。コミット: HEAD

ujiro99 and others added 2 commits September 7, 2026 13:20
Instead of passing iconUrl in from the caller, derive it internally from
aiPromptOption.serviceId via ai-services.json, keeping the icon and the
AI service it represents in sync.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@ujiro99
ujiro99 merged commit 7fba6aa into main Sep 7, 2026
3 of 6 checks passed
@ujiro99
ujiro99 deleted the feat/onboarding-flow-refinements branch September 7, 2026 08:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

PRD:初回オンボーディングによるTTV短縮

3 participants