@flood-md/agent 0.2.11 → 0.2.12

package/dist/materials/guide-installation.md

@@ -1,6 +1,6 @@
-# Installation · 0.2.11
+# Installation · 0.2.12
 
-The commands below target version 0.2.11. Verify registry availability before installation; for local source evaluation, see the tarball instructions at the end of this guide.
+The commands below target version 0.2.12. Verify registry availability before installation; for local source evaluation, see the tarball instructions at the end of this guide.
 
 Use Node.js 22.12 or newer and an existing npm-based React/Next.js project.
 React 18.3/19 is supported; React 19 and Next.js App Router are integration targets.
@@ -15,8 +15,8 @@ repeat installation when you start using another component.
 ## Connect with the CLI
 
 ```sh
-npx @flood-md/cli@0.2.11 init --dry-run
-npx @flood-md/cli@0.2.11 init
+npx @flood-md/cli@0.2.12 init --dry-run
+npx @flood-md/cli@0.2.12 init
 ```
 
 The installer adds exact matching tokens, React and agent packages. It creates
@@ -40,7 +40,7 @@ No Tailwind configuration or font CDN is needed. The foundations profile is dark
 only; legacy theme behavior remains available outside `FloodRoot`.
 
 ```sh
-npx @flood-md/cli@0.2.11 doctor
+npx @flood-md/cli@0.2.12 doctor
 ```
 
 Doctor checks package versions and guide presence, not stylesheet imports or
@@ -50,7 +50,7 @@ reference `flood/DESIGN.md` from its existing instructions.
 ## Manual package installation
 
 ```sh
-npm install --save-exact @flood-md/tokens@0.2.11 @flood-md/react@0.2.11 @flood-md/agent@0.2.11
+npm install --save-exact @flood-md/tokens@0.2.12 @flood-md/react@0.2.12 @flood-md/agent@0.2.12
 ```
 
 Import the stylesheet and use `FloodRoot` as above. Manual installation does not

package/dist/materials/guide-motion.md

@@ -1,10 +1,5 @@
 # Motion
 
-`PageHeader` stays static. Its actions keep their own Flood interaction feedback,
-and container reflow does not animate the title or move focus.
-`AppShell` and `AppTopBar` do not animate layout or scroll position. Sidebar
-and Drawer own their own transitions.
-
 Flood uses short motion to show where an interface changed. Motion follows the
 component's own state and respects the operating system's reduced-motion preference.
 
@@ -43,10 +38,11 @@ behavior of their children. State updates and focus take effect immediately.
 | `FloodRoot` | Applies the motion preference to its scope. Preference changes are immediate. |
 | `Text`, `Heading`, `Kbd`, `VisuallyHidden`, `Blockquote`, `InlineCode`, `IconSlot`, `Label` | Static text and artwork. The containing control owns feedback. |
 | `Stack`, `Inline`, `Surface`, `Divider`, `Container`, `Grid`, `AspectRatio`, `Section`, `Split`, `Center`, `Fieldset` | Stable layout. Children own any appearance or interaction feedback. |
+| `PageHeader`, `AppShell`, `AppTopBar` | Titles, layout and scroll position stay stable during reflow. Actions, Sidebar and Drawer own their interaction feedback. |
 | `ScrollArea`, `ResizablePanels`, `Slider` | Direct pointer tracking. Only scrollbar hover paint eases. Resize, scroll and slider positions stay under the pointer. |
 | `Button`, `IconButton`, `Toggle`, `CopyButton` | Hover paint and short press compression. Toggle holds selected paint. Copy shows its result glyph without resizing the button. |
 | `ButtonGroup`, `ToggleGroup`, `Toolbar`, `OverflowActions`, `BulkActionBar`, `Menubar` | Actions inherit Button and Menu feedback. Joined button surfaces keep their geometry. Bulk actions fade in when available. |
-| `CommandList`, `ListBox`, `Tree`, `NavigationItem`, `NavigationList`, `NavigationTree`, `NavigationGroup`, `Sidebar` | Row paint, disclosure glyphs and optional flyouts. NavigationTree fades in branch content in place and removes it immediately on collapse. Sidebar eases between expanded and rail widths. Focus, route and tree reflow update immediately. |
+| `CommandList`, `ListBox`, `Tree`, `NavigationItem`, `NavigationList`, `NavigationTree`, `NavigationGroup`, `Sidebar` | Row paint, disclosure glyphs and optional flyouts. NavigationTree fades in branch content in place and removes it immediately on collapse. Sidebar eases between expanded and rail widths and truncates its row text to keep it on one line. Its toggle shows a filled keyboard focus state, with the system outline in forced colors. Focus, route and tree reflow update immediately. |
 | `Link`, `Breadcrumb`, `Pagination`, `SkipLink`, `Steps` | Navigation is immediate. Button-style actions and step rows can ease their paint. Skip links appear immediately on focus. |
 | `Tabs`, `SegmentedControl` | Selected paint and, for line tabs, an arriving indicator. Tabs reveal the visible panel with a short fade while selection and focus update immediately. |
 | `Field`, `Input`, `Textarea`, `InputGroup`, `SearchInput`, `PasswordInput`, `NumberInput`, `PinInput`, `DateField`, `TimeField`, `DateRangeField`, `Editable`, `CharacterCount` | Field hover paint and inherited action feedback. Typing, caret, counts, validation and edit-mode focus are immediate. |
@@ -57,13 +53,14 @@ behavior of their children. State updates and focus take effect immediately.
 | `Collapsible`, `Accordion` | Keep the header flush on press, rotate the centered disclosure mark and reveal panel content. Closing immediately hides the panel and restores focus where needed. |
 | `CodeSnippet`, `Card`, `DataList`, `DataListItem`, `FileItem`, `FileList`, `AvatarGroup` | Embedded actions and avatars own motion. Reading order and record layout remain stable. |
 | `Badge`, `DescriptionList`, `Table`, `Image`, `List`, `Figure`, `Metric`, `Timeline`, `ColorSwatch`, `FileMeta` | Static content. Changes to data, labels and supporting media render immediately. |
+| `Sparkline` | Hover briefly strengthens the latest point and area. Data changes render immediately. |
 | `Avatar` | Loaded image eases in within a fixed frame. Fallback text is immediately available. |
-| `DataTable` | Selected row paint and sort chevron rotation. Sorting, pagination and table geometry update immediately. |
-| `Tooltip`, `Popover`, `Menu`, `ContextMenu`, `HoverCard`, `CommandPalette`, `Dialog`, `AlertDialog`, `Drawer`, `ImagePreview` | Anchored entrances follow placement. Modal and edge panels have their own timing. Controls, focus, close and positioning retain their native behavior. |
+| `DataTable` | Selected row paint, chevron rotation and a short height transition for row details. Sorting, pagination and column resize update geometry immediately. |
+| `Tooltip`, `Popover`, `Menu`, `ContextMenu`, `HoverCard`, `CommandPalette`, `Dialog`, `AlertDialog`, `Drawer`, `Sheet`, `ImagePreview` | Anchored entrances follow placement. Modal and edge panels have their own timing. Sheet uses the bottom Drawer entrance. Controls, focus, close and positioning retain their native behavior. |
+| `Spinner`, `Skeleton`, `Progress`, `Meter`, `ToastRegion`, `UploadItem`, `UploadList` | Busy indicators and value fill. A floating toast enters as a card from its placement edge; an inline toast fades in place. Upload compositions inherit the progress and action recipes. Announcements and final values are immediate. |
+| `Alert`, `EmptyState`, `StatusIndicator`, `ErrorSummary` | State and message changes are immediate. Embedded actions keep Button feedback. |
 
 Menu, ContextMenu and title-only navigation flyouts fade in and out where
 discrete top-layer transitions are supported. Dismissal releases focus and
 pointer interaction immediately. When a sibling navigation flyout takes over
 the same rail position, the outgoing panel yields immediately.
-| `Spinner`, `Skeleton`, `Progress`, `Meter`, `ToastRegion`, `UploadItem`, `UploadList` | Busy indicators, value fill and floating toast arrivals. Upload compositions inherit the progress and action recipes. Announcements and final values are immediate. |
-| `Alert`, `EmptyState`, `StatusIndicator`, `ErrorSummary` | State and message changes are immediate. Embedded actions keep Button feedback. |

package/dist/materials/recipe-collection-views.md

@@ -61,7 +61,9 @@ checkboxes with no resulting action.
 
 Selecting projects reveals one shared action bar floating at the viewport bottom. It shows the
 selected count, changes status, confirms archiving and clears the
-selection. Selection spans the filtered client collection across its pages.
+selection. DataTable uses `showSelection={false}` to keep its result range and
+pagination while announcing the selected count without displaying it again.
+Selection spans the filtered client collection across its pages.
 Changing the query resets it. Archiving captures IDs and names before opening
 the confirmation. Cancel keeps the selection and records intact.
 
@@ -70,6 +72,10 @@ records after the optional onUpdateStatus callback accepts the whole operation.
 Reload returns to the declared fixtures. A rejection keeps accepted records and
 selection intact. Retry uses the failed operation's captured IDs and status.
 Dismiss or a deliberate query/selection change abandons its feedback.
+Report results in a floating ToastRegion so the table stays in place.
+Use the default bottom-end placement. Success expires automatically. A failed
+update offers a persistent Retry action. While the selection rail is visible,
+raise the toast above it without changing the table's scroll clearance.
 
 Only one update can run at a time. Pending actions are disabled. If the user
 changes the query or selection while an update is pending, its result still
@@ -113,7 +119,7 @@ export function ProjectSelectionActions({ projects, pending, onUpdate, onClear }
     <VisuallyHidden role="status">{pending ? 'Updating…' : ''}</VisuallyHidden>
     {archive && <AlertDialog
         title={`Archive ${archive.length} ${archive.length === 1 ? 'project' : 'projects'}?`}
-        description={`${archive.map(project => project.name).join(', ')} will move to Archived.`}
+        description={`${archive.map(project => project.name).join(', ')}\n${archive.length === 1 ? 'It' : 'They'} will move to Archived.`}
         confirmLabel="Archive projects"
         cancelLabel="Keep projects"
         open
@@ -129,29 +135,52 @@ export function ProjectSelectionActions({ projects, pending, onUpdate, onClear }
 
 The panel uses the existing floating-surface tokens and a viewport-safe inset.
 It leaves normal document flow and stays centered when the document scrolls.
+Check the table header position and scroll dimensions with zero, one and
+several selected records. A collection that fits should keep fitting on selection.
 BulkActionBar keeps a single pill-shaped row with at most two visible commands
 by default. Lower-priority commands move into More as space shrinks; the host
-does not add a second row of commands. ResizeObserver measures its actual height, and the
-collection reserves enough bottom space for the final rows and pagination to
-scroll above the panel. Keep this measured clearance with the host styles.
+keeps the commands on one row. Budget bottom clearance in the base layout
+using the control height, the panel chrome and the viewport inset. At the end
+of a scroll, the final rows and pagination should be reachable above the panel.
+Keep the scroll area inside the bordered Surface and clip the frame at its
+rounded corners so the table footer cannot cover the outline.
 
 ```css
 .collection-examples { padding-block:var(--flood-sys-space-8); min-inline-size:0; }
 .collection-view-controls { min-inline-size:0; }
 .flood-root .collection-filter-editor { inline-size:min(42rem,calc(100vw - 2rem)); }
 
+.collection-projects {
+  --collection-selection-inset: max(var(--flood-sys-space-4), env(safe-area-inset-bottom));
+  --collection-selection-control-height: var(--flood-sys-control-sm-height);
+  --collection-selection-height: calc(var(--collection-selection-control-height) + 2 * (var(--flood-sys-space-1) + var(--flood-sys-stroke-width)));
+  padding-block-end: calc(var(--collection-selection-inset) + var(--collection-selection-height) + var(--flood-sys-space-2));
+}
+
+@media (pointer: coarse) {
+  .collection-projects {
+    --collection-selection-control-height: max(var(--flood-sys-control-sm-height), var(--flood-sys-size-touch));
+  }
+}
+
+.collection-table-frame {
+  border: var(--flood-sys-stroke-width) solid var(--flood-sys-color-border-decorative);
+  overflow: clip;
+}
+
 .collection-selection-panel {
   position: fixed;
   inset-inline: 0;
-  inset-block-end: max(var(--flood-sys-space-4), env(safe-area-inset-bottom));
+  inset-block-end: var(--collection-selection-inset);
   margin-inline: auto;
   inline-size: min(26rem, calc(100% - 2 * var(--flood-sys-space-4)));
   max-inline-size: calc(100% - 2 * var(--flood-sys-space-4));
   z-index: var(--flood-sys-layer-sticky);
 }
 
-.collection-projects[data-selected="true"] {
-  padding-block-end: calc(var(--collection-selection-height, 0px) + 2 * var(--flood-sys-space-4) + env(safe-area-inset-bottom));
+.flood-root .collection-selection-panel + .flood-toast-region {
+  inset-block-end: calc(var(--collection-selection-inset) + var(--collection-selection-height) + var(--flood-sys-space-2));
+  max-block-size: calc(100dvh - var(--collection-selection-inset) - var(--collection-selection-height) - var(--flood-sys-space-6));
 }
 ```
 
@@ -210,6 +239,9 @@ defines reset scope and supplies canClear for any state held by quickFilters.
 At most two task-important quick properties remain inline; additional properties
 belong inside Filters. Summaries outside the panel name the property and preserve
 any-match meaning. Container width, rather than viewport size, governs reflow.
+The Projects table places its Columns control in CollectionToolbar's `actions`
+slot via DataTable's `toolbar` render function. It shares the tool row with
+search and filters, and the commands wrap as a group in a narrow container.
 
 CollectionViewSwitcher owns the separate accepted-view choice and adaptive
 commands. It reuses Field/Select and Button/OverflowActions with the same size.
@@ -222,7 +254,7 @@ SearchInput, Select, Menu, MultiSelect and SegmentedControl own input/choice beh
 Popover contains the condition draft and Tag removes applied conditions. Button
 and IconButton perform actions. Several view commands use OverflowActions; a
 single command uses Button directly. Field/Fieldset, Grid/Stack/Inline, Dialog,
-AlertDialog and Alert retain their own roles. DataTable/StatusIndicator and
+AlertDialog and ToastRegion retain their own roles. DataTable/StatusIndicator and
 FileList/FileItem/FileMeta demonstrate two result structures. No owner is inserted
 merely to increase its usage count, and no new package atom is needed for layout.
 
@@ -293,7 +325,7 @@ export function readCollectionViews(key:string,schema:CollectionSchema,storage:V
 
 ```tsx
 "use client";
-import {useEffect,useRef,useState,type FormEvent} from 'react';
+import {useEffect,useRef,useState,type FormEvent,type ReactNode} from 'react';
 import {Alert,AlertDialog,Button,CollectionToolbar,CollectionViewSwitcher,Dialog,Field,FilterGroup,IconSlot,Inline,Input,Menu,Select,Stack,Tag,type OverflowAction} from '@flood-md/react';
 import {collectionQueryKey,copyCollectionQuery,parseCollectionQuery,readCollectionViews,type CollectionQuery,type CollectionSchema,type CollectionView,type FilterProperty,type ViewRead,type ViewStorage} from './collection-views-model';
 
@@ -340,13 +372,13 @@ export function AppliedFilterControl({ property, value, onChange }: {
 
 interface CollectionViewControlsProps {
  label:string;schema:CollectionSchema;presets:readonly CollectionView[];
- value:CollectionQuery;onValueChange:(query:CollectionQuery)=>void;storageKey:string;storage?:ViewStorage;
+ value:CollectionQuery;onValueChange:(query:CollectionQuery)=>void;storageKey:string;storage?:ViewStorage;toolbarActions?:ReactNode;
 }
 type NameDraft={kind:'create'|'rename';id?:string;name:string;snapshot:CollectionQuery;error?:string;invalid?:string};
 const inlineFilterLimit = 2;
 
 /** Host recipe: shared behaviour, not a second Flood component implementation. */
-export function CollectionViewControls({label,schema,presets,value,onValueChange,storageKey,storage}:CollectionViewControlsProps){
+export function CollectionViewControls({label,schema,presets,value,onValueChange,storageKey,storage,toolbarActions}:CollectionViewControlsProps){
  const [saved,setSaved]=useState<ViewRead|{state:'loading';views:[]}>({state:'loading',views:[]}),[selectedId,setSelectedId]=useState(presets[0].id);
  const [editing,setEditing]=useState(false),[draft,setDraft]=useState(()=>copyCollectionQuery(value)),[draftError,setDraftError]=useState('');
  const [advancedEditor, setAdvancedEditor] = useState(false);
@@ -435,6 +467,7 @@ export function CollectionViewControls({label,schema,presets,value,onValueChange
   {saved.state==='error'&&<Stack gap="3"><Alert tone="error">Saved views could not be read.</Alert><Inline gap="3"><Button size="sm" variant="subtle" onClick={()=>setReadAttempt(attempt=>attempt+1)}>Retry saved views</Button>{saved.raw!==null&&<Button size="sm" variant="subtle" onClick={exportSnapshot}>Export snapshot</Button>}<Button size="sm" variant="subtle" tone="danger" onClick={()=>{viewInput.current?.focus({preventScroll:true});setConfirmation({kind:'replace'});}}>Replace saved views</Button></Inline></Stack>}
   {operationError&&<Alert tone="error" announcement="polite"><Inline gap="3">{operationError.message}<Button size="sm" variant="ghost" onClick={()=>setOperationError(null)}>Dismiss</Button></Inline></Alert>}
   <CollectionToolbar label={label+' collection toolbar'} searchValue={value.search}
+    actions={toolbarActions}
     onSearchValueChange={search=>onValueChange({...value,search})}
     searchLabel={'Search '+label.toLowerCase()} searchPlaceholder={'Search '+label.toLowerCase()+'…'} clearSearchLabel={'Clear '+label.toLowerCase()+' search'}
     appliedFiltersLabel={label+' applied filters'}
@@ -496,8 +529,8 @@ chosen consumer with actual data and their own chrome.
 
 ```tsx
 "use client";
-import {useEffect,useRef,useState} from 'react';
-import {Alert,Button,DataTable,EmptyState,Field,FileItem,FileList,FloodRoot,Heading,Inline,Select,Stack,StatusIndicator,Tabs} from '@flood-md/react';
+import {useRef,useState} from 'react';
+import {Button,DataTable,EmptyState,Field,FileItem,FileList,FloodRoot,Heading,Select,Stack,StatusIndicator,Surface,Tabs,ToastRegion,type ToastItem} from '@flood-md/react';
 import {SiteHeader} from './site-header';
 import {SiteFooter} from './site-footer';
 import {CollectionViewControls} from './recipes/collection-views';
@@ -532,10 +565,8 @@ export function ProjectCollection({storage,onUpdateStatus}: {
  const [page, setPage] = useState(1);
  const [selection, setSelection] = useState<readonly string[]>([]);
  const [pending, setPending] = useState(false);
- const [feedback, setFeedback] = useState<
-   { kind: 'success'; message: string } |
-   { kind: 'error'; update: ProjectStatusUpdate; message: string } | null
- >(null);
+ const [feedback, setFeedback] = useState<ToastItem | null>(null);
+ const feedbackSequence = useRef(0);
  const inFlight = useRef(false);
  const collection = useRef<HTMLElement>(null);
  const selectionPanel = useRef<HTMLDivElement>(null);
@@ -549,20 +580,6 @@ export function ProjectCollection({storage,onUpdateStatus}: {
  const selectedProjects=rows.filter(project=>selection.includes(project.id));
  const hasSelection = selectedProjects.length > 0;
 
- useEffect(() => {
-   const panel = selectionPanel.current;
-   const host = collection.current;
-   if (!hasSelection || !panel || !host) return;
-   const measure = () => host.style.setProperty('--collection-selection-height', `${panel.getBoundingClientRect().height}px`);
-   measure();
-   const observer = new ResizeObserver(measure);
-   observer.observe(panel);
-   return () => {
-     observer.disconnect();
-     host.style.removeProperty('--collection-selection-height');
-   };
- }, [hasSelection]);
-
  async function updateStatus(proposal: ProjectStatusUpdate) {
    if (inFlight.current) return;
    const update = { ids: [...new Set(proposal.ids)], status: proposal.status };
@@ -580,33 +597,38 @@ export function ProjectCollection({storage,onUpdateStatus}: {
      setSelection(current => current.filter(id => !ids.has(id)));
      setPage(1);
      const result = update.status === 'active' ? 'set active' : update.status;
-     setFeedback({ kind: 'success', message: `${ids.size} ${ids.size === 1 ? 'project' : 'projects'} ${result}.` });
+     setFeedback({ id: String(++feedbackSequence.current), status: 'success', title: `${ids.size} ${ids.size === 1 ? 'project' : 'projects'} ${result}.` });
    } catch {
-     setFeedback({ kind: 'error', update, message: `Couldn’t update ${update.ids.length} ${update.ids.length === 1 ? 'project' : 'projects'}.` });
+     setFeedback({
+       id: String(++feedbackSequence.current),
+       status: 'error',
+       title: `Couldn’t update ${update.ids.length} ${update.ids.length === 1 ? 'project' : 'projects'}.`,
+       action: { label: 'Retry update', onClick: () => {
+         collection.current?.focus({ preventScroll: true });
+         void updateStatus(update);
+       }},
+     });
    } finally {
      inFlight.current = false;
      setPending(false);
    }
  }
 
- return <section ref={collection} tabIndex={-1} className="collection-projects" data-selected={hasSelection || undefined} aria-label="Projects collection"><Stack gap="6">
-  <CollectionViewControls label="Projects" schema={projectSchema} presets={projectPresets} value={query} onValueChange={change} storageKey="flood-project-views-v1" storage={storage}/>
+ return <section ref={collection} tabIndex={-1} className="collection-projects" aria-label="Projects collection"><Stack gap="6">
   {hasSelection&&<div ref={selectionPanel} className="collection-selection-panel"><ProjectSelectionActions projects={selectedProjects} pending={pending} onUpdate={update=>{void updateStatus(update);}} onClear={()=>{
    collection.current?.focus({preventScroll:true});setSelection([]);setFeedback(null);
   }}/></div>}
-  {feedback&&<Alert tone={feedback.kind==='error'?'error':'success'} announcement="polite"><Inline gap="3">
-   {feedback.message}
-   {feedback.kind==='error'&&<Button size="sm" variant="subtle" disabled={pending} onClick={()=>{
-    collection.current?.focus({preventScroll:true});void updateStatus(feedback.update);
-   }}>Retry update</Button>}
-   <Button size="sm" variant="ghost" disabled={pending} onClick={()=>{
-    collection.current?.focus({preventScroll:true});setFeedback(null);
-   }}>Dismiss</Button>
-  </Inline></Alert>}
-  <DataTable caption="Projects" hideCaption minWidth="36rem" selectable pageSize={5} page={page} onPageChange={setPage} selectedIds={selection} onSelectionChange={ids=>{setSelection(ids);setFeedback(null);}} sort={query.sort} onSortChange={sort=>change({...query,sort})}
+  <ToastRegion label="Project updates" items={feedback ? [feedback] : []}
+   onDismiss={id=>setFeedback(current=>current?.id===id?null:current)}/>
+  <Surface padding="0" className="collection-table-frame">
+   <DataTable caption="Projects" hideCaption minWidth="36rem" selectable showSelection={false} pageSize={5} page={page} onPageChange={setPage} selectedIds={selection} onSelectionChange={ids=>{setSelection(ids);setFeedback(null);}} sort={query.sort} onSortChange={sort=>change({...query,sort})}
+   inset="roomy" showColumnVisibility
+   toolbar={({columns}) => <CollectionViewControls label="Projects" schema={projectSchema} presets={projectPresets}
+     value={query} onValueChange={change} storageKey="flood-project-views-v1" storage={storage} toolbarActions={columns}/>}
    emptyContent={<EmptyState title="No matching projects" actions={<Button variant="subtle" onClick={()=>{change({...query,search:'',conditions:[]});collection.current?.querySelector<HTMLInputElement>('.flood-collection-toolbar input')?.focus({preventScroll:true});}}>Reset filters</Button>}/>}
-   columns={[{id:'name',label:'Project',sortable:true},{id:'owner',label:'Owner',sortable:true},{id:'status',label:'Status',sortable:true},{id:'priority',label:'Priority',sortable:true}]}
+   columns={[{id:'name',label:'Project',sortable:true,hideable:false},{id:'owner',label:'Owner',sortable:true},{id:'status',label:'Status',sortable:true},{id:'priority',label:'Priority',sortable:true}]}
    rows={rows.map(project=>({id:project.id,label:project.name,cells:{name:project.name,owner:owners.find(owner=>owner.value===project.owner)!.label,status:<StatusIndicator label={projectSchema.properties[0].options.find(option=>option.value===project.status)!.label} tone={project.status==='active'?'success':project.status==='paused'?'warning':'neutral'}/>,priority:project.priority==='urgent'?'Urgent':'Normal'},sortValues:{name:project.name,owner:project.owner,status:project.status,priority:project.priority==='urgent'?1:0}}))}/>
+  </Surface>
  </Stack></section>;
 }
 

package/dist/materials/recipe-record-management.md

@@ -36,11 +36,11 @@ and filters that share the table surface.
         },
       }]} />
   )}>
-  <Stack gap="6">
-    <Section title="Customer message">
+  <Stack gap="8">
+    <Section title="Customer message" headingLevel={3} headingSize="group">
       <Text as="p">Confirm who should manage member permissions.</Text>
     </Section>
-    <Section title="Assignment">
+    <Section title="Assignment" headingLevel={3} headingSize="group">
       <Field label="Owner">{field => <Input {...field} />}</Field>
     </Section>
   </Stack>
@@ -51,6 +51,20 @@ Use `size="lg"` when long messages and several field groups need the wider
 reading area. Compose the body from Section for separately named content,
 DescriptionList for facts and Fieldset for related controls. Check wrapping and
 scrolling with the longest title and a real footer action before selecting a size.
+Use the group heading size inside a detail Drawer to keep the record name prominent.
+
+When the detail contains line items and a total, use the Table footer to mark
+the summary and keep its amount aligned with the line-item amounts. A row header
+labels the total, and the Table footer supplies the separator and emphasis.
+
+```tsx
+<tfoot>
+  <tr>
+    <th scope="row" colSpan={2}>Total</th>
+    <td data-numeric>{formattedTotal}</td>
+  </tr>
+</tfoot>
+```
 
 ## Keep browsing state and edit state separate
 
@@ -235,7 +249,7 @@ export function RecordManagement() {
           <Surface elevation="raised" padding="4">
             <ScrollArea ref={list} role="region" aria-label="Request results" style={{maxBlockSize: "22rem"}}>
               {results.length > 0
-                ? <DataList aria-label="Requests">
+                ? <DataList aria-label="Requests" className="request-results">
                   {results.map(record => <DataListItem
                     key={record.id}
                     title={record.title}

package/lib/inspect.mjs

@@ -51,6 +51,17 @@ export function inspectRenderedUI(options = {}) {
     return matches.slice(0, limit);
   };
   if(root===document&&document.documentElement.scrollWidth>innerWidth+1)addIssue({id:'layout.page-overflow',target:{tag:'html',id:document.documentElement.id||null,className:document.documentElement.getAttribute('class')||'',label:'Document'},offset:document.documentElement.scrollWidth-innerWidth,message:'The document extends beyond the viewport. Review the actual overflow owner at this text size; dense content can scroll locally. Hiding page overflow does not repair the layout.'});
+  const documentGutter = innerWidth - document.documentElement.clientWidth;
+  const scrollOwner = document.scrollingElement;
+  if (documentGutter > 1 && scrollOwner && scrollOwner.scrollHeight > scrollOwner.clientHeight + 1) {
+    const table = select('.flood-data-table').find(visible);
+    if (table) addIssue({
+      id: 'layout.record-scroll-owner',
+      target: target(table),
+      offset: documentGutter,
+      message: 'A document scrollbar consumes width on this record view. Compare full and filtered views with classic scrollbars. For a full-window workspace, use AppShell content scrolling so changes in row count keep the table edges in place.',
+    });
+  }
   for (const button of select('button.flood-button, button.flood-icon-button')) {
     // Text is inspected outside real icon slots, SVGs and visually hidden names.
     const walker = document.createTreeWalker(button, NodeFilter.SHOW_TEXT);

package/manifest.json

@@ -158,7 +158,7 @@
       "kind": "reference"
     }
   ],
-  "version": "0.2.11",
+  "version": "0.2.12",
   "installedEntry": ".agents/skills/flood-ui/SKILL.md",
   "pathBase": "source is package-relative; target is relative to the host project root"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flood-md/agent",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "type": "module",
   "description": "Versioned Flood design instructions for coding agents.",
   "license": "MIT",

package/references/component-families.md

@@ -89,6 +89,10 @@ override leaves fields and composed controls inconsistent. Keep absolute
 material colors separate from contextual control roles and verify the nearest
 nested owner resets those roles. Preserve accent focus and destructive meaning.
 
+Vertical pill Toolbar keeps one column on a shared center axis. Use named
+icon-only actions and a consistent control size for a compact rail. Use a
+rounded vertical Toolbar with consistently labeled controls when text is needed.
+
 BulkActionBar is a one-row capsule for a small set of selection commands. Keep
 one to three visible commands, prefer two, and disclose the remainder through
 its overflow owner. Do not wrap this floating rail into a second row or use it

package/references/composition.md

@@ -43,6 +43,18 @@ adapter such as @/ui/button may re-export Flood, but does not change React APIs.
 Before handing off, inspect a real composed screen at narrow and wide widths,
 not only isolated controls. See [verification](verification.md).
 
+Choose the scroll owner when laying out a screen. In an application workspace
+with fixed chrome or floating collection actions, use AppShell with
+`scroll="content"`. For a padded workspace, set `scrollContentInset="none"`
+when that prop is available and the existing edge padding clears the rails.
+Use the document as scroll owner for pages designed to flow as one document.
+Apply the workspace recipe to filterable or pageable record queues with floating
+actions even when they have no persistent top bar. Keep viewport-fixed actions
+outside the scrolling content. Table's horizontal ScrollArea handles wide
+columns independently.
+When testing a floating selection bar, select the first row and check that the
+viewport and the table keep the same inline size as the overlay rail appears.
+
 For constrained overflow, use installed ScrollArea when available. Set height or
 maxHeight on its viewport, choose the needed axis, and provide a useful accessible
 name. Rails overlay content with insets; keep essential content out of the rail

package/references/flood-data-display/SKILL.md

@@ -60,6 +60,35 @@ the interface-content workflow for contextual placement.
   Keep identifiers, such as postal codes and account numbers, aligned as text
   even when they contain only digits. Preserve formatted units and use raw sort
   values when localized text or rich cells would sort differently.
+- Offer column visibility when users need different subsets of fields for real
+  tasks in the same table. Leave it off for compact tables with a fixed task.
+  Use one layout control per table. If the screen already has View options or
+  Display settings, put column visibility there and pass `hiddenColumnIds`.
+  Otherwise enable `showColumnVisibility`. If the table already has search and
+  filters, use the `toolbar` render function and put its Columns control in
+  `CollectionToolbar.actions` to share the existing tool row. Keep the record
+  identity visible with `hideable: false` and save preferences by column ID in
+  the host. Keep layout preferences independent of the data query. Verify that
+  visibility changes preserve page, selection and sort.
+- Enable resizing for columns with variable-length content when readers need
+  control over width. Use logical start pinning for record identity and logical
+  end for recurring actions when horizontal scrolling would hide them. Persist
+  widths by column ID with visibility, and verify keyboard resize, reset, RTL
+  and access to the unpinned middle at the smallest intended width.
+- Choose short one-line column labels and use DataTable's `unit` badge for
+  a shared short unit. Preserve the complete label when a narrow column
+  truncates it. Compare the label, sort icon and resize grip on the same row.
+- Use DataTable's row disclosure for short details the reader needs while
+  scanning parent records. Compose a named nested Table for related line items.
+  Keep the disclosure and any record-opening action independent. Use a Drawer
+  or separate page for longer detail or editing tasks.
+- Use Sparkline when the shape of a series helps a comparison. Supply a label
+  that describes the trend, use a shared scale for comparing magnitudes, and
+  show decision-critical numbers as text. If a rich trend cell is sortable,
+  define the metric it sorts by and supply its raw value.
+  Keep the same tone across rows of one metric. A soft area fill supports the
+  stroke and follows the same gaps. Reserve semantic tones for meaning and
+  keep numbers and labels readable independently of color.
 - DescriptionList expresses named values; DataList/DataListItem express records.
   Card/Section/Surface organize groups without inventing a second typography or
   spacing system. A heading's semantic level does not prescribe its visual size.

package/references/flood-feedback/SKILL.md

@@ -35,6 +35,14 @@ visible even when reducing decorative emphasis.
 
 ## Scope feedback to its operation
 
+Use a floating ToastRegion for the result of a discrete action in a collection
+that is still usable. Keep a failed action's toast available while its retry
+is offered, and preserve the operation's captured targets. Start at bottom-end
+and keep the toast clear of selection actions. Use an inline Alert when the message belongs to
+the affected section, for example when a read failure blocks the table itself.
+Keep its action on the same visual axis as the message in a short titleless
+row. Use Flood Button variants so hover and press inherit the Alert tone.
+
 Associate a message with the operation and record that produced it. Preserve
 entered data after refusal and keep a useful error while that operation remains
 unresolved. A successful retry clears/replaces its failure. Explicitly discarding
@@ -48,6 +56,10 @@ that distinction; the feedback primitive only presents the supplied state.
 
 ## Evidence
 
+After a collection action, check that its result is visible at the current
+scroll position and that success, refusal, retry and dismissal leave the
+table header and scroll height in place.
+
 Trigger the operation and observe each applicable transition, including failure
 and retry. Also follow failure → explicit discard → list → reopen a saved record;
 the abandoned draft's failure must be gone and the saved data unchanged. Distinguish

package/references/flood-hierarchy/SKILL.md

@@ -21,6 +21,10 @@ this workflow makes that meaning visible.
 
 - Dialog owns its task heading and the body inset. Its dark title uses the
   dialog-title role (1.25rem / 600); it is distinct from compact popup captions.
+- For independent blocks inside a record Drawer, use Section with
+  `headingSize="group"` when installed. Keep the Drawer title one level stronger
+  visually. Set the semantic heading level separately. Start with a tighter gap
+  from each heading to its content and space-8 between independent sections.
 - Field owns the label-to-control relationship: space-1 (.25rem) in the dark
   profile. DateField/TimeField already use that relationship. Leave room between
   independent fields instead of increasing the gap inside every label/control pair.

package/references/flood-interface-content/SKILL.md

@@ -38,6 +38,13 @@ Do not hide essential instructions or risks behind a tooltip merely
 to make a screen quieter. Preserve accessible names and associations when reducing
 visible copy; use the component's documented hideLabel API where appropriate.
 
+For a bulk confirmation, put the action and its scope first. Use the title for
+the count when it reads naturally there. If the count belongs in the body, give
+it the first sentence. Put a meaningful consequence on a separate line or in a
+separate paragraph. Let each thought wrap naturally on narrow screens. Preserve
+the dialog's accessible description and check singular and plural copy.
+AlertDialog preserves a newline in its string description.
+
 ## Separate prototype provenance from product state
 
 An explicitly requested local prototype or fixture-backed test app does not need

package/references/flood-motion/SKILL.md

@@ -22,6 +22,9 @@ opacity and transform on bounded visual parts. Keep an anchored overlay's
 positioning root stable while a child moves. Animate color only where the old and
 new colors keep required information legible. Keep focus outlines and error
 messages immediate. Apply hover treatment only to devices that can hover.
+For ToastRegion, animate each arriving card as a unit from its placement edge.
+Keep the region anchored and its announcement available as soon as it appears.
+Inline toasts can fade without moving surrounding content.
 Keep compression off disabled controls, text editors and joined control
 surfaces. Verify release and cancellation without a layout shift.
 Treat disclosure headers as part of their enclosing surface. Keep their

package/references/flood-overlays/SKILL.md

@@ -56,6 +56,12 @@ DescriptionList or Fieldset as appropriate. Put the next action in the footer
 when it must stay reachable during scrolling. Avoid repeating the heading
 as a section name or showing two equivalent dismiss actions in a clean state.
 
+Use Sheet when a short touch task, navigation list or option list needs the
+width of the phone. Keep the current choice visible on its trigger and compose
+single-choice options with ListBox. Commit on selection, keep the previous value
+on dismissal, and return focus to the trigger. Use one scrolling body and keep
+long content, the close action and safe-area padding reachable.
+
 Overlay material establishes the nested neutral control context automatically.
 Compare its fields, secondary actions, selection and supporting chips with their
 canvas counterparts. Avoid opaque dark action islands or hiding the entire

package/references/flood-records/SKILL.md

@@ -69,6 +69,29 @@ button provides the keyboard entry. Keep checkbox, links and menus independent.
 For a real destination, preserve a Link. Use the table toolbar and matching
 edge inset when the heading, filters, cells and footer share one surface.
 
+For transient selection commands, look up `recipe:collection-views` in the
+installed catalog. For a full-window record workspace with a changing row count,
+use `AppShell scroll="content" scrollOrientation="vertical"` as the vertical
+scroll owner, including when the page has no app chrome. Keep fixed actions
+outside that ScrollArea. Test a populated view and a filtered or empty view in a
+browser with space-reserving scrollbars. Compare the table's inline edges
+and the document's client width across those views.
+
+Place BulkActionBar in a fixed host centered near the bottom
+of the viewport. Keep the host outside the table toolbar. Budget any needed
+bottom clearance in the base layout so selecting rows preserves both the table
+position and the scroll height. Use `showSelection={false}` when BulkActionBar displays the count.
+The table still announces selection and can show its result range and pagination.
+When a bordered Surface wraps a flush table, apply `overflow: clip` to that
+frame. Keep horizontal scrolling on the table's own ScrollArea. Verify the
+outline at both lower corners with a visible footer and check keyboard focus at
+the frame's edges.
+
+If a detail table's total summarizes its rows, put it in Table's `tfoot`. Use a
+row header for the label and align the amount with the corresponding numeric
+column. The existing footer border separates it from the last item. Use an
+external summary when its scope includes data beyond the table.
+
 Give a queue's summaries only the prominence they earn in the task. If a
 count changes which work to pick up, make the relevant scope clear. If the
 table already exposes the decision, compare a quiet inline count with a

package/references/flood-spacing/SKILL.md

@@ -74,6 +74,13 @@ and compact states. Center an icon-only rail against the full rail, not the
 remainder after a one-sided gutter. A scrollbar appearing must not shift body
 tracks relative to the fixed header/footer. Full-viewport workspaces without
 document overflow must not reserve a document scrollbar strip.
+For a floating action bar, size its host to the actual count, commands and close
+control. Keep the count slot stable across digit changes and bound the panel to
+the viewport. Measure the clearance below the last row with the panel open.
+Compare scroll height, available content width and table position before and
+after selection. Check a viewport where all rows fit and one where the last
+row needs scrolling. Put required clearance in the base layout so selection
+keeps the same scroll geometry.
 Test expanded/compact, missing icons, badges/disclosures, long labels, RTL and
 enlarged text. Measure rendered glyph centers, text starts and action centers
 across distant rows; include the header and footer. Correct the owning primitive

package/rules.json

@@ -131,6 +131,7 @@
       "verify": [
         "320px width",
         "Root 24px and increased text spacing",
+        "Record workspace keeps table edges and document width stable across full, filtered and empty views with classic scrollbars",
         "No glyph shrink or unintended page overflow"
       ]
     },
@@ -418,6 +419,9 @@
       "verify": [
         "Caption, headers and named-value relationships preserved",
         "Row actions remain independent named controls",
+        "When users need column visibility, the table has one layout control in its tool row or existing view settings",
+        "If enabled, column resizing works by pointer and keyboard, pinned edges leave the middle reachable, and resetting layout preserves the query",
+        "Expanded detail remains associated with its parent record and preserves native table semantics",
         "File metadata/status/progress reuse their existing primitives",
         "Test one supplied server page without local slicing/sorting; declare and validate page/dataset selection scope."
       ]