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

Author: ENvironmentSet

.changeset/remove-core-step-context-fields.md

@@ -0,0 +1,6 @@
+---
+"@stackflow/core": patch
+---
+
+Remove the internal optional `stepContext` event fields and `ActivityStep.context`
+storage that were added for plugin-history-sync URL preservation.

.changeset/withdraw-history-sync-param-coercion.md

@@ -0,0 +1,7 @@
+---
+"@stackflow/plugin-history-sync": patch
+---
+
+Withdraw the activity and step param string coercion introduced in `1.11.0`.
+Internal navigation now preserves non-string param values at runtime again, while
+URL arrivals continue to use decoded URL params as before.

core/src/Stack.ts

@@ -1,3 +1,4 @@
+import type { BaseDomainEvent } from "event-types/_base";
 import type {
   DomainEvent,
   PoppedEvent,
@@ -18,7 +19,6 @@ export type ActivityStep = {
   params: {
     [key: string]: string | undefined;
   };
-  context?: {};
   enteredBy: PushedEvent | ReplacedEvent | StepPushedEvent | StepReplacedEvent;
   exitedBy?: ReplacedEvent | PoppedEvent | StepReplacedEvent | StepPoppedEvent;
   zIndex: number;

core/src/activity-utils/makeActivityReducer.ts

@@ -68,7 +68,6 @@ export function makeActivityReducer(context: {
       const newRoute = {
         id: event.stepId,
         params: event.stepParams,
-        ...(event.stepContext ? { context: event.stepContext } : null),
         enteredBy: event,
         zIndex: activity.zIndex,
         hasZIndex: event.hasZIndex ?? false,
@@ -89,7 +88,6 @@ export function makeActivityReducer(context: {
       const newRoute = {
         id: event.stepId,
         params: event.stepParams,
-        ...(event.stepContext ? { context: event.stepContext } : null),
         enteredBy: event,
         zIndex: activity.zIndex,
         hasZIndex: event.hasZIndex ?? false,
@@ -109,7 +107,7 @@ export function makeActivityReducer(context: {
      * Pop the last step
      * If there are params in the previous step, set them as the new params
      */
-    StepPopped: (activity: Activity, _event: StepPoppedEvent): Activity => {
+    StepPopped: (activity: Activity, event: StepPoppedEvent): Activity => {
       activity.steps.pop();
 
       const beforeActivityParams = last(activity.steps)?.params;

core/src/aggregate.ts

@@ -75,7 +75,6 @@ export function aggregate(inputEvents: DomainEvent[], now: number): Stack {
             {
               ...step,
               zIndex: lastStepZIndex + (step.hasZIndex ? 1 : 0),
-              ...(step.context ? { context: step.context } : null),
             },
           ];
         }, []);

core/src/event-types/StepPushedEvent.ts

@@ -7,7 +7,6 @@ export type StepPushedEvent = BaseDomainEvent<
     stepParams: {
       [key: string]: string | undefined;
     };
-    stepContext?: {};
     targetActivityId?: string;
     hasZIndex?: boolean;
   }

core/src/event-types/StepReplacedEvent.ts

@@ -7,7 +7,6 @@ export type StepReplacedEvent = BaseDomainEvent<
     stepParams: {
       [key: string]: string | undefined;
     };
-    stepContext?: {};
     targetActivityId?: string;
     hasZIndex?: boolean;
   }

docs/pages/docs/advanced/history-sync.en.mdx

@@ -72,22 +72,6 @@ The `historySyncPlugin` accepts two options: `config` and `fallbackActivity`.
   **Warning** - When mapping activity parameters to path parameters, ensure that the parameter values are URL-safe. If special characters that are not URL-safe are used, query parameters may appear duplicated.
 </Callout>
 
-## Runtime Coercion of Activity Params
-
-Regardless of how an activity is entered, including `push()`, `replace()`, `pushStep()`, `replaceStep()`, or URL arrival with or without a `decode` hook, the params you receive from `useActivityParams()` are always `string | undefined` at runtime.
-
-```tsx
-// These two paths used to produce different runtime types. They don't anymore.
-push("ArticleActivity", { visible: true })   // store: { visible: "true" }
-// URL arrival: /articles/1?visible=true      // store: { visible: "true" }
-```
-
-The `encode` hook on a route still receives the original typed params, so you can use `encode: ({ visible }) => ({ visible: visible ? "y" : "n" })` exactly as before. Coercion happens at the `@stackflow/plugin-history-sync` boundary, after `encode` has consumed the typed values to build the URL.
-
-<Callout emoji="⚠️">
-  **Migration note for `decode` users**: if you previously relied on `decode` to inject typed values, such as `decode: (p) => ({ count: Number(p.count) })`, and read them back via `useActivityParams().count` as a number, that value is now a string in the store. Perform the type coercion at the usage site instead: `Number(params.count)`.
-</Callout>
-
 <Callout emoji="⚡️">
   In a server-side rendering environment, the `window.location` value is not available, so the initial activity cannot be determined. To set the initial activity, add the path value to the `req.path` field in the `initialContext` of the Stack as follows:
 

docs/pages/docs/advanced/history-sync.ko.mdx

@@ -75,22 +75,6 @@ const { Stack } = stackflow({
   특수문자를 사용하는 경우 query parameter가 중복해서 나타날 수 있어요.
 </Callout>
 
-## 액티비티 파라미터의 런타임 강제 변환
-
-액티비티에 어떻게 진입했는지와 관계없이, `push()`, `replace()`, `pushStep()`, `replaceStep()`, 또는 `decode` 훅 유무와 무관한 URL 직접 진입 모두에서 `useActivityParams()`로 받는 파라미터는 런타임에 항상 `string | undefined`예요.
-
-```tsx
-// 이전에는 두 경로가 런타임에 서로 다른 타입을 반환했지만, 이제는 동일해요.
-push("ArticleActivity", { visible: true })   // 스토어: { visible: "true" }
-// URL 진입: /articles/1?visible=true         // 스토어: { visible: "true" }
-```
-
-라우트의 `encode` 훅은 여전히 원본의 타입이 적용된 파라미터를 받아요. 예를 들어 `encode: ({ visible }) => ({ visible: visible ? "y" : "n" })`는 이전과 동일하게 동작해요. 문자열화는 `encode`가 URL 생성을 위해 타입이 적용된 값을 소비한 이후에, `@stackflow/plugin-history-sync` 경계에서 이뤄져요.
-
-<Callout emoji="⚠️">
-  **`decode` 사용자를 위한 마이그레이션 안내**: 이전에 `decode`로 타입이 적용된 값을 주입해서, 예를 들어 `decode: (p) => ({ count: Number(p.count) })`, `useActivityParams().count`를 숫자로 사용하셨다면, 이제 해당 값은 스토어에서 문자열이에요. 사용 지점에서 타입 변환을 해주세요: `Number(params.count)`.
-</Callout>
-
 <Callout emoji="⚡️">
   서버사이드 렌더링 환경에서는 `window.location` 값이 없으므로 초기 액티비티를 결정할 수 없어요.
   초기 액티비티를 결정하려면 다음과 같이 Stack의 `initialContext`에 `req.path` 필드에 path 값을 넣어주세요.