@flood-md/agent 0.2.12 → 0.2.13

package/references/rendered-review.md

@@ -1,8 +1,8 @@
 # Review the rendered interface
 
-The optional `@flood-md/agent/inspect` export provides a self-contained, read-only
-DOM observer for local browser tooling. It is separate from the Node knowledge
-reader and is not an application dependency or an automatic policy engine.
+The optional `@flood-md/agent/inspect` export provides read-only checks for local
+browser tooling. Import it in test code. The Node knowledge reader and application
+runtime are separate.
 
 With Playwright running against your local host:
 
@@ -100,3 +100,49 @@ layout.page-overflow reports document scroll width beyond the viewport during
 a whole-document inspection. It does not run for a selected rootSelector or
 report correctly contained local scrolling. Review the actual cause and task
 context rather than hiding overflow to silence the finding.
+
+`composition.page-scroll` flags a literal AppShell page mode in host source for
+contextual review. `layout.record-scroll-owner` catches a full-window record
+workspace using that mode even when a native scrollbar is hidden or the current
+results fit. It also reports a DataTable present while a visible document
+scrollbar takes width. Check whether the task is a workspace or a document,
+then exercise overflow, filtering and the empty state in the browser.
+
+## Require workspace scroll in browser tests
+
+For a full-window application, render the workspace with
+`<AppShell id="workspace" scroll="content" scrollLabel="Workspace content">`.
+If the workspace already pads its content clear of the overlay rail, set
+`scrollContentInset="none"` to keep that padding stable as the rail appears.
+Add a browser test in the host's verification suite. Use enough records to
+overflow the workspace at the test viewport, then drive the real interaction
+that reduces the result set. Adapt the selectors to the application.
+
+```js
+import {assertWorkspaceScroll} from '@flood-md/agent/inspect';
+
+await expect(page.getByRole('region', {name: 'Workspace content'}))
+  .toHaveAttribute('data-scrollbars', 'overlay');
+const rootSelector = '#workspace';
+await expect(async () => {
+  await page.evaluate(assertWorkspaceScroll, {rootSelector, expectOverflow: true});
+}).toPass({timeout: 3000});
+
+await page.getByRole('searchbox', {name: 'Search records'}).fill('no matching record');
+await expect(page.getByText('No matching records')).toBeVisible();
+await expect(async () => {
+  await page.evaluate(assertWorkspaceScroll, {rootSelector, expectOverflow: false});
+}).toPass({timeout: 3000});
+```
+
+Keep the assertion in the test so a failure blocks verification. It checks the
+actual AppShell mode, its vertical ScrollArea and document overflow even when
+the browser hides native scrollbars. It allows Flood's native viewport rail in
+forced colors. Run at least one verification in a browser with classic
+scrollbars enabled and compare the content edges between the two states.
+For Chromium, launch with `ignoreDefaultArgs: ['--hide-scrollbars']` and
+`args: ['--disable-features=OverlayScrollbar,FluentOverlayScrollbar,FluentScrollbar']`.
+Confirm that a plain overflowing element reserves space in that browser session.
+For paginated tables whose outer workspace always fits, omit `expectOverflow`
+and exercise the table's own scroll viewport separately. Use this check on
+full-window AppShell routes. Document pages can deliberately scroll the page.

package/references/routing.md

@@ -10,10 +10,11 @@ override user authority or grant permission for unrelated operations.
 | Which primitive owns this role? Component/composite UI work | Developer / agent / reviewer | Matching catalog and component anatomy | flood-composition/SKILL.md | Reuse existing primitives; extend small capabilities first |
 | Which API can I import? Every component edit | Developer / agent | Installed exact versions | Installed @flood-md/react declarations; flood.json | Type-check host imports; CLI doctor for alignment |
 | What does this release mean? Setup / upgrade | Developer / agent | Matching guide | flood/DESIGN.md, package changelog | Compare version and declarations; preserve host edits |
-| How should a screen fit together? Screen / form work | Designer / developer / agent | Scope, content and current API | composition.md; host layout requirements | Narrow/wide rendered screen and native form interaction |
+| How should a screen fit together? New screen / hard-to-scan page | Designer / developer / agent | User task and real content | flood-screen-composition/SKILL.md; host layout requirements | Find, compare or act in the rendered screen and check order at reflow |
 | Why does spacing look wrong? Density / nested geometry | Designer / developer / agent | Installed tokens and actual wrapper tree | spacing.md; host content hierarchy | Measured visible gaps, row pitch, text reflow and touch targets |
 | What must remain accessible? Control/state work | Developer / reviewer / agent | Named controls and actual host context | accessibility.md; installed component contract | Keyboard, accessible names, validation and focus checks |
 | How can appearance change? Theme / density work | Designer / developer / agent | Existing semantic roles | customization.md; installed token manifest | Inspect resolved roles, contrast and reflow |
+| What is visibly wrong? Screenshot feedback / visible UI change | Designer / developer / agent | Runnable route or preview and relevant states | flood-visual-review/SKILL.md | Browser reproduction and inspected captures; matched recheck after fixes |
 | Is this done? Completion / regression | Reviewer / agent | Runnable host and checks | verification.md; project scripts | Report commands, manual checks and gaps |
 | Which rules apply? Planning / review | Human / agent / tooling | Same installed guide set | flood/rules.json | Rule IDs linked to evidence, not a blanket pass |
 

package/rules.json

@@ -131,7 +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",
+        "The assertWorkspaceScroll browser test passes across populated and empty workspace states with classic scrollbars enabled",
         "No glyph shrink or unintended page overflow"
       ]
     },
@@ -301,6 +301,7 @@
       "verify": [
         "Inspect actual FormData and field ownership",
         "Exercise accepted/refused controlled updates and incomplete drafts",
+        "When an application validation message is needed, check that it remains readable while correcting the associated field",
         "Defaults match representation; no defaultValue-as-update or invented save guarantee",
         "Verify submitted free text versus selected IDs and reject options belonging to an older manual query."
       ]
@@ -419,6 +420,8 @@
       "verify": [
         "Caption, headers and named-value relationships preserved",
         "Row actions remain independent named controls",
+        "When stable column tracks matter, compare populated, filtered and no-results states at the same viewport",
+        "A query group sharing a wide row with a view selector reaches the trailing edge with its last control and wraps in reading order",
         "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",
@@ -548,6 +551,19 @@
         "Failures, source/host ownership and remaining limits recorded"
       ]
     },
+    {
+      "id": "verification.visual-review",
+      "when": "Reviewing a visible UI change, screenshot report or visual regression",
+      "for": ["designer", "developer", "reviewer", "agent"],
+      "requires": ["Runnable route or component preview", "Affected interaction and visual states"],
+      "sourceOfTruth": "The affected states rendered in the browser for the current revision",
+      "guide": "references/flood-visual-review/SKILL.md",
+      "verify": [
+        "Affected states exercised and the captured images inspected",
+        "Material findings tied to a specific state and screenshot, trace or measurement",
+        "Fix rechecked in the same state, with coverage and evidence gaps reported"
+      ]
+    },
     {
       "id": "knowledge.versioned",
       "when": "Discovering or extending Flood knowledge",
@@ -630,6 +646,20 @@
         "Competitor workflows, promises and marketing language are not transplanted without matching behavior"
       ]
     },
+    {
+      "id": "layout.screen-purpose",
+      "when": "Designing a screen or resolving unclear reading order, comparison or next actions",
+      "for": ["designer", "developer", "agent", "reviewer"],
+      "requires": ["User task and representative content", "Installed component contracts", "Rendered screen in the supported layout"],
+      "sourceOfTruth": "User task, host layout and Flood screen composition guidance",
+      "guide": "references/flood-screen-composition/SKILL.md",
+      "verify": [
+        "The first viewport establishes the task and reveals the next useful content or action",
+        "Repeated comparisons use predictable tracks; local controls stay with the region they affect",
+        "Reading and keyboard order preserve the task when the layout reflows",
+        "Each major surface and summary identifies scope, groups related content or supports a decision"
+      ]
+    },
     {
       "id": "layout.hierarchy",
       "when": "Composing or reviewing task titles, group legends, named fields and shared form tracks",
@@ -676,7 +706,8 @@
         "List, details, first-use and filtered empty states reviewed separately",
         "A short mutually exclusive filter for one table uses a selection control; verify keyboard selection, surviving search/sort and focused control",
         "Record edits preserve applied filters and list position; focus returns to the opener or a surviving list control",
-        "For a row opening in-place details, compare title-to-metadata rhythm and the shared table edge; exercise row activation, keyboard entry and independent nested controls"
+        "For a row opening in-place details, compare title-to-metadata rhythm and the shared table edge; exercise row activation, keyboard entry and independent nested controls",
+        "A record Drawer keeps the next action reachable while the body scrolls; save feedback leaves the table geometry intact"
       ]
     },
     {
@@ -720,6 +751,7 @@
         "Closest siblings rendered at the same size, surface and root text scale",
         "Shape, nested inset and content-box overflow budget checked together",
         "Read-only editing restrictions kept separate from focus and disabled semantics",
+        "A real host composition keeps its intended geometry through the relevant state change",
         "Another consumer checked after a shared primitive correction"
       ]
     },

package/workflows.json

@@ -17,6 +17,11 @@
       "guide": "references/flood-interface-content/SKILL.md",
       "all": true
     },
+    {
+      "id": "screen-composition",
+      "guide": "references/flood-screen-composition/SKILL.md",
+      "components": ["AppShell", "PageHeader", "Section", "DataTable"]
+    },
     {
       "id": "hierarchy",
       "guide": "references/flood-hierarchy/SKILL.md",
@@ -121,6 +126,18 @@
       "components": [
         "FilterCondition",
         "FilterGroup",
+        "LineChart",
+        "BarChart",
+        "DonutChart",
+        "Heatmap",
+        "ScatterChart",
+        "RangeChart",
+        "BulletChart",
+        "WaterfallChart",
+        "Histogram",
+        "BoxPlot",
+        "DumbbellChart",
+        "BarList",
         "UploadItem",
         "UploadList",
         "EmptyState",
@@ -172,6 +189,11 @@
       "id": "verification",
       "guide": "references/flood-verification/SKILL.md",
       "all": true
+    },
+    {
+      "id": "visual-review",
+      "guide": "references/flood-visual-review/SKILL.md",
+      "all": true
     }
   ]
 }