@flowstack-ui/agent-tools 0.1.0-bootstrap.0

package/public/packages/atom/0.24.0/components/pressable.txt

@@ -0,0 +1,94 @@
+# Pressable
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: pressable
+
+# Pressable agent guide
+
+## Purpose
+
+Add normalized press interaction to a deliberately chosen semantic element without deciding that element's visual design.
+
+## Use when
+
+- A semantic surface needs unified keyboard, pointer, and press handling and neither Button nor Link alone expresses the composition.
+
+## Choose something else when
+
+- A normal action or destination needs no custom semantic surface. Use Button or Link.
+
+## Required composition
+
+- Choose the correct rendered semantic element first, then attach Pressable behavior without nesting interactive controls.
+
+## Rules
+
+- **MUST:** Pressable does not supply missing semantics; the rendered element must already express the interaction.
+- **MUST:** Do not create nested interactive elements.
+
+## Common mistakes
+
+- **Avoid:** Using Pressable as a generic clickable div. **Instead:** Prefer Button or Link; use Pressable only for a justified semantic composition.
+
+## Validation checklist
+
+- Verify the rendered role and accessible name.
+- Test keyboard, pointer, touch, focus, and disabled behavior.
+
+## Related guidance
+
+- `button`
+- `link`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "pressable",
+  "name": "Pressable",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Add normalized press interaction to a deliberately chosen semantic element without deciding that element's visual design.",
+  "useWhen": [
+    "A semantic surface needs unified keyboard, pointer, and press handling and neither Button nor Link alone expresses the composition."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A normal action or destination needs no custom semantic surface.",
+      "useInstead": "Button or Link"
+    }
+  ],
+  "composition": [
+    "Choose the correct rendered semantic element first, then attach Pressable behavior without nesting interactive controls."
+  ],
+  "rules": [
+    {
+      "id": "pressable-semantics-first",
+      "level": "must",
+      "statement": "Pressable does not supply missing semantics; the rendered element must already express the interaction."
+    },
+    {
+      "id": "pressable-no-nesting",
+      "level": "must",
+      "statement": "Do not create nested interactive elements."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Pressable as a generic clickable div.",
+      "correction": "Prefer Button or Link; use Pressable only for a justified semantic composition."
+    }
+  ],
+  "validation": [
+    "Verify the rendered role and accessible name.",
+    "Test keyboard, pointer, touch, focus, and disabled behavior."
+  ],
+  "related": [
+    "button",
+    "link"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/progress.txt

@@ -0,0 +1,130 @@
+# Progress
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: progress
+
+# Progress agent guide
+
+## Purpose
+
+Communicate determinate or indeterminate completion of ongoing work with progressbar semantics, normalized range state, and a presentation-only Indicator.
+
+## Use when
+
+- Work is ongoing and users should know either how much is complete or that completion is still indeterminate.
+
+## Choose something else when
+
+- The value is a stable measurement rather than ongoing work, users manipulate the value, or only a short transient completion message is needed. Use the native meter element, Slider, or Toast.
+
+## Required composition
+
+- Give Root a concise accessible name, pass a measurable value for determinate work or null/omit value for indeterminate work, set a truthful range, and add Indicator only as the visual fill. Provide aria-valuetext or getValueLabel when the numeric value needs domain-specific wording.
+
+## Rules
+
+- **MUST:** Give Root an accessible name that identifies the ongoing task, through visible labeling or native ARIA.
+- **MUST:** Use a current numeric value only when progress is measurable; omit it or pass null when indeterminate so aria-valuenow is absent.
+- **MUST:** Supply truthful min and max values and understand that Atom clamps the value and normalizes an invalid max to min plus 100 before exposing ARIA and percent state.
+- **SHOULD:** Provide concise human-readable value text when the numeric range alone does not communicate meaningful completion.
+- **MUST:** Keep Indicator presentation-only and aria-hidden because Root is the sole semantic value owner; do not create a duplicate progressbar or live announcement path.
+- **MUST:** Do not make Progress interactive or keyboard adjustable; use Slider or another input when users control the value.
+
+## Common mistakes
+
+- **Avoid:** Passing zero as a stand-in for unknown progress or using Progress for storage capacity or another static quantity. **Instead:** Use null or omit value for indeterminate work and use the native meter element for a stable measurement.
+- **Avoid:** Putting progressbar semantics on Indicator or announcing every value update through another live region. **Instead:** Keep Root as the single semantic owner and add announcements only when independently justified.
+
+## Validation checklist
+
+- Verify accessible naming, determinate loading and complete states, indeterminate state without aria-valuenow, clamping, invalid-range normalization, data attributes, and percent calculations.
+- Verify explicit aria-valuetext precedence and getValueLabel argument order and output for domain-specific ranges.
+- Confirm Indicator remains aria-hidden, Root owns the only progressbar role, no keyboard interaction is introduced, and asChild or render composition preserves semantics and refs.
+
+## Related guidance
+
+- `native-element (native-application)`
+- `slider`
+- `toast`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "progress",
+  "name": "Progress",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Communicate determinate or indeterminate completion of ongoing work with progressbar semantics, normalized range state, and a presentation-only Indicator.",
+  "useWhen": [
+    "Work is ongoing and users should know either how much is complete or that completion is still indeterminate."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value is a stable measurement rather than ongoing work, users manipulate the value, or only a short transient completion message is needed.",
+      "useInstead": "the native meter element, Slider, or Toast"
+    }
+  ],
+  "composition": [
+    "Give Root a concise accessible name, pass a measurable value for determinate work or null/omit value for indeterminate work, set a truthful range, and add Indicator only as the visual fill. Provide aria-valuetext or getValueLabel when the numeric value needs domain-specific wording."
+  ],
+  "rules": [
+    {
+      "id": "progress-name",
+      "level": "must",
+      "statement": "Give Root an accessible name that identifies the ongoing task, through visible labeling or native ARIA."
+    },
+    {
+      "id": "progress-determinate",
+      "level": "must",
+      "statement": "Use a current numeric value only when progress is measurable; omit it or pass null when indeterminate so aria-valuenow is absent."
+    },
+    {
+      "id": "progress-range",
+      "level": "must",
+      "statement": "Supply truthful min and max values and understand that Atom clamps the value and normalizes an invalid max to min plus 100 before exposing ARIA and percent state."
+    },
+    {
+      "id": "progress-value-text",
+      "level": "should",
+      "statement": "Provide concise human-readable value text when the numeric range alone does not communicate meaningful completion."
+    },
+    {
+      "id": "progress-indicator",
+      "level": "must",
+      "statement": "Keep Indicator presentation-only and aria-hidden because Root is the sole semantic value owner; do not create a duplicate progressbar or live announcement path."
+    },
+    {
+      "id": "progress-readonly",
+      "level": "must",
+      "statement": "Do not make Progress interactive or keyboard adjustable; use Slider or another input when users control the value."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Passing zero as a stand-in for unknown progress or using Progress for storage capacity or another static quantity.",
+      "correction": "Use null or omit value for indeterminate work and use the native meter element for a stable measurement."
+    },
+    {
+      "mistake": "Putting progressbar semantics on Indicator or announcing every value update through another live region.",
+      "correction": "Keep Root as the single semantic owner and add announcements only when independently justified."
+    }
+  ],
+  "validation": [
+    "Verify accessible naming, determinate loading and complete states, indeterminate state without aria-valuenow, clamping, invalid-range normalization, data attributes, and percent calculations.",
+    "Verify explicit aria-valuetext precedence and getValueLabel argument order and output for domain-specific ranges.",
+    "Confirm Indicator remains aria-hidden, Root owns the only progressbar role, no keyboard interaction is introduced, and asChild or render composition preserves semantics and refs."
+  ],
+  "related": [
+    {
+      "kind": "native-application",
+      "id": "native-element"
+    },
+    "slider",
+    "toast"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/radio-group.txt

@@ -0,0 +1,118 @@
+# RadioGroup
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: radio-group
+
+# RadioGroup agent guide
+
+## Purpose
+
+Manage one selected form option with radiogroup semantics, roving focus, orientation-aware keyboard navigation, validation, and optional native submission.
+
+## Use when
+
+- A user must choose exactly one option from a short visible list whose choices are best compared together.
+
+## Choose something else when
+
+- Several choices may be selected, the list is long and should stay compact, or the controls are pressed commands rather than form answers. Use CheckboxGroup, Select, or ToggleGroup.
+
+## Required composition
+
+- Give Root an accessible group name and compose uniquely valued Radio parts with visible or native accessible names. Use name and form for native submission and a Fieldset Legend when the option set needs a visible legend.
+
+## Rules
+
+- **MUST:** Give Root an accessible name with native ARIA or an inherited Fieldset Legend and give every Radio an accessible option name.
+- **MUST:** Use value with onValueChange for controlled state or defaultValue for uncontrolled state, and provide stable unique Radio values.
+- **MUST:** Preserve the selected or first enabled Radio as the single Tab stop, skip disabled Radios, and use Root orientation and direction for Arrow, Home, and End focus and selection behavior.
+- **MUST:** Keep read-only groups focusable and submitted while preventing pointer, Space, and navigation-driven value changes; Arrow navigation may still expose every option by focus.
+- **MUST:** Preserve group-level required validity, first-enabled validation focus, named hidden radio submission, Fieldset integration, and uncontrolled form reset.
+
+## Common mistakes
+
+- **Avoid:** Giving every Radio a Tab stop, omitting the group name, using RadioGroup for independent choices, or disabling a read-only group and losing focus and submission. **Instead:** Use the owned roving radiogroup model, choose CheckboxGroup for independent choices, and use readOnly when the selected value must remain discoverable and submitted.
+
+## Validation checklist
+
+- Verify controlled and uncontrolled selection, Root and Radio naming, one roving Tab stop, disabled skipping, orientation-specific Arrow keys, Home/End, Space, looping, explicit and inherited LTR/RTL, pointer activation, and asChild/render semantics.
+- Verify read-only focus without value changes, required validation with and without a submission name, first-enabled validation focus, inline/native behavior, Fieldset state and descriptions, hidden radio values, and form reset.
+
+## Related guidance
+
+- `checkbox-group`
+- `select`
+- `toggle-group`
+- `fieldset`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "radio-group",
+  "name": "RadioGroup",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Manage one selected form option with radiogroup semantics, roving focus, orientation-aware keyboard navigation, validation, and optional native submission.",
+  "useWhen": [
+    "A user must choose exactly one option from a short visible list whose choices are best compared together."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Several choices may be selected, the list is long and should stay compact, or the controls are pressed commands rather than form answers.",
+      "useInstead": "CheckboxGroup, Select, or ToggleGroup"
+    }
+  ],
+  "composition": [
+    "Give Root an accessible group name and compose uniquely valued Radio parts with visible or native accessible names. Use name and form for native submission and a Fieldset Legend when the option set needs a visible legend."
+  ],
+  "rules": [
+    {
+      "id": "radio-group-name",
+      "level": "must",
+      "statement": "Give Root an accessible name with native ARIA or an inherited Fieldset Legend and give every Radio an accessible option name."
+    },
+    {
+      "id": "radio-group-state",
+      "level": "must",
+      "statement": "Use value with onValueChange for controlled state or defaultValue for uncontrolled state, and provide stable unique Radio values."
+    },
+    {
+      "id": "radio-group-roving",
+      "level": "must",
+      "statement": "Preserve the selected or first enabled Radio as the single Tab stop, skip disabled Radios, and use Root orientation and direction for Arrow, Home, and End focus and selection behavior."
+    },
+    {
+      "id": "radio-group-readonly",
+      "level": "must",
+      "statement": "Keep read-only groups focusable and submitted while preventing pointer, Space, and navigation-driven value changes; Arrow navigation may still expose every option by focus."
+    },
+    {
+      "id": "radio-group-form",
+      "level": "must",
+      "statement": "Preserve group-level required validity, first-enabled validation focus, named hidden radio submission, Fieldset integration, and uncontrolled form reset."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Giving every Radio a Tab stop, omitting the group name, using RadioGroup for independent choices, or disabling a read-only group and losing focus and submission.",
+      "correction": "Use the owned roving radiogroup model, choose CheckboxGroup for independent choices, and use readOnly when the selected value must remain discoverable and submitted."
+    }
+  ],
+  "validation": [
+    "Verify controlled and uncontrolled selection, Root and Radio naming, one roving Tab stop, disabled skipping, orientation-specific Arrow keys, Home/End, Space, looping, explicit and inherited LTR/RTL, pointer activation, and asChild/render semantics.",
+    "Verify read-only focus without value changes, required validation with and without a submission name, first-enabled validation focus, inline/native behavior, Fieldset state and descriptions, hidden radio values, and form reset."
+  ],
+  "related": [
+    "checkbox-group",
+    "select",
+    "toggle-group",
+    "fieldset",
+    "form"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/rating.txt

@@ -0,0 +1,122 @@
+# Rating
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: rating
+
+# Rating agent guide
+
+## Purpose
+
+Choose a value on a small ordered rating scale through one slider-semantic control with decorative whole or fractional item targets.
+
+## Use when
+
+- A user chooses a score on a short ordered scale where each successive item means more of the same quality.
+
+## Choose something else when
+
+- The numeric setting is general-purpose or every choice has a distinct categorical meaning. Use Slider or RadioGroup.
+
+## Required composition
+
+- Give Root an accessible name and render an ordered Item for each visual scale segment with its numeric upper value. Use step and getValueLabel or aria-valuetext for fractional or domain-specific meaning; Items remain decorative while Root is the single control.
+
+## Rules
+
+- **MUST:** Keep Root as the only focusable role=slider control and every Item aria-hidden; do not turn rating symbols into separate radio or button stops.
+- **MUST:** Give Root an accessible name and meaningful aria-valuetext, using getValueLabel when the default value-out-of-maximum wording is insufficient.
+- **MUST:** Use a valid ordered min/max range, positive step, and Item values that represent the visual segments; preserve snapping and partial-fill state for fractional ratings.
+- **MUST:** Keep repeated selection stable by default and enable allowClear only when clearing back to the minimum is an intentional product action.
+- **MUST:** Preserve one-pointer capture, cross-item dragging, vertical page scrolling, cancellation rollback, lost-capture finalization, keyboard steps, and horizontal LTR and RTL behavior.
+- **MUST:** Preserve disabled, read-only, invalid, required-above-minimum validity, Field relationships, named hidden submission, validation focus, and uncontrolled form reset.
+
+## Common mistakes
+
+- **Avoid:** Giving each star a Tab stop, using Rating for unrelated categorical choices, clearing on repeated selection without product intent, or exposing only the numeric value without a meaningful label. **Instead:** Keep one slider control with decorative Items, use RadioGroup for categories, opt into clearing deliberately, and expose understandable value text.
+
+## Validation checklist
+
+- Verify Root name and slider ARIA, whole and fractional controlled/uncontrolled values, snapping, generated and custom value text, decorative Item empty/partial/full fill, Arrow, PageUp/PageDown, Home/End, disabled/read-only state, and LTR/RTL.
+- Verify pointer selection within each segment and across gaps, drag capture, one-pointer ownership, vertical scroll preservation, true cancellation rollback, lost-capture finalization, repeated selection with and without allowClear, required-above-minimum validation, Field integration, hidden form value, and reset.
+
+## Related guidance
+
+- `slider`
+- `radio-group`
+- `field`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "rating",
+  "name": "Rating",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Choose a value on a small ordered rating scale through one slider-semantic control with decorative whole or fractional item targets.",
+  "useWhen": [
+    "A user chooses a score on a short ordered scale where each successive item means more of the same quality."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The numeric setting is general-purpose or every choice has a distinct categorical meaning.",
+      "useInstead": "Slider or RadioGroup"
+    }
+  ],
+  "composition": [
+    "Give Root an accessible name and render an ordered Item for each visual scale segment with its numeric upper value. Use step and getValueLabel or aria-valuetext for fractional or domain-specific meaning; Items remain decorative while Root is the single control."
+  ],
+  "rules": [
+    {
+      "id": "rating-single-control",
+      "level": "must",
+      "statement": "Keep Root as the only focusable role=slider control and every Item aria-hidden; do not turn rating symbols into separate radio or button stops."
+    },
+    {
+      "id": "rating-name-value",
+      "level": "must",
+      "statement": "Give Root an accessible name and meaningful aria-valuetext, using getValueLabel when the default value-out-of-maximum wording is insufficient."
+    },
+    {
+      "id": "rating-scale",
+      "level": "must",
+      "statement": "Use a valid ordered min/max range, positive step, and Item values that represent the visual segments; preserve snapping and partial-fill state for fractional ratings."
+    },
+    {
+      "id": "rating-clear",
+      "level": "must",
+      "statement": "Keep repeated selection stable by default and enable allowClear only when clearing back to the minimum is an intentional product action."
+    },
+    {
+      "id": "rating-pointer-keyboard",
+      "level": "must",
+      "statement": "Preserve one-pointer capture, cross-item dragging, vertical page scrolling, cancellation rollback, lost-capture finalization, keyboard steps, and horizontal LTR and RTL behavior."
+    },
+    {
+      "id": "rating-state-form",
+      "level": "must",
+      "statement": "Preserve disabled, read-only, invalid, required-above-minimum validity, Field relationships, named hidden submission, validation focus, and uncontrolled form reset."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Giving each star a Tab stop, using Rating for unrelated categorical choices, clearing on repeated selection without product intent, or exposing only the numeric value without a meaningful label.",
+      "correction": "Keep one slider control with decorative Items, use RadioGroup for categories, opt into clearing deliberately, and expose understandable value text."
+    }
+  ],
+  "validation": [
+    "Verify Root name and slider ARIA, whole and fractional controlled/uncontrolled values, snapping, generated and custom value text, decorative Item empty/partial/full fill, Arrow, PageUp/PageDown, Home/End, disabled/read-only state, and LTR/RTL.",
+    "Verify pointer selection within each segment and across gaps, drag capture, one-pointer ownership, vertical scroll preservation, true cancellation rollback, lost-capture finalization, repeated selection with and without allowClear, required-above-minimum validation, Field integration, hidden form value, and reset."
+  ],
+  "related": [
+    "slider",
+    "radio-group",
+    "field",
+    "form"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/reorder.txt

@@ -0,0 +1,141 @@
+# Reorder
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: reorder
+
+# Reorder agent guide
+
+## Purpose
+
+Provide accessible manual reordering for one controlled linear collection through drag, keyboard movement, and direct movement controls.
+
+## Use when
+
+- A user deliberately controls the saved order of items in one vertical or horizontal list.
+
+## Choose something else when
+
+- Items are ordered automatically by a data field, query, table header, or server sort rule. Use the collection's sorting API.
+- Movement changes tree parents, table row semantics, Kanban containers, or freeform coordinates. Use a component-specific adapter built on DragDrop.
+
+## Required composition
+
+- Provide Root with stable item identities, getItemLabel, controlled onItemsChange, and one keyed Item for each identity in the same order.
+- Place a labelled Handle and visible MoveBefore/MoveAfter or equivalent movement controls inside every movable Item.
+- Optionally render DropIndicator for styled insertion feedback; keep application content and controls inside each Item.
+
+## Rules
+
+- **MUST:** Treat Root items as the canonical controlled identity order and render Items in that same order.
+- **MUST:** Provide stable identities and human getItemLabel output for instructions and announcements.
+- **MUST:** Include visible direct movement controls so the operation does not require a dragging path.
+- **MUST:** Do not combine active automatic sorting with manual reordering unless the application clearly disables or reconciles one behavior.
+- **SHOULD:** Keep persistence, optimistic updates, Undo, conflicts, validation, and error recovery in the application.
+
+## Common mistakes
+
+- **Avoid:** Using the rendered index as Item value or rendering Items in an order different from Root items. **Instead:** Use durable record IDs and render the controlled identity order exactly.
+- **Avoid:** Showing only a drag handle because keyboard users can also move it. **Instead:** Keep the handle and add visible MoveBefore/MoveAfter or an equally direct simple-pointer alternative.
+- **Avoid:** Using Reorder to change a sorted result set while its sort remains active. **Instead:** Disable reordering or switch the collection to a documented manual-order mode first.
+
+## Validation checklist
+
+- Verify drag, keyboard, and direct-control changes emit the same final identity order and accurate previous/next indices.
+- Verify boundary controls disable correctly and disabled/read-only Items cannot move.
+- Verify focus remains on the same keyed control after re-render, including first/last movement and RTL horizontal order.
+- Verify application persistence failures can be recovered without Atom owning remote state.
+
+## Related guidance
+
+- `drag-drop`
+- `list`
+- `collection`
+- `data-grid`
+- `tree`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "reorder",
+  "name": "Reorder",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide accessible manual reordering for one controlled linear collection through drag, keyboard movement, and direct movement controls.",
+  "useWhen": [
+    "A user deliberately controls the saved order of items in one vertical or horizontal list."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Items are ordered automatically by a data field, query, table header, or server sort rule.",
+      "useInstead": "the collection's sorting API"
+    },
+    {
+      "condition": "Movement changes tree parents, table row semantics, Kanban containers, or freeform coordinates.",
+      "useInstead": "a component-specific adapter built on DragDrop"
+    }
+  ],
+  "composition": [
+    "Provide Root with stable item identities, getItemLabel, controlled onItemsChange, and one keyed Item for each identity in the same order.",
+    "Place a labelled Handle and visible MoveBefore/MoveAfter or equivalent movement controls inside every movable Item.",
+    "Optionally render DropIndicator for styled insertion feedback; keep application content and controls inside each Item."
+  ],
+  "rules": [
+    {
+      "id": "reorder-controlled-order",
+      "level": "must",
+      "statement": "Treat Root items as the canonical controlled identity order and render Items in that same order."
+    },
+    {
+      "id": "reorder-stable-labels",
+      "level": "must",
+      "statement": "Provide stable identities and human getItemLabel output for instructions and announcements."
+    },
+    {
+      "id": "reorder-visible-controls",
+      "level": "must",
+      "statement": "Include visible direct movement controls so the operation does not require a dragging path."
+    },
+    {
+      "id": "reorder-sort-boundary",
+      "level": "must",
+      "statement": "Do not combine active automatic sorting with manual reordering unless the application clearly disables or reconciles one behavior."
+    },
+    {
+      "id": "reorder-application-ownership",
+      "level": "should",
+      "statement": "Keep persistence, optimistic updates, Undo, conflicts, validation, and error recovery in the application."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using the rendered index as Item value or rendering Items in an order different from Root items.",
+      "correction": "Use durable record IDs and render the controlled identity order exactly."
+    },
+    {
+      "mistake": "Showing only a drag handle because keyboard users can also move it.",
+      "correction": "Keep the handle and add visible MoveBefore/MoveAfter or an equally direct simple-pointer alternative."
+    },
+    {
+      "mistake": "Using Reorder to change a sorted result set while its sort remains active.",
+      "correction": "Disable reordering or switch the collection to a documented manual-order mode first."
+    }
+  ],
+  "validation": [
+    "Verify drag, keyboard, and direct-control changes emit the same final identity order and accurate previous/next indices.",
+    "Verify boundary controls disable correctly and disabled/read-only Items cannot move.",
+    "Verify focus remains on the same keyed control after re-render, including first/last movement and RTL horizontal order.",
+    "Verify application persistence failures can be recovered without Atom owning remote state."
+  ],
+  "related": [
+    "drag-drop",
+    "list",
+    "collection",
+    "data-grid",
+    "tree"
+  ]
+}
+```