@flood-md/agent 0.2.11 → 0.2.13

package/references/flood-visual-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: flood-visual-review
+description: Review rendered Flood UI with Playwright or equivalent browser tooling. Use for visual bugs, screenshot feedback, new or changed UI, and visual regressions across interaction states.
+---
+
+# Review the UI in the browser
+
+Open the actual route or component preview with representative data. For a
+reported issue, reproduce its state with the user's viewport, input and browser
+engine when relevant and available. For a new or changed UI, start with the user's
+main task and exercise the affected states. A visual review request can produce
+findings alone. When implementing a fix, repeat the same interaction after it.
+
+## Capture and inspect
+
+Use the project's Playwright setup or equivalent browser tooling. Reach states
+with clicks, keyboard and scroll. Wait for fonts and the intended stable state
+before a still capture. Keep motion enabled when investigating a jump or flicker;
+use consecutive frames, video or a trace with screenshots. Confirm layout shifts
+with measurements before and after the action when possible.
+
+Save a screenshot of the changed region in its surrounding layout, then open the
+image and inspect it at its intended size. Crop a detail if needed. For a fix,
+capture before and after with the same data, viewport, scroll position and state
+when the original is available. Keep the artifacts in the host's test output or
+another ignored local directory and link the relevant evidence in the handoff.
+
+| Surface | What to exercise and look for |
+| --- | --- |
+| Table or collection | Select and clear rows, apply a filter through to zero results, then open any affected row detail. Compare column tracks, clipping at rounded edges and whether the toolbar, scrollbar or selection actions shift the table. |
+| Drawer, dialog or popup | Inspect the open state with real content, scroll to the last action and close it. Check the rhythm between title, description and body, internal clipping, overlay placement and visible keyboard focus. |
+| Form or navigation | Walk the relevant keyboard path. Compare label/control gaps, peer text and icon axes, long labels and hierarchy. Exercise an affected error, expansion or selection. For failed submit, verify the message is readable during correction and check what receives focus. |
+
+When a workspace changes height, use a browser with classic scrollbars enabled
+and force overflow. Verify that the intended region scrolls. Compare its content
+edges and `innerWidth - document.documentElement.clientWidth` before and after
+filtering. A browser with hidden or overlay system rails can mask the gutter.
+Use the [workspace scroll assertion](../rendered-review.md#require-workspace-scroll-in-browser-tests)
+in both states so the browser test fails if the document takes over scrolling.
+
+Check the affected scope at the normal viewport and at a supported narrow or
+enlarged-text setting when space is part of the risk. Read the rendered copy as
+part of the task. Look for duplicated labels, decorative status and instructions
+that repeat what the surrounding UI already says. Use the existing [rendered
+review observer](../rendered-review.md) for additional clues if available.
+
+## Resolve and verify
+
+For each material finding, record the route and state, the action to reproduce
+it, the visible symptom, and a screenshot or measurement. Start with problems
+that block the task, hide content or confuse the next action. If a bug repeats,
+locate its shared owner using the [component family contract](../component-families.md)
+and check another affected use after the fix.
+
+Use browser assertions for stable invariants such as bounds, focus or scroll
+position. A passing assertion still leaves visual hierarchy, copy and balance
+to inspect. Report the states actually reviewed and any missing evidence. If the
+target cannot run, or images cannot be inspected, say which visual checks remain
+open and report the evidence you could obtain.

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,6 +131,7 @@
       "verify": [
         "320px width",
         "Root 24px and increased text spacing",
+        "The assertWorkspaceScroll browser test passes across populated and empty workspace states with classic scrollbars enabled",
         "No glyph shrink or unintended page overflow"
       ]
     },
@@ -300,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."
       ]
@@ -418,6 +420,11 @@
       "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",
         "File metadata/status/progress reuse their existing primitives",
         "Test one supplied server page without local slicing/sorting; declare and validate page/dataset selection scope."
       ]
@@ -544,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",
@@ -626,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",
@@ -672,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"
       ]
     },
     {
@@ -716,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
     }
   ]
 }