refactor(core): BreadcrumbStore added by Reversean · Pull Request #175 · codex-team/hawk.javascript

Reversean · 2026-03-25T20:42:46Z

Motivation

Part of the broader effort to extract environment-agnostic logic into @hawk.so/core (#151). BreadcrumbManager was a concrete, browser-coupled class living in @hawk.so/javascript — Catcher depended directly on it, making breadcrumb support impossible to share or override in a non-browser runtime.

What changed and why

BreadcrumbStore is an interface extracted into @hawk.so/core. Catcher now depends on that interface rather than the browser implementation. BrowserBreadcrumbStore (the renamed BreadcrumbManager) is the browser-specific implementation that stays in @hawk.so/javascript.

Core defines the contract, concrete catchers wire in the environment-appropriate implementation. A future NodeCatcher can provide its own BreadcrumbStore without inheriting any browser code.

Changes

core: BreadcrumbStore interface added and exported
javascript: BreadcrumbManager renamed to BrowserBreadcrumbStore, now implements BreadcrumbStore; Catcher updated to depend on the interface

Copilot

Pull request overview

This PR refactors breadcrumb handling by introducing a shared BreadcrumbStore contract in @hawk.so/core and updating the JavaScript SDK to use a browser-specific implementation (BrowserBreadcrumbStore) instead of the previous BreadcrumbManager.

Changes:

Added BreadcrumbStore (plus related types) to @hawk.so/core and re-exported them from the core entrypoint.
Refactored the JavaScript SDK breadcrumbs implementation to BrowserBreadcrumbStore and updated Catcher to use the new store API (add/get/clear).
Updated JavaScript tests and types to align with the new names and API surface (and removed the local breadcrumbs-api.ts type).

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
packages/javascript/tests/catcher.user.test.ts	Updates singleton reset/import to `BrowserBreadcrumbStore`.
packages/javascript/tests/catcher.transport.test.ts	Updates singleton reset/import to `BrowserBreadcrumbStore`.
packages/javascript/tests/catcher.test.ts	Updates imports/reset and helper ordering.
packages/javascript/tests/catcher.global-handlers.test.ts	Updates singleton reset/import to `BrowserBreadcrumbStore`.
packages/javascript/tests/catcher.context.test.ts	Updates singleton reset/import to `BrowserBreadcrumbStore`.
packages/javascript/tests/catcher.breadcrumbs.test.ts	Updates singleton reset/import to `BrowserBreadcrumbStore`.
packages/javascript/tests/catcher.addons.test.ts	Updates singleton reset/import to `BrowserBreadcrumbStore`.
packages/javascript/tests/breadcrumbs.test.ts	Renames the suite and updates API calls to `add/get/clear`.
packages/javascript/src/types/index.ts	Re-exports breadcrumb store types from `@hawk.so/core`.
packages/javascript/src/types/breadcrumbs-api.ts	Removes the local `BreadcrumbsAPI` definition in favor of core types.
packages/javascript/src/catcher.ts	Switches from `BreadcrumbManager` to `BrowserBreadcrumbStore` and updates the public `breadcrumbs` getter typing.
packages/javascript/src/addons/breadcrumbs.ts	Introduces `BrowserBreadcrumbStore` implementing the core `BreadcrumbStore` contract and renames browser hint type.
packages/core/src/index.ts	Re-exports breadcrumb store types from the core package entrypoint.
packages/core/src/breadcrumbs/breadcrumb-store.ts	Adds the new shared breadcrumb store contract and associated types.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Dobrunia · 2026-04-01T18:02:42Z

don't forget to bump version

Reversean · 2026-04-01T18:29:38Z

don't forget to bump version

Thx for reminder.

neSpecc · 2026-04-09T18:56:42Z

  public init(options: BreadcrumbsOptions = {}): void {
    if (this.isInitialized) {
-      log('[BreadcrumbManager] init has already been called; breadcrumb configuration is global and subsequent init options are ignored.', 'warn');
+      log('[BrowserBreadcrumbStore] init has already been called; breadcrumb configuration is global and subsequent init options are ignored.', 'warn');


I don't think users should see such a log. It's better to remove it.

Log shortened.

neSpecc · 2026-04-22T16:51:40Z

  public init(options: BreadcrumbsOptions = {}): void {
    if (this.isInitialized) {
-      log('[BreadcrumbManager] init has already been called; breadcrumb configuration is global and subsequent init options are ignored.', 'warn');
+      log('Breadcrumbs store already initialized', 'warn');


Please, remove this log. Users should not see our debug logs.

If init() is somehow called twice, then we should either:

throw exception (if it is not normal case)

hand it silently (if it is ok)

Log removed.

I guess it's not critical to silently return on second init.

Please, explain how init can be called twice? Are you sure it is a regular case, not an exception?

I think in most cases we can consider multiple init calls as a developer misstake, maybe in that case it's better to throw explicitly to prevent this in prod.

Added exception here.

neSpecc · 2026-04-22T16:54:26Z

+      this.breadcrumbStore = BrowserBreadcrumbStore.getInstance();
+      this.breadcrumbStore.init(settings.breadcrumbs ?? {});
+      this.messageProcessors.push(new BreadcrumbsMessageProcessor());


can we initialize BrowserBreadcrumbStore inside the BreadcrumbsMessageProcessor to incapsulate breadcrumbs logic in there and do not pass breadcrumbs to all processors? and get rid of ErrorSnapshot term

Now we call init inside of BrowserBreadcrumbsMessageProcessor.

However we still need BreadcrumbStore as Catcher field since we have Catcher.breadcrumbs(), so breadcrumbs logic is not fully contained inside message-processor.

…n added

…ted in catcher event processing pipeline - MessageProcessor interface and MessageHint type - BrowserMessageProcessor, BreadcrumbsMessageProcessor, ConsoleCatcherMessageProcessor, DebugMessageProcessor - replaced inline addon logic with sequential MessageProcessor pipeline

neSpecc · 2026-05-02T12:21:49Z

I dont like the idea to create a "messages" folder just for a single file. What is "messages" in case of core architecture?

messages are just shorthand for message-processors. I think we can clarify and rename it.

Why it has own package? To store implementations in other modules in corresponding places and keep module structure clean I guess.

If it steel seems bad idea, i can suggest to store interface in same package, where BaseCatcher will be, store implementations in packages of related domains (i.e. BrowserBreadcrumbsMessageProcessor in breadcrumbs, BrowserAddonMessageProcessor in addons, etc) and rid of messages package.

neSpecc · 2026-05-02T12:23:23Z

Do we need to create a /breadcrumbs/ directory? It is supposed to see only architecture-like terms on the first level.

I guess in outer modules we want to store implementations in corresponding places and don't make a mess.

About breadcrumbs I'm not sure where it should be: addons, addons/breadcrumbs, breadcrumbs or just in root where catcher is. I've decided to store interface and implementation in breadcrumbs.

neSpecc · 2026-05-02T12:25:06Z

still do not understand what /messages/ are stand for

neSpecc · 2026-05-02T12:28:50Z

+   * Used to prepare event message before send.
+   * May modify original event payload or return null to drop it.
+   */
+  messageProcessors?: MessageProcessor<'errors/javascript'>[];


should be documented somewhere, maybe at readme.

Check this PR

Is this description fine, or should we explain all core mechanisms more detailed?

neSpecc requested a review from Copilot March 31, 2026 16:33

Copilot started reviewing on behalf of neSpecc March 31, 2026 16:33 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

neSpecc requested a review from Dobrunia April 1, 2026 17:54

Dobrunia approved these changes Apr 1, 2026

View reviewed changes

Reversean force-pushed the refactor/breadcrumb-store branch from 9890ddb to afc73fa Compare April 4, 2026 09:13

neSpecc approved these changes Apr 9, 2026

View reviewed changes

neSpecc requested changes Apr 22, 2026

View reviewed changes

Reversean force-pushed the refactor/breadcrumb-store branch from acafb78 to 31d54df Compare April 28, 2026 20:52

Reversean requested a review from neSpecc April 29, 2026 07:14

refactor(core): BreadcrumbStore abstraction and browser implementatio…

1b2b7df

…n added

Reversean force-pushed the refactor/breadcrumb-store branch 2 times, most recently from b8c9b5c to c049bd4 Compare April 29, 2026 07:43

neSpecc reviewed May 2, 2026

View reviewed changes

Conversation

Reversean commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

What changed and why

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Dobrunia commented Apr 1, 2026

Uh oh!

Reversean commented Apr 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

neSpecc Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Reversean commented Mar 25, 2026 •

edited

Loading

neSpecc Apr 22, 2026 •

edited

Loading