@goflowstate/widget-sdk 0.3.0 → 0.3.2

package/README.md

@@ -156,6 +156,42 @@ Claims are only ever the reader's own, and they are context, not
 authorization. `session.claims` is `null` for members, for PWA guests and
 before the first state arrives.
 
+## Flow feedback (the bug icon)
+
+A flow that calls `CanvasWidget.initSession()` carries the feedback icon with no code of its own.
+While the ring has feedback switched on, the session state says so and the SDK puts a round
+button in the corner of the page. A tap takes a screenshot of the page, then opens a sheet with
+one field. The note is sent through the flow's session to `POST /api/w/:slug/feedback`.
+
+The icon and the sheet take the look of the page they sit on: its fonts, ground, ink, the fill
+and shape of its main button, and its corner radius. To pin a role, set a custom property on
+`:root`:
+
+```css
+:root {
+  --fs-feedback-cta: #5136c4; /* also -cta-ink, -ground, -ink, -font, -font-display, -radius */
+  --fs-feedback-bottom: 96px; /* where the icon sits; also -right */
+}
+```
+
+The button floats over the flow and belongs to the person using it. They can drag it anywhere,
+and it settles on the nearer side. A flick at an edge, or a drag into one, docks it there as a
+slim tab with the bug still showing; a tap on the tab opens the sheet, and pulling the tab
+inward floats it again. The sheet also has a "Tuck the button to the side" link. Where a person
+leaves the button is remembered.
+
+Until a person moves it, the button keeps clear of the page's own controls. It starts in the bottom corner and, whenever
+the page changes, resizes or stops scrolling, looks up the right edge for the lowest spot that is empty. It sits over a line of text only
+when empty space is far above it, and on a control only when the whole edge is controls. Pinning
+`--fs-feedback-bottom` turns that off and holds the icon where the flow puts it.
+
+To take the icon off one screen of a flow (a film, a full-screen picture), set
+`--fs-feedback-display: none` from the flow's stylesheet while that screen is up, for example
+`:root:has(.film) { --fs-feedback-display: none; }`.
+
+Name each screen so a report says where it came from: `document.body.dataset.pageKey = 'question-2'`.
+A page that must not show the icon (a projected wall) sets `<html data-fs-feedback="off">`.
+
 ## Full API Reference
 
 See the [Flowstate developer docs](https://developer.goflowstate.com/docs/) for the complete API reference, the manifest format, the AI integration guide, and the submission pipeline.