Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
docs(frontend): clarify transient state ownership (#41541)
yyh57144b0094b0
diff --git a/.agents/skills/frontend-code-review/references/component-architecture.md b/.agents/skills/frontend-code-review/references/component-architecture.mdindex ffabbf4cd69..9eda6589fd0 100644--- a/.agents/skills/frontend-code-review/references/component-architecture.md+++ b/.agents/skills/frontend-code-review/references/component-architecture.md@@ -61,7 +61,7 @@ Flag effects that:- Transform props/state for rendering.- Copy one state value into another representing the same concept.- Handle user actions that belong in event handlers.-- Reset state from props when a keyed reset, stable ID, or render-time derivation would work.+- Reset local state from props or visibility when derivation, a stable semantic identity, or the intended mounted owner already expresses the lifecycle.- Fetch data that belongs in framework APIs or TanStack Query.If an effect remains, it must synchronize with a named external system: browser API, subscription, timer, analytics-on-visibility, non-React widget, or imperative DOM integration.@@ -71,11 +71,24 @@ If an effect remains, it must synchronize with a named external system: browserFlag:- Storing derived booleans, disabled flags, default tabs, or loading labels that can be calculated from current query/feature state.+- Per-session state held by a longer-lived visibility coordinator and cleared through an open-state Effect or a generated key when the primitive's mounted-content lifecycle already matches the intended state lifetime.+- A DOM field mirrored into competing prop, default, and React state sources when editing does not require those sources to synchronize.- Local state used to fake server data or generated contract fields.- UI state persisted to localStorage when it is live app state.- Feature-local mock shells wired to unrelated existing APIs before the real API is confirmed.-Prefer render-time derivation. Keep true local state for user choices, transient input, controlled popups, and feature UI state that has no server source.+Review state lifetime before its storage mechanism. For a hidden surface, distinguish the+visibility coordinator from mounted content. State private to one mounted session belongs in that+content owner; promote it only when the draft must survive that content owner's unmount or another+owner coordinates it. A stable semantic identity key may create a new snapshot when the represented+identity changes; a generated key is not a routine reset command.++Prefer render-time derivation. Keep true local state for user choices, transient input, controlled+popups, and feature UI state that has no server source. Submit-only DOM fields may remain+uncontrolled; use local controlled state when React must own the current value to drive rendering+or coordination. Observing change events or tracking a derived fact such as dirty state does not+require mirroring the field value. Do not flag controlled state by itself without a concrete+competing-source, stale-state, or ownership defect.## Navigationdiff --git a/.agents/skills/frontend-code-review/references/testing.md b/.agents/skills/frontend-code-review/references/testing.mdindex 2f81d10589e..3bda124c01b 100644--- a/.agents/skills/frontend-code-review/references/testing.md+++ b/.agents/skills/frontend-code-review/references/testing.md@@ -9,6 +9,7 @@ Flag missing coverage when a change alters a reachable contract such as:- User interaction, navigation, form submission, validation, or permissions.- Query or mutation behavior, URL state, persistence, or one-shot signals.- Loading, error, empty, and recovery states that users can encounter.+- A hidden surface whose close-and-reopen behavior changes whether in-progress state resets or persists.- Accessibility-critical labels, keyboard flow, focus, disabled state, or overlay behavior.- A regression-prone business rule or bug fix that can be reproduced through a public boundary.diff --git a/.agents/skills/how-to-write-component/SKILL.md b/.agents/skills/how-to-write-component/SKILL.mdindex 2b0e50f538d..b6599743227 100644--- a/.agents/skills/how-to-write-component/SKILL.md+++ b/.agents/skills/how-to-write-component/SKILL.md@@ -9,10 +9,11 @@ Use this skill to route component architecture decisions to its bundled referenc## First Decisions-| Question | Default | Promote only when |+| Question | Default | Choose differently when || --- | --- | --- || Where should code live? | In the product workflow, route, or feature owner. | Several verticals need the same stable contract. |-| Who owns state and handlers? | The lowest visual owner that consumes them. | A parent coordinates one workflow or consistent snapshot. |+| Who owns state and handlers? | The lowest owner that consumes them and whose lifetime matches the state. | Another owner coordinates the value or it must survive the local owner's unmount. |+| Should React control a value? | Leave submit-only DOM fields uncontrolled. | The workflow must own the current value to drive rendering or coordination. || Should state enter Jotai? | Keep component and form state local. | Siblings need one source of truth or scoped workflow persistence. || Who owns URL state? | Next.js route APIs and `nuqs`. | Atoms require a read-only route-identity bridge. || Who owns remote state? | TanStack Query at the lowest consumer. | Atom state drives the query or shared derivations consume it. |@@ -24,12 +25,12 @@ Use this skill to route component architecture decisions to its bundled referenc- Component moves, module boundaries, props, types, or owner placement: read [`references/ownership.md`][ownership].- Jotai, form drafts, route identity, URL state, or persistence: read [`references/state.md`][state].- Generated contracts, nullable API data, Query, mutations, SSR, auth, or workspace state: read [`references/data.md`][data].-- Hotkeys, focus, dialogs, menus, popovers, or other secondary surfaces: read [`references/interactions.md`][interactions] and the overlay guide it references when applicable.+- Hotkeys, focus, dialogs, menus, popovers, or other secondary surfaces: read [`references/interactions.md`][interactions] and the overlay guide it references when applicable. Also read [`references/state.md`][state] when the surface owns a draft or other local session state.- Effects, navigation, memoization, preloading, or render cost: read [`references/runtime.md`][runtime].## Workflow-1. Identify the behavior owner and the public contract being changed.+1. Identify the behavior owner, the required state lifetime, and the public contract being changed.2. Read the nearby implementation, tests, and only the routed skill references.3. Implement one coherent vertical slice. Do not expand into equivalent patterns elsewhere unless the current contract cannot be completed without them.4. Verify observable behavior at the narrowest sufficient boundary, then run the checks documented by the owning package: `web/docs/test.md` or `web/docs/lint.md` for Web, and `packages/dify-ui/docs/testing.md` for Dify UI.diff --git a/.agents/skills/how-to-write-component/references/interactions.md b/.agents/skills/how-to-write-component/references/interactions.mdindex 68233987b61..ba9315f981e 100644--- a/.agents/skills/how-to-write-component/references/interactions.md+++ b/.agents/skills/how-to-write-component/references/interactions.md@@ -23,8 +23,10 @@ Read this document when a change involves application hotkeys, focus, dialogs, m- Follow the [overlay contract] for primitive choice and shared mechanics. The nearest consumer `AGENTS.md` owns application-specific composite reuse policy.- Separate behavior ownership from placement ownership: the action may own trigger, open state, and menu content while the caller owns slots, offsets, and alignment.- Keep menu and dialog surfaces as siblings when a menu command opens a dialog. Mount the dialog outside popup content.-- Mount controlled overlays unconditionally unless unmounting is required for performance or reset semantics. Prefer keyed or owner-local reset over conditional wrappers.-- Put query and mutation work inside dialog or alert-dialog content when it should mount only after opening.-- Prefer uncontrolled roots when the primitive can own open state. Use controlled state only for business coordination, analytics, cleanup, or explicit reset behavior.+- Keep overlay open-state ownership separate from content-session ownership. A controlled root does not require controlled fields or root-owned drafts.+- Match transient state to the primitive's content mount lifecycle. State below an unmounting content boundary gets a fresh instance after unmount; intentionally kept-mounted content needs an explicit persistence or reset policy.+- Keep a controlled overlay root at its coordination owner so the primitive can complete exit transitions, focus restoration, and detached-handle behavior. Do not conditionally remove the root to reset content state, and use keys only for stable semantic identity.+- Place query subscriptions and mutation observers at the owner whose lifetime matches when they should run. Mounted-session work may belong inside content; work that must start or stop exactly with `open` needs an explicit open-state condition.+- Prefer primitive-owned open state unless another owner must observe or coordinate it. Analytics callbacks and local cleanup alone do not require a controlled root.[overlay contract]: ../../../../packages/dify-ui/docs/overlays.mddiff --git a/.agents/skills/how-to-write-component/references/ownership.md b/.agents/skills/how-to-write-component/references/ownership.mdindex d8da521aafc..886421ef394 100644--- a/.agents/skills/how-to-write-component/references/ownership.md+++ b/.agents/skills/how-to-write-component/references/ownership.md@@ -12,8 +12,8 @@ Read this document when adding, moving, splitting, or refactoring React componen## Component Ownership-- Put state, data access, loading, empty, error, and handlers in the lowest visual owner that uses them.-- Keep coordination in a parent only when it needs one consistent snapshot or coordinates submission, shared selection, batch behavior, navigation, or cross-section loading and errors.+- Put state, data access, loading, empty, error, and handlers in the lowest owner that uses them and whose mounted lifetime matches the required persistence.+- Keep coordination in a parent only when it needs one consistent snapshot, the value must intentionally survive the local owner's unmount, or the parent coordinates submission, shared selection, batch behavior, navigation, or cross-section loading and errors.- Repeated TanStack Query calls in siblings are acceptable when each sibling independently consumes the data; the cache already deduplicates requests.- Pass stable domain identity across boundaries. Do not pass raw server data together with separately derived flags for the same concept.- One pass-through prop layer is acceptable. Repeated forwarding means ownership should move closer to the consumer or into feature-scoped shared state.@@ -23,7 +23,8 @@ Read this document when adding, moving, splitting, or refactoring React componen## Boundaries- State-heavy wizards, drawers, modals, and secondary workflows can form a small vertical surface with an entrypoint, optional feature-local state, and shallow owners matching real visual regions.-- The entrypoint owns route integration, provider wiring, close behavior, and mounting. Composition owners handle workflow branches; the closest visual owner handles section branches.+- The entrypoint owns route integration, provider wiring, placement, and open-state coordination. A content or session owner keeps state scoped to that mounted surface.+- Judge hook lifetime by the component that declares the hook and the primitive's mount contract, not only by where its rendered controls appear in JSX.- Separate hidden dialogs, dropdowns, and popovers into small local owners when their content obscures the parent flow.- Keep cohesive forms, menu bodies, and one-off helpers local unless they have their own state, reuse, or semantic boundary.- Avoid wrapper components and wrapper DOM that only rename props, pass children through, or hide the real primitive. A wrapper must own behavior, validation, state, accessibility, layout, or library integration.diff --git a/.agents/skills/how-to-write-component/references/runtime.md b/.agents/skills/how-to-write-component/references/runtime.mdindex 24554d895f5..42131944637 100644--- a/.agents/skills/how-to-write-component/references/runtime.md+++ b/.agents/skills/how-to-write-component/references/runtime.md@@ -7,7 +7,7 @@ Read this document when a change introduces Effects, navigation side effects, me- Keep render pure: do not read or write `ref.current` during render except for predictable null-guarded lazy initialization. Update interaction-owned refs in event handlers, synchronize external-system refs after commit, and use state or derivation for rendered values.- Use Effects only to synchronize with a named external system such as a browser API, subscription, timer, analytics integration, non-React widget, or imperative DOM API.- Do not use Effects to transform render state, handle user actions, copy query data, reset state from props, or fetch data owned by framework APIs or TanStack Query.-- Initialize query-backed forms with keyed remounts or surface-entry hydration instead of copying data through Effects.+- Initialize query-backed form sessions after their defaults are available instead of copying data through Effects. Use a stable semantic identity key when the represented identity changes; use the intended surface lifecycle for per-session reset.## Navigationdiff --git a/.agents/skills/how-to-write-component/references/state.md b/.agents/skills/how-to-write-component/references/state.mdindex 0ede0a85e92..680d77fb8b9 100644--- a/.agents/skills/how-to-write-component/references/state.md+++ b/.agents/skills/how-to-write-component/references/state.md@@ -9,10 +9,12 @@ Read this document when a change involves Jotai, form drafts, route identity, sh- Keep server and cache state in TanStack Query. Use existing feature stores for complex, high-frequency interaction state such as workflow canvas drag, resize, and runtime panels.- Use feature-owned storage only for low-frequency client preferences, dismissed notices, and UI defaults. Live application state does not belong in local storage.-## Forms+## Forms And Sessions-- Prefer uncontrolled Dify UI form and field controls when values are only read at submit time. Initialize query-backed defaults with `defaultValue` and keyed remounts.-- Promote form values to atoms only when another owner reacts to in-progress values, the draft must survive scoped unmounting, or several workflow steps edit the same draft.+- Keep form state in the narrowest owner whose lifetime matches the draft. A draft scoped to one mounted surface belongs to that content or session owner; a draft that must survive its current owner's unmount belongs to an explicit longer-lived feature owner.+- Prefer uncontrolled fields when values are only read at submit time. Use local controlled state only when React must own the current value to drive dependent UI or linked fields; track derived facts such as dirty state without mirroring the field value. Controlledness does not decide whether a draft is local or persisted.+- For query-backed defaults, establish the form session after the required defaults are available. `defaultValue` initializes the current mount; a stable semantic identity key may create a fresh snapshot when the represented identity changes. Do not use a generated key as a routine reset command.+- Promote drafts beyond the session only when another owner reacts to in-progress values, several workflow steps share one draft, or the draft must intentionally survive unmounting. Start with the lowest shared React owner; use feature-scoped atoms only when their coordination or persistence contract is needed.- Keep validation, source priority, fallback behavior, dirty checks, and payload assembly in the workflow that owns submission.## Route And URL Statediff --git a/packages/dify-ui/AGENTS.md b/packages/dify-ui/AGENTS.mdindex 5d02acdc1e0..2cd05f418f9 100644--- a/packages/dify-ui/AGENTS.md+++ b/packages/dify-ui/AGENTS.md@@ -20,9 +20,9 @@ then read only the guide for the contract being changed.- Imports, exports, naming, public types, generics, and anatomy: [Public API authoring]- Button and icon-only action behavior: [Button contract] and [Icon Button contract]- Compound input behavior: [Input Group contract]-- Form structure and labels: [Forms]+- Form structure, labels, and value ownership: [Forms]- Picker choice and typed values: [Selection]-- Portals, layering, and floating-surface semantics: [Overlays]+- Portals, presence, layering, and floating-surface semantics: [Overlays]- Tailwind integration and radius mapping: [Styling]- Package test ownership and setup: [Testing and development]diff --git a/packages/dify-ui/README.md b/packages/dify-ui/README.mdindex 5825f310a82..622b4f556b4 100644--- a/packages/dify-ui/README.md+++ b/packages/dify-ui/README.md@@ -70,9 +70,9 @@ Upstream behavior remains owned by the [Base UI documentation].| Guide | Scope || ------------------------- | ------------------------------------------------------------------------------ |-| [Forms] | Native submit boundaries, fields, labels, grouped controls, and errors. |+| [Forms] | Native submit boundaries, value ownership, fields, labels, and errors. || [Selection] | Typed values and choosing among segmented controls, pickers, and radio groups. |-| [Overlays] | Portals, root isolation, layering, trigger composition, and semantics. |+| [Overlays] | Portals, presence lifecycles, layering, trigger composition, and semantics. || [Styling] | Tailwind CSS integration and the Figma radius mapping. || [Public API authoring] | Subpath exports, naming, public types, generics, and private helpers. || [Testing and development] | Package commands, test ownership, accessibility, and animation setup. |diff --git a/packages/dify-ui/docs/forms.md b/packages/dify-ui/docs/forms.mdindex f3d3f21c1fe..862b207ed74 100644--- a/packages/dify-ui/docs/forms.md+++ b/packages/dify-ui/docs/forms.md@@ -16,6 +16,22 @@ remains correct when another form library owns submission and validation; do notSet [`Button`] submit buttons to `type="submit"` explicitly. Keep every other button inside a format `type="button"`.+## Value and state ownership++`Form` owns the submission and validation boundary described above, not each field's draft.++Choose controlledness from source-of-truth needs, independently from where a draft is stored.+Prefer `defaultValue` when application React code does not need to own the current value. Use+`value` and change handlers when application rendering or coordination must own it while editing.+Listening to change events, tracking dirty state, and native or primitive validation do not by+themselves require controlled state.++Application code owns the draft in the narrowest component whose lifetime matches it. A value can+be controlled locally without being lifted. An uncontrolled field can participate in a persisted+workflow when that workflow captures its value at an explicit persistence boundary. The+surrounding surface defines its mount lifecycle; owner placement determines whether draft state+lives inside or outside that lifecycle.+## Fields and labelsUse `Field` when a control needs a shared name, label, validation, description, or error state. A@@ -61,9 +77,9 @@ option with `FieldItem` and give it its own label:Every radio belongs to a `RadioGroup`. Use `FieldsetLegend` to name the group and `FieldLabel` toname each option; do not render a standalone `Radio`.-Keep form state, schemas, server validation, and reset behavior outside these primitives. Pass-their observable state through the public field and control props instead of replacing the-semantic structure.+Keep form state, schemas, server validation, and reset behavior outside the primitive internals,+in the nearest application owner with the required lifetime. Pass observable state through the+public field and control props instead of replacing the semantic structure.[Base UI Slider anatomy]: https://base-ui.com/react/components/slider#anatomy[Base UI forms handbook]: https://base-ui.com/react/handbook/formsdiff --git a/packages/dify-ui/docs/overlays.md b/packages/dify-ui/docs/overlays.mdindex 422ce4621f5..1274ce1b274 100644--- a/packages/dify-ui/docs/overlays.md+++ b/packages/dify-ui/docs/overlays.md@@ -10,6 +10,25 @@ Floating surfaces render through [Base UI Portal] into `document.body`. Conveniesuch as `DialogContent`, `PopoverContent`, and `SelectContent` own their portals internally;primitives with explicit anatomy expose the constituent portal and content parts.+## Mounting and state lifetime++An overlay root's React lifetime, its open state, and its portal subtree's presence are separate.+Presence is part of each primitive's contract. Convenience content follows its primitive's+default mount behavior; for example, `DialogContent` owns a [`Dialog.Portal`] whose subtree mounts+when the dialog opens and unmounts after any close transition completes. The `Dialog` root may+remain mounted and controlled independently of that content lifetime. Removing the controlled+root with the same condition that closes it bypasses the primitive's closing lifecycle.++Application code can use an unmounting content subtree as the owner of state scoped to one mounted+content session. State that must survive the subtree's unmount belongs to an explicit longer-lived+feature owner.+Unmounting resets only DOM and component state owned inside that subtree; state declared by an+ancestor or external store survives. Portal placement alone is not a reset boundary.+Consumers using explicit anatomy may opt into `keepMounted` where that portal supports it; they+must then define which state persists and which state resets instead of relying on a remount.+Check the selected primitive's API rather than assuming every overlay portal has the same presence+options.+The host must establish an isolated stacking context at its application root:```tsx@@ -58,6 +77,7 @@ spacing unless its API documents a measured exception.[Base UI Portal]: https://base-ui.com/react/overview/quick-start#portals[MDN `isolation`]: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/isolation+[`Dialog.Portal`]: https://base-ui.com/react/components/dialog#portal[`Popover`]: https://base-ui.com/react/components/popover[`PreviewCard`]: https://base-ui.com/react/components/preview-card[`Tooltip`]: https://base-ui.com/react/components/tooltipdiff --git a/web/docs/test.md b/web/docs/test.mdindex df686e8e37b..7de60d55f15 100644--- a/web/docs/test.md+++ b/web/docs/test.md@@ -59,6 +59,7 @@ Browser Mode remains a focused component or feature test and currently proves Ch- Drive state transitions through props, user interaction, URL changes, or public APIs.- Assert rendered UI, ARIA state, navigation, persistence, network-boundary calls, or another observable result.+- For a reset-or-persistence regression in a hidden surface, exercise the public transition: open, modify, close and wait for the surface to disappear, then reopen. Assert the intended behavior without coupling the test to hook placement, component names, keys, or private mount structure.- Do not inspect React state, refs, hook call order, effect dependencies, or private DOM structure.- Test referential identity only when identity is itself a documented public contract.- One test should describe one behavior. It may contain multiple assertions when they jointly prove that behavior.