Skip to content

fix(plugin-history-sync): revert activity params string coercion (#705)#717

Merged
ENvironmentSet merged 3 commits into
mainfrom
feature/fep-2381
Jun 8, 2026
Merged

fix(plugin-history-sync): revert activity params string coercion (#705)#717
ENvironmentSet merged 3 commits into
mainfrom
feature/fep-2381

Conversation

@ENvironmentSet
Copy link
Copy Markdown
Collaborator

@ENvironmentSet ENvironmentSet commented Jun 8, 2026

Summary

Reverts #705 which forced activity/step params to string | undefined at the @stackflow/plugin-history-sync boundary to unify runtime types across navigation paths.

While adopting it in a downstream monorepo (FEP-2363) we found it breaks substantial user code, and on re-review concluded its direction partly conflicts with user needs. Per team agreement (Edward + Anakin), we fully revert and re-release as a patch (no unpublish). FEP-1061's original goal will be retried later with a different approach.

What this reverts

Versioning (patch, no unpublish)

  • @stackflow/plugin-history-sync 1.11.11.11.2
  • @stackflow/core 2.0.02.0.1

🤖 Generated with Claude Code

@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented Jun 8, 2026

🦋 Changeset detected

Latest commit: 558e028

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages
Name Type
@stackflow/core Patch
@stackflow/plugin-history-sync Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Jun 8, 2026

Review Change Stack

📝 Walkthrough

Walkthrough

This PR removes internal param-string coercion and context field propagation from the Stackflow core and history sync plugin. ActivityStep.context and step event stepContext fields are deleted, the coerceParamsToString utility is removed, and the history plugin is refactored to compute URLs directly from params without storing intermediate context values. Related tests and documentation are cleaned up.

Changes

Parameter Coercion and Context Preservation Rollback

Layer / File(s) Summary
Core type shape: remove stepContext from events and steps
core/src/Stack.ts, core/src/event-types/StepPushedEvent.ts, core/src/event-types/StepReplacedEvent.ts
ActivityStep type removes optional context?: {} field; StepPushedEvent and StepReplacedEvent payloads replace stepContext?: {} with stepParams: { [key: string]: string | undefined } and remove internal context storage.
Core reducer and aggregate: stop propagating stepContext
core/src/activity-utils/makeActivityReducer.ts, core/src/aggregate.ts
StepPushed/StepReplaced reducers no longer conditionally copy event.stepContext to route context field; aggregate's step remapping removes the conditional context injection; unused StepPopped parameter renamed for clarity.
Remove param coercion utility and cleanup imports
extensions/plugin-history-sync/src/coerceParamsToString.ts, extensions/plugin-history-sync/src/coerceParamsToString.spec.ts
coerceParamsToString function that coerced all non-string param values to string | undefined is deleted; import removed from plugin; comprehensive test coverage of coercion behavior removed.
History sync plugin: remove coercion and simplify param/context handling
extensions/plugin-history-sync/src/historySyncPlugin.tsx
Plugin emits events without param coercion; activityContext.path and stepContext.path are computed from current route path instead of cached in context; URL writeback handlers use template.fill(params) directly instead of falling back to stored context paths; onBeforeStepPush/onBeforeStepReplace hooks removed entirely; forward replay from onPopState no longer preserves activity/step context across history navigation.
Template utility: inline URL building and remove fillWithoutEncode
extensions/plugin-history-sync/src/makeTemplate.ts
_buildUrl helper inlined into the fill method; fillWithoutEncode method removed from returned template object; URL pathname assembly logic now entirely contained within fill.
Test suite cleanup: remove coercion and rendering tests
extensions/plugin-history-sync/src/historySyncPlugin.spec.ts, extensions/plugin-history-sync/src/historySyncPlugin.react.spec.tsx, extensions/plugin-history-sync/src/makeTemplate.spec.ts
Large test suites covering FEP-1061 coercion, encode/decode round-trips, and param string coercion deleted; React integration tests simplified to focus on SSR hydration instead of activity snapshot capture; makeTemplate test suite truncated after the JSON.stringify encode test.
Documentation: remove param coercion guidance
docs/pages/docs/advanced/history-sync.en.mdx, docs/pages/docs/advanced/history-sync.ko.mdx
"Runtime Coercion of Activity Params" section and decode migration notes removed from both English and Korean documentation pages.
Changeset documentation
.changeset/remove-core-step-context-fields.md, .changeset/withdraw-history-sync-param-coercion.md
Changesets document patch version bumps: core removes internal stepContext event fields and ActivityStep.context storage; plugin-history-sync reverts param coercion while preserving URL decoding for URL arrivals.

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

  • daangn/stackflow#709: Added stepContext.path and context propagation to step events and routing, which this PR directly removes.
  • daangn/stackflow#705: Introduced stepContext fields and param string coercion mechanism that this PR undoes across type definitions, reducers, and the history sync plugin.

Suggested reviewers

  • orionmiz
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: reverting activity params string coercion in the plugin-history-sync package.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description check ✅ Passed The pull request description clearly explains the purpose of reverting FEP-2381 (#705) and details what is being changed across multiple packages and their reasoning.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feature/fep-2381

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new Bot commented Jun 8, 2026

@stackflow/core

yarn add https://pkg.pr.new/@stackflow/core@717.tgz

@stackflow/link

yarn add https://pkg.pr.new/@stackflow/link@717.tgz

@stackflow/plugin-basic-ui

yarn add https://pkg.pr.new/@stackflow/plugin-basic-ui@717.tgz

@stackflow/plugin-blocker

yarn add https://pkg.pr.new/@stackflow/plugin-blocker@717.tgz

@stackflow/plugin-devtools

yarn add https://pkg.pr.new/@stackflow/plugin-devtools@717.tgz

@stackflow/plugin-google-analytics-4

yarn add https://pkg.pr.new/@stackflow/plugin-google-analytics-4@717.tgz

@stackflow/plugin-history-sync

yarn add https://pkg.pr.new/@stackflow/plugin-history-sync@717.tgz

@stackflow/plugin-lifecycle

yarn add https://pkg.pr.new/@stackflow/plugin-lifecycle@717.tgz

@stackflow/plugin-renderer-basic

yarn add https://pkg.pr.new/@stackflow/plugin-renderer-basic@717.tgz

@stackflow/plugin-renderer-web

yarn add https://pkg.pr.new/@stackflow/plugin-renderer-web@717.tgz

@stackflow/plugin-sentry

yarn add https://pkg.pr.new/@stackflow/plugin-sentry@717.tgz

@stackflow/plugin-stack-depth-change

yarn add https://pkg.pr.new/@stackflow/plugin-stack-depth-change@717.tgz

@stackflow/react-ui-core

yarn add https://pkg.pr.new/@stackflow/react-ui-core@717.tgz

@stackflow/react

yarn add https://pkg.pr.new/@stackflow/react@717.tgz

commit: 558e028

@cloudflare-workers-and-pages
Copy link
Copy Markdown

Deploying stackflow-demo with  Cloudflare Pages  Cloudflare Pages

Latest commit: 558e028
Status: ✅  Deploy successful!
Preview URL: https://ce34abf5.stackflow-demo.pages.dev
Branch Preview URL: https://feature-fep-2381.stackflow-demo.pages.dev

View logs

@cloudflare-workers-and-pages
Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs
stackflow-docs 558e028 Commit Preview URL Jun 08 2026, 12:44 PM

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@core/src/Stack.ts`:
- Line 1: The file imports the type BaseDomainEvent but never uses it; remove
the unused type-only import to clean up the module by deleting BaseDomainEvent
from the import statement in core/src/Stack.ts (i.e., remove the reference to
BaseDomainEvent so the import becomes unused-free).
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: edeebcb7-8fef-4527-b849-e661d876801d

📥 Commits

Reviewing files that changed from the base of the PR and between 78e7b84 and 558e028.

📒 Files selected for processing (17)
  • .changeset/remove-core-step-context-fields.md
  • .changeset/withdraw-history-sync-param-coercion.md
  • core/src/Stack.ts
  • core/src/activity-utils/makeActivityReducer.ts
  • core/src/aggregate.ts
  • core/src/event-types/StepPushedEvent.ts
  • core/src/event-types/StepReplacedEvent.ts
  • docs/pages/docs/advanced/history-sync.en.mdx
  • docs/pages/docs/advanced/history-sync.ko.mdx
  • extensions/plugin-history-sync/INTENT.md
  • extensions/plugin-history-sync/src/coerceParamsToString.spec.ts
  • extensions/plugin-history-sync/src/coerceParamsToString.ts
  • extensions/plugin-history-sync/src/historySyncPlugin.react.spec.tsx
  • extensions/plugin-history-sync/src/historySyncPlugin.spec.ts
  • extensions/plugin-history-sync/src/historySyncPlugin.tsx
  • extensions/plugin-history-sync/src/makeTemplate.spec.ts
  • extensions/plugin-history-sync/src/makeTemplate.ts
💤 Files with no reviewable changes (9)
  • extensions/plugin-history-sync/src/coerceParamsToString.spec.ts
  • extensions/plugin-history-sync/src/coerceParamsToString.ts
  • extensions/plugin-history-sync/INTENT.md
  • core/src/event-types/StepPushedEvent.ts
  • core/src/aggregate.ts
  • docs/pages/docs/advanced/history-sync.ko.mdx
  • extensions/plugin-history-sync/src/makeTemplate.spec.ts
  • core/src/event-types/StepReplacedEvent.ts
  • docs/pages/docs/advanced/history-sync.en.mdx

Comment thread core/src/Stack.ts
@@ -1,3 +1,4 @@
import type { BaseDomainEvent } from "event-types/_base";
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Check if BaseDomainEvent is referenced in Stack.ts beyond the import line

# Search for BaseDomainEvent usage in Stack.ts, excluding the import line itself
rg -n 'BaseDomainEvent' core/src/Stack.ts | rg -v '^1:import'

Repository: daangn/stackflow

Length of output: 42


Remove the unused BaseDomainEvent type-only import from core/src/Stack.ts
BaseDomainEvent is only present in the import statement and has no other references in core/src/Stack.ts, so the import can be removed.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@core/src/Stack.ts` at line 1, The file imports the type BaseDomainEvent but
never uses it; remove the unused type-only import to clean up the module by
deleting BaseDomainEvent from the import statement in core/src/Stack.ts (i.e.,
remove the reference to BaseDomainEvent so the import becomes unused-free).

@ENvironmentSet
Copy link
Copy Markdown
Collaborator Author

PR #705가 해결하고자 하는 이슈의 핵심은 타입과 동작을 일치시키는 데에 있다고 생각해요. 둘이 상이하면 타입 검사를 신뢰할 수 없게 되고, 디버깅이 복잡해지며, 무엇보다도 복잡한 구현 맥락을 지속적으로 신경쓰며 작업해야 해서 크게 불편해요.

이 관점에서 볼 때, 해당 PR에는 다음과 같은 문제가 있어요.

  1. 타입과 동작이 일치하지 않는 이슈가 일부 남아있어요.
  • loader 매개변수로 들어오는 값은 여전히 상황에 따라 타입 정의와 다를 수 있어요.
  • plugin-history-sync보다 먼저 적용되는 플러그인은 여전히 타입 정의와 다른 값을 받을 수 있어요.
  • 컴포넌트 props로 activity params를 받는 경우 여전히 타입 정의와 다른 값을 받을 수 있어요.
  1. activity params 소비 맥락은 여전히 복잡해요.
  • 비록 타입 정의와 런타임 동작이 다를 수 있다는 이슈는 일부 해소되었지만, 묵시적 형 변환이 개입한다는 맥락이 추가로 생겼어요.
    • 묵시적 형 변환은 그 자체로 복잡한 규칙이라 API 규약을 어렵게 만들어요.
  • push, replace를 사용하는 쪽이나 액티비티를 정의하는 쪽에서는 전달한 것, 정의한 것과 다른 것이 들어오는 현상을 이해하기 위해 노력해야 해요.
    • ex: false를 넘겼는데 "true"가 돼서 truthy 검사를 통과하는 이슈를 디버깅하는 경우가 종종 생길 거예요.
    • activity params 조정에 사용하는 묵시적 형 변환 알고리즘은 자바스크립트 표준 형 변환 알고리즘과도 상이해요.
      • null은 undefined로 변환해요. string으로 강제되지지도차 않아요.
      • 객체와 함수는 기본적으로 JSON.stringify를 사용해요.
  1. 기존 기능에 파괴적 변환이 생기다 못해 망가졌어요.
  • 이 패치는 decode API 동작을 파괴적으로 변경할 뿐더러, activity params의 일부를 string 외의 다른 타입의 값으로 조정한다는 본래 목적을 달성할 수 없도록 동작을 바꾸어요.
  • 더해서, 이런 대형 변경은 patch보다는 major bump가 적절하다 생각해요.

그런 고로, revert합니다.

@ENvironmentSet ENvironmentSet merged commit 416b65d into main Jun 8, 2026
9 checks passed
@ENvironmentSet ENvironmentSet deleted the feature/fep-2381 branch June 8, 2026 14:28
@coderabbitai coderabbitai Bot mentioned this pull request Jun 8, 2026
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.

1 participant