@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/segmented-control/README.md

@@ -28,12 +28,12 @@ Toggle button row for switching between a small set of mutually exclusive option
 | `id`                     | `string`                       | yes      | —       | Unique identifier for the control.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `label`                  | `string`                       | yes      | —       | Accessible label for the group.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `orientation`            | `"horizontal"` \| `"vertical"` | no       | —       | Layout orientation.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `selectionMode`          | `"single"` \| `"multiple"`     | no       | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `selectionMode`          | `"single"` \| `"multiple"`     | no       | —       | Selection mode. `"single"` allows exactly one segment to be selected at a time; `"multiple"` allows any number of segments to be selected simultaneously. Default `"single"`.                                                                                                                                                                                                                                                                                                  |
 | `size`                   | `"sm"` \| `"md"` \| `"lg"`     | no       | —       | Requested visual size of the control. Defaults to `"md"`. The resolved size is reflected as `data-cinder-size` on the root; when `density="toolbar"` is set, the resolved size is forced to `"sm"` and any explicit `size` value is ignored. `size="md"` option text uses `--cinder-text-sm`; `size="sm"` and `density="toolbar"` use `--cinder-text-xs`; `size="lg"` uses `--cinder-text-sm`.                                                                                 |
 | `variant`                | `"radiogroup"` \| `"tablist"`  | no       | —       | ARIA interaction pattern. Use `tablist` when options switch visible panels.                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `children`               | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                     |
-| `onchange`               | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                     |
-| `value`                  | `(opaque)`                     | no       | —       | A generically typed prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                       |
+| `children`               | `(opaque)`                     | yes      | —       | Child `<Segment>` elements. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                         |
+| `onchange`               | `(opaque)`                     | no       | —       | Called when the selected value changes (single mode only). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                          |
+| `value`                  | `(opaque)`                     | no       | —       | Currently selected value. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                           |
 
 <!-- generated:props:end -->
 

package/src/components/segmented-control/segmented-control.css

@@ -261,6 +261,23 @@
     box-shadow: var(--cinder-shadow-sm);
   }
 
+  /* For the default pill variant: the `[data-cinder-selected]` rule (specificity
+   * 0,1,0) is declared after `:focus-visible` (0,1,0) and wins by cascade order,
+   * replacing the focus ring's box-shadow with shadow-sm. Re-assert the ring so
+   * the selected+focused segment still shows a visible ring in single and multiple
+   * selection modes. Scope to :not([data-cinder-variant='tablist']) so this does
+   * not conflict with the tablist re-assert below.
+   * Specificity 0,3,0 beats the base shadow-sm rule's 0,2,0 — intentional. */
+  .cinder-segmented-control:not([data-cinder-variant='tablist'])
+    .cinder-segmented-control-option[data-cinder-selected]:focus-visible,
+  .cinder-segmented-control:not([data-cinder-variant='tablist'])
+    .cinder-segmented-control-option[data-cinder-pressed]:focus-visible {
+    box-shadow:
+      0 0 0 var(--cinder-ring-offset) var(--cinder-ring-offset-color),
+      0 0 0 calc(var(--cinder-ring-offset) + var(--cinder-ring-width)) var(--cinder-ring-color);
+    z-index: 1;
+  }
+
   /* ── Tablist variant (single mode only) ─────────────────────────────────────
  * See docs/decisions/segmented-control-tablist-variant.md. The tablist variant
  * carries tab semantics for externally owned panels, so it must read as a

package/src/components/segmented-control/segmented-control.types.ts

@@ -62,6 +62,7 @@ type CommonProps<T extends string> = Omit<
 };
 
 type SingleProps<T extends string> = CommonProps<T> & {
+  /** Selection mode. `"single"` allows exactly one segment to be selected at a time; `"multiple"` allows any number of segments to be selected simultaneously. Default `"single"`. */
   selectionMode?: 'single' | undefined;
   /** Currently selected value. */
   value?: T | undefined;
@@ -73,6 +74,7 @@ type SingleProps<T extends string> = CommonProps<T> & {
 };
 
 type MultipleProps<T extends string> = CommonProps<T> & {
+  /** Selection mode. `"single"` allows exactly one segment to be selected at a time; `"multiple"` allows any number of segments to be selected simultaneously. Default `"single"`. */
   selectionMode: 'multiple';
   /** Set of selected values. Must be a SvelteSet for reactivity. */
   value?: SvelteSet<T> | undefined;

package/src/components/select/README.md

@@ -16,17 +16,17 @@ Native-style dropdown select for choosing a single option from a predefined list
 
 <!-- generated:props:start -->
 
-| Prop          | Type       | Required | Default | Description                                                                                                              |
-| ------------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `description` | `string`   | no       | —       | Helper text rendered below the control; wired via `aria-describedby`.                                                    |
-| `disabled`    | `boolean`  | no       | —       | Disables the control.                                                                                                    |
-| `error`       | `string`   | no       | —       | Validation error message; sets `aria-invalid="true"` and is wired via `aria-describedby`.                                |
-| `id`          | `string`   | yes      | —       | Unique identifier — required for label association and ARIA wiring.                                                      |
-| `label`       | `string`   | no       | —       | Visible label rendered in a `<label>` associated via `for`.                                                              |
-| `required`    | `boolean`  | no       | —       | Marks the control required and sets the native `required` attribute.                                                     |
-| `class`       | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                  |
-| `options`     | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                  |
-| `value`       | `(opaque)` | no       | —       | A generically typed prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop          | Type       | Required | Default | Description                                                                                                                                           |
+| ------------- | ---------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description` | `string`   | no       | —       | Helper text rendered below the control; wired via `aria-describedby`.                                                                                 |
+| `disabled`    | `boolean`  | no       | —       | Disables the control.                                                                                                                                 |
+| `error`       | `string`   | no       | —       | Validation error message; sets `aria-invalid="true"` and is wired via `aria-describedby`.                                                             |
+| `id`          | `string`   | yes      | —       | Unique identifier — required for label association and ARIA wiring.                                                                                   |
+| `label`       | `string`   | no       | —       | Visible label rendered in a `<label>` associated via `for`.                                                                                           |
+| `required`    | `boolean`  | no       | —       | Marks the control required and sets the native `required` attribute.                                                                                  |
+| `class`       | `(opaque)` | no       | —       | Extra class names merged with `.cinder-select-field`. Not expressible in JSON Schema; see the component types for the signature.                      |
+| `options`     | `(opaque)` | yes      | —       | Options to render as `<option>` children. The sole inference source for T. Not expressible in JSON Schema; see the component types for the signature. |
+| `value`       | `(opaque)` | no       | —       | Bound selected value. `undefined` when nothing is selected. Not expressible in JSON Schema; see the component types for the signature.                |
 
 <!-- generated:props:end -->
 

package/src/components/select/select.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic select",
       "description": "Native select with label and bound string value.",
-      "code": "<script lang=\"ts\">\n  import { Select } from '@lostgradient/cinder/select';\n  const options = [\n    { value: 'us', label: 'United States' },\n    { value: 'ca', label: 'Canada' },\n    { value: 'gb', label: 'United Kingdom' },\n    { value: 'au', label: 'Australia' },\n  ];\n\n  let country = $state(options[0]?.value ?? 'us');\n</script>\n\n<Select id=\"country\" bind:value={country} {options} label=\"Country\" />\n<p style=\"margin-top: 0.5rem; color: var(--cinder-text-muted);\">Selected: {country}</p>\n"
+      "code": "<script lang=\"ts\">\n  import { Select } from '@lostgradient/cinder/select';\n\n  const options = [\n    { value: 'us', label: 'United States' },\n    { value: 'ca', label: 'Canada' },\n    { value: 'gb', label: 'United Kingdom' },\n    { value: 'au', label: 'Australia' },\n  ];\n\n  let country = $state(options[0]?.value ?? 'us');\n</script>\n\n<Select id=\"field\" bind:value={country} {options} label=\"Country\" />\n<p style=\"margin-top: 0.5rem; color: var(--cinder-text-muted);\">Selected: {country}</p>\n"
     },
     {
       "id": "disabled-option",
@@ -20,6 +20,12 @@
       "title": "Typed options with as const",
       "description": "Use `as const` on the options array to infer a precise literal-union type for `T`. TypeScript then rejects any `value` that is not a member of the union at compile time.",
       "code": "<script lang=\"ts\">\n  import { Select } from '@lostgradient/cinder/select';\n\n  // `as const` narrows value types to the literal union 'us' | 'ca' | 'gb' | 'au'.\n  // T is inferred from `options`; passing value=\"invalid\" would be a compile error.\n  const options = [\n    { value: 'us', label: 'United States' },\n    { value: 'ca', label: 'Canada' },\n    { value: 'gb', label: 'United Kingdom' },\n    { value: 'au', label: 'Australia' },\n  ] as const;\n\n  type CountryCode = (typeof options)[number]['value'];\n  let country = $state<CountryCode>('us');\n</script>\n\n<Select id=\"country-typed\" bind:value={country} {options} label=\"Country\" />\n<p style=\"margin-top: 0.5rem; color: var(--cinder-text-muted);\">Selected: {country}</p>\n"
+    },
+    {
+      "id": "with-error",
+      "title": "Select with an error",
+      "description": "A required Select whose placeholder is still selected is invalid: pass a non-empty `error` string to mark it. The control gets `aria-invalid=\"true\"`, the message is wired via `aria-describedby`, and a danger ring replaces the focus ring when the invalid control is focused.",
+      "code": "<script lang=\"ts\">\n  import { Select } from '@lostgradient/cinder/select';\n\n  // A `disabled` placeholder paired with `required` is the accessible pattern for\n  // a \"must pick one\" Select: the empty value can be the initial state but cannot\n  // be re-selected, and native constraint validation agrees with the `error` prop.\n  const options = [\n    { value: '', label: 'Select a plan…', disabled: true },\n    { value: 'free', label: 'Free' },\n    { value: 'pro', label: 'Pro' },\n    { value: 'enterprise', label: 'Enterprise' },\n  ];\n\n  let plan = $state('');\n</script>\n\n<Select\n  id=\"plan-error\"\n  bind:value={plan}\n  {options}\n  label=\"Plan\"\n  required\n  error=\"Choose a plan to continue.\"\n/>\n"
     }
   ]
 }

package/src/components/selection-popover/README.md

@@ -2,7 +2,7 @@
 
 A floating toolbar that appears near a text selection and offers a comment-on-selection action with an inline composer. The component uses fixed-position Floating UI geometry, so the supplied selection anchor can flip or shift when it is near a viewport edge.
 
-## When to use
+## Choosing this component
 
 Use `SelectionPopover` when you want readers to annotate or comment on a highlighted range of text — for example, in a document editor, review tool, or article surface. It is designed specifically for selection-scoped actions. For generic floating content or popovers unrelated to text selection, use the `Popover` component instead.
 
@@ -18,7 +18,7 @@ const rect =
   Array.from(range.getClientRects()).find((clientRect) => {
     return clientRect.width > 0 && clientRect.height > 0;
   }) ?? range.getBoundingClientRect();
-position = { x: rect.left + rect.width / 2, y: rect.top };
+position = { x: rect.left + rect.width / 2, y: rect.top, height: rect.height };
 ```
 
 The component treats that point as a Floating UI virtual anchor, not as the panel's top-left corner. It prefers an above-selection placement, but shifts or flips near viewport edges. Coordinates are **not** relative to a containing element — do not pass offsetLeft/offsetTop or any container-relative value.
@@ -68,7 +68,7 @@ The component treats that point as a Floating UI virtual anchor, not as the pane
         position = null;
         return;
       }
-      position = { x: rect.left + rect.width / 2, y: rect.top };
+      position = { x: rect.left + rect.width / 2, y: rect.top, height: rect.height };
       isOpen = true;
     }
 
@@ -104,16 +104,16 @@ The component treats that point as a Floating UI virtual anchor, not as the pane
 
 <!-- generated:props:start -->
 
-| Prop              | Type       | Required | Default | Description                                                                                                                |
-| ----------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`           | `string`   | no       | —       | Additional class names merged with `.cinder-selection-popover`.                                                            |
-| `id`              | `string`   | yes      | —       | Unique identifier for the popover.                                                                                         |
-| `open`            | `boolean`  | no       | —       | Whether the popover is visible.                                                                                            |
-| `oncancel`        | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onclose`         | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `oncommentsubmit` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onexpand`        | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `position`        | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
+| Prop              | Type       | Required | Default | Description                                                                                                                          |
+| ----------------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `class`           | `string`   | no       | —       | Additional class names merged with `.cinder-selection-popover`.                                                                      |
+| `id`              | `string`   | yes      | —       | Unique identifier for the popover.                                                                                                   |
+| `open`            | `boolean`  | no       | —       | Whether the popover is visible.                                                                                                      |
+| `oncancel`        | `(opaque)` | no       | —       | Called when the composer is canceled. Not expressible in JSON Schema; see the component types for the signature.                     |
+| `onclose`         | `(opaque)` | no       | —       | Called when the popover should close. Not expressible in JSON Schema; see the component types for the signature.                     |
+| `oncommentsubmit` | `(opaque)` | no       | —       | Called when a comment is submitted. Not expressible in JSON Schema; see the component types for the signature.                       |
+| `onexpand`        | `(opaque)` | no       | —       | Called when the compact action expands into the composer. Not expressible in JSON Schema; see the component types for the signature. |
+| `position`        | `(opaque)` | yes      | —       | Viewport-relative anchor point for the popover. Not expressible in JSON Schema; see the component types for the signature.           |
 
 <!-- generated:props:end -->
 

package/src/components/selection-popover/selection-popover.examples.json

@@ -7,19 +7,19 @@
       "id": "basic",
       "title": "Selection-driven comment popover",
       "description": "Highlight text in the passage below to trigger the popover at the selection anchor. Position is viewport-relative geometry derived from the selected range.",
-      "code": "<script lang=\"ts\">\n  import { onMount } from 'svelte';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  type Comment = { id: string; body: string };\n\n  const popoverId = 'basic-selection-popover';\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let comments = $state<Comment[]>([]);\n\n  /**\n   * A bound reference to the text surface element.\n   * Used in the document-level selectionchange handler to scope\n   * selection detection to this element's subtree.\n   */\n  let surfaceElement = $state<HTMLElement | null>(null);\n\n  /**\n   * Compute a viewport-relative anchor from the current Selection.\n   * Returns null when there is no non-collapsed selection inside the surface.\n   */\n  function getSelectionAnchor(surface: HTMLElement): SelectionPopoverPosition | null {\n    const selection = window.getSelection();\n    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return null;\n\n    const range = selection.getRangeAt(0);\n    if (!surface.contains(range.commonAncestorContainer)) return null;\n\n    const rect =\n      Array.from(range.getClientRects()).find((clientRect) => {\n        return clientRect.width > 0 && clientRect.height > 0;\n      }) ?? range.getBoundingClientRect();\n\n    if (rect.width === 0 && rect.height === 0) return null;\n\n    return {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n    };\n  }\n\n  /**\n   * `selectionchange` fires on document, not on elements.\n   * Register at document level and scope to the surface via\n   * the bound surfaceElement reference.\n   *\n   * Guard: when the selection collapses because the user clicked inside the\n   * popover (e.g. the \"Add comment\" button or the textarea), do NOT close the\n   * popover mid-interaction.  Two checks mirror the production review-editor\n   * pattern:\n   *\n   *   1. Focus containment — document.activeElement is inside the popover root.\n   *      Covers the common case and all non-Safari browsers.\n   *\n   *   2. data-cinder-expanded attribute — the SelectionPopover component sets\n   *      this on its root element while the comment form is open.  Safari does\n   *      not move focus to buttons on click, so the focus check alone would\n   *      miss that case.\n   */\n  onMount(() => {\n    function handleSelectionChange(): void {\n      if (!surfaceElement) return;\n\n      // Don't close the popover while the user is interacting with it.\n      const popoverElement = document.getElementById(popoverId);\n      if (popoverElement?.contains(document.activeElement)) return;\n      if (popoverElement?.hasAttribute('data-cinder-expanded')) return;\n\n      const anchor = getSelectionAnchor(surfaceElement);\n      if (anchor) {\n        position = anchor;\n        isOpen = true;\n      } else {\n        isOpen = false;\n        position = null;\n      }\n    }\n\n    document.addEventListener('selectionchange', handleSelectionChange);\n    return () => document.removeEventListener('selectionchange', handleSelectionChange);\n  });\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function addComment(body: string): void {\n    comments = [...comments, { id: crypto.randomUUID(), body }];\n    handleClose();\n  }\n</script>\n\n<article\n  bind:this={surfaceElement}\n  style=\"max-width: 36rem; line-height: 1.6; user-select: text; cursor: text;\"\n>\n  <p style=\"margin: 0 0 0.75rem;\">\n    The <strong>SelectionPopover</strong> appears near highlighted text — its\n    <code>position</code> prop takes viewport-relative coordinates derived from\n    <code>Range.getClientRects()</code>, not local container offsets. Select any portion of this\n    paragraph to see it appear near your selection.\n  </p>\n  <p style=\"margin: 0;\">\n    Clicking the comment icon expands the composer. Submit with the send button or\n    <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>Enter</kbd>. Clicking outside the popover closes it and\n    resets the popover state.\n  </p>\n</article>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={addComment}\n/>\n\n{#if comments.length > 0}\n  <section style=\"margin: 1rem 0 0;\" aria-label=\"Submitted comments\">\n    <h3\n      style=\"margin: 0 0 0.5rem; font-size: var(--cinder-text-xs); font-weight: var(--cinder-font-medium); color: var(--cinder-text-muted); text-transform: uppercase; letter-spacing: 0.04em;\"\n    >\n      Submitted comments\n    </h3>\n    {#each comments as comment (comment.id)}\n      <article\n        style=\"padding: 0.5rem 0.75rem; margin-bottom: 0.375rem; border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-sm); background: var(--cinder-surface);\"\n      >\n        {comment.body}\n      </article>\n    {/each}\n  </section>\n{/if}\n"
+      "code": "<script lang=\"ts\">\n  import { onMount } from 'svelte';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  type Comment = { id: string; body: string };\n\n  const popoverId = 'basic-selection-popover';\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let comments = $state<Comment[]>([]);\n\n  /**\n   * A bound reference to the text surface element.\n   * Used in the document-level selectionchange handler to scope\n   * selection detection to this element's subtree.\n   */\n  let surfaceElement = $state<HTMLElement | null>(null);\n\n  /**\n   * Compute a viewport-relative anchor from the current Selection.\n   * Returns null when there is no non-collapsed selection inside the surface.\n   */\n  function getSelectionAnchor(surface: HTMLElement): SelectionPopoverPosition | null {\n    const selection = window.getSelection();\n    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return null;\n\n    const range = selection.getRangeAt(0);\n    if (!surface.contains(range.commonAncestorContainer)) return null;\n\n    const rect =\n      Array.from(range.getClientRects()).find((clientRect) => {\n        return clientRect.width > 0 && clientRect.height > 0;\n      }) ?? range.getBoundingClientRect();\n\n    if (rect.width === 0 && rect.height === 0) return null;\n\n    return {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n      height: rect.height,\n    };\n  }\n\n  /**\n   * `selectionchange` fires on document, not on elements.\n   * Register at document level and scope to the surface via\n   * the bound surfaceElement reference.\n   *\n   * Guard: when the selection collapses because the user clicked inside the\n   * popover (e.g. the \"Add comment\" button or the textarea), do NOT close the\n   * popover mid-interaction.  Two checks mirror the production review-editor\n   * pattern:\n   *\n   *   1. Focus containment — document.activeElement is inside the popover root.\n   *      Covers the common case and all non-Safari browsers.\n   *\n   *   2. data-cinder-expanded attribute — the SelectionPopover component sets\n   *      this on its root element while the comment form is open.  Safari does\n   *      not move focus to buttons on click, so the focus check alone would\n   *      miss that case.\n   */\n  onMount(() => {\n    function handleSelectionChange(): void {\n      if (!surfaceElement) return;\n\n      // Don't close the popover while the user is interacting with it.\n      const popoverElement = document.getElementById(popoverId);\n      if (popoverElement?.contains(document.activeElement)) return;\n      if (popoverElement?.hasAttribute('data-cinder-expanded')) return;\n\n      const anchor = getSelectionAnchor(surfaceElement);\n      if (anchor) {\n        position = anchor;\n        isOpen = true;\n      } else {\n        isOpen = false;\n        position = null;\n      }\n    }\n\n    document.addEventListener('selectionchange', handleSelectionChange);\n    return () => document.removeEventListener('selectionchange', handleSelectionChange);\n  });\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function addComment(body: string): void {\n    comments = [...comments, { id: crypto.randomUUID(), body }];\n    handleClose();\n  }\n</script>\n\n<article\n  bind:this={surfaceElement}\n  style=\"max-width: 36rem; line-height: 1.6; user-select: text; cursor: text;\"\n>\n  <p style=\"margin: 0 0 0.75rem;\">\n    The <strong>SelectionPopover</strong> appears near highlighted text — its\n    <code>position</code> prop takes viewport-relative coordinates derived from\n    <code>Range.getClientRects()</code>, not local container offsets. Select any portion of this\n    paragraph to see it appear near your selection.\n  </p>\n  <p style=\"margin: 0;\">\n    Clicking the comment icon expands the composer. Submit with the send button or\n    <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>Enter</kbd>. Clicking outside the popover closes it and\n    resets the popover state.\n  </p>\n</article>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={addComment}\n/>\n\n{#if comments.length > 0}\n  <section style=\"margin: 1rem 0 0;\" aria-label=\"Submitted comments\">\n    <h3\n      style=\"margin: 0 0 0.5rem; font-size: var(--cinder-text-xs); font-weight: var(--cinder-font-medium); color: var(--cinder-text-muted); text-transform: uppercase; letter-spacing: 0.04em;\"\n    >\n      Submitted comments\n    </h3>\n    {#each comments as comment (comment.id)}\n      <article\n        style=\"padding: 0.5rem 0.75rem; margin-bottom: 0.375rem; border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-sm); background: var(--cinder-surface);\"\n      >\n        {comment.body}\n      </article>\n    {/each}\n  </section>\n{/if}\n"
     },
     {
       "id": "existing-comments",
       "title": "Existing commented selections",
       "description": "Shows persistent comment highlights as consumer-owned markup while SelectionPopover handles new text selections.",
-      "code": "<script lang=\"ts\">\n  import { onMount } from 'svelte';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  type ExistingComment = {\n    id: string;\n    quote: string;\n    body: string;\n  };\n\n  type SubmittedComment = { id: string; body: string };\n\n  const popoverId = 'existing-comments-selection-popover';\n  const activeCommentPanelId = 'existing-comment-panel';\n  const existingComments: ExistingComment[] = [\n    {\n      id: 'existing-comment-platform',\n      quote: 'platform review workflow',\n      body: 'This phrase already has a persisted comment. The highlight is rendered by the consumer.',\n    },\n    {\n      id: 'existing-comment-anchors',\n      quote: 'anchored selections visible',\n      body: 'ReviewEditor uses commentary anchor decorations for the full editor-backed version.',\n    },\n  ];\n\n  let surfaceElement = $state<HTMLElement | null>(null);\n  let activeCommentId = $state(existingComments[0]?.id ?? null);\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let submittedComments = $state<SubmittedComment[]>([]);\n\n  const activeComment = $derived(\n    existingComments.find((comment) => comment.id === activeCommentId) ?? null,\n  );\n  const layoutStyle =\n    'display: flex; flex-wrap: wrap; gap: var(--cinder-space-4); align-items: flex-start;';\n  const surfaceStyle =\n    'flex: 1 1 24rem; min-width: min(100%, 20rem); max-width: 36rem; line-height: 1.6; user-select: text; cursor: text;';\n  const paragraphStyle = 'margin: 0 0 var(--cinder-space-3);';\n  const anchorBaseStyle =\n    'border-radius: var(--cinder-radius-sm); color: inherit; text-decoration-color: var(--cinder-accent); text-decoration-thickness: 0.1em; text-underline-offset: 0.15em; cursor: pointer;';\n  const panelStyle =\n    'flex: 1 1 14rem; max-width: 18rem; padding: var(--cinder-space-3); border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-md); background: var(--cinder-surface);';\n  const headingStyle =\n    'margin: 0 0 var(--cinder-space-2); font-size: var(--cinder-text-sm); font-weight: var(--cinder-font-medium);';\n  const bodyStyle =\n    'margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm); line-height: 1.5;';\n  const submittedStyle = `${panelStyle} max-width: 36rem; margin-top: var(--cinder-space-3);`;\n\n  function getAnchorStyle(active: boolean): string {\n    const background = active\n      ? 'background: color-mix(in oklch, var(--cinder-accent), transparent 72%); outline: 1px solid color-mix(in oklch, var(--cinder-accent), transparent 32%);'\n      : 'background: color-mix(in oklch, var(--cinder-accent), transparent 84%);';\n    return `${anchorBaseStyle} ${background}`;\n  }\n\n  function getSelectionAnchor(surface: HTMLElement): SelectionPopoverPosition | null {\n    const selection = window.getSelection();\n    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return null;\n\n    const range = selection.getRangeAt(0);\n    if (!surface.contains(range.commonAncestorContainer)) return null;\n\n    const rect =\n      Array.from(range.getClientRects()).find((clientRect) => {\n        return clientRect.width > 0 && clientRect.height > 0;\n      }) ?? range.getBoundingClientRect();\n\n    if (rect.width === 0 && rect.height === 0) return null;\n\n    return {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n    };\n  }\n\n  onMount(() => {\n    function handleSelectionChange(): void {\n      if (!surfaceElement) return;\n\n      const popoverElement = document.getElementById(popoverId);\n      if (popoverElement?.contains(document.activeElement)) return;\n      if (popoverElement?.hasAttribute('data-cinder-expanded')) return;\n\n      const anchor = getSelectionAnchor(surfaceElement);\n      if (anchor) {\n        position = anchor;\n        isOpen = true;\n      } else {\n        position = null;\n        isOpen = false;\n      }\n    }\n\n    document.addEventListener('selectionchange', handleSelectionChange);\n    return () => document.removeEventListener('selectionchange', handleSelectionChange);\n  });\n\n  function openExistingComment(event: MouseEvent, commentId: string): void {\n    event.preventDefault();\n    activeCommentId = commentId;\n    isOpen = false;\n    position = null;\n  }\n\n  function handleExistingCommentKeydown(event: KeyboardEvent, commentId: string): void {\n    if (event.key !== ' ') return;\n    event.preventDefault();\n    activeCommentId = commentId;\n    isOpen = false;\n    position = null;\n  }\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function addComment(body: string): void {\n    submittedComments = [...submittedComments, { id: crypto.randomUUID(), body }];\n    handleClose();\n  }\n</script>\n\n<div style={layoutStyle}>\n  <article bind:this={surfaceElement} style={surfaceStyle}>\n    <p style={paragraphStyle}>\n      Consumers can keep the\n      <a\n        href=\"#existing-comment-platform\"\n        data-testid=\"existing-comment-anchor\"\n        data-active={activeCommentId === 'existing-comment-platform'}\n        aria-current={activeCommentId === 'existing-comment-platform' ? 'true' : undefined}\n        aria-controls={activeCommentPanelId}\n        style={getAnchorStyle(activeCommentId === 'existing-comment-platform')}\n        onclick={(event) => openExistingComment(event, 'existing-comment-platform')}\n        onkeydown={(event) => handleExistingCommentKeydown(event, 'existing-comment-platform')}\n      >\n        platform review workflow\n      </a>\n      visibly connected to saved comments while still using SelectionPopover for brand-new selections.\n    </p>\n\n    <p style={paragraphStyle}>\n      For editor-backed documents, ReviewEditor and commentary anchor decorations keep\n      <a\n        href=\"#existing-comment-anchors\"\n        data-testid=\"existing-comment-anchor\"\n        data-active={activeCommentId === 'existing-comment-anchors'}\n        aria-current={activeCommentId === 'existing-comment-anchors' ? 'true' : undefined}\n        aria-controls={activeCommentPanelId}\n        style={getAnchorStyle(activeCommentId === 'existing-comment-anchors')}\n        onclick={(event) => openExistingComment(event, 'existing-comment-anchors')}\n        onkeydown={(event) => handleExistingCommentKeydown(event, 'existing-comment-anchors')}\n      >\n        anchored selections visible\n      </a>\n      as the document changes. Select any unhighlighted text in this example to add a new note.\n    </p>\n  </article>\n\n  <aside id={activeCommentPanelId} style={panelStyle} aria-live=\"polite\">\n    {#if activeComment}\n      <h4 id={activeComment.id} style={headingStyle}>{activeComment.quote}</h4>\n      <p style={bodyStyle}>{activeComment.body}</p>\n    {/if}\n  </aside>\n</div>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={addComment}\n/>\n\n{#if submittedComments.length > 0}\n  <section style={submittedStyle} aria-label=\"New comments\">\n    <h4 style={headingStyle}>New comments</h4>\n    {#each submittedComments as comment (comment.id)}\n      <p style={bodyStyle}>{comment.body}</p>\n    {/each}\n  </section>\n{/if}\n"
+      "code": "<script lang=\"ts\">\n  import { onMount } from 'svelte';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  type ExistingComment = {\n    id: string;\n    quote: string;\n    body: string;\n  };\n\n  type SubmittedComment = { id: string; body: string };\n\n  const popoverId = 'existing-comments-selection-popover';\n  const activeCommentPanelId = 'existing-comment-panel';\n  const existingComments: ExistingComment[] = [\n    {\n      id: 'existing-comment-platform',\n      quote: 'platform review workflow',\n      body: 'This phrase already has a persisted comment. The highlight is rendered by the consumer.',\n    },\n    {\n      id: 'existing-comment-anchors',\n      quote: 'anchored selections visible',\n      body: 'ReviewEditor uses commentary anchor decorations for the full editor-backed version.',\n    },\n  ];\n\n  let surfaceElement = $state<HTMLElement | null>(null);\n  let activeCommentId = $state(existingComments[0]?.id ?? null);\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let submittedComments = $state<SubmittedComment[]>([]);\n\n  const activeComment = $derived(\n    existingComments.find((comment) => comment.id === activeCommentId) ?? null,\n  );\n  const layoutStyle =\n    'display: flex; flex-wrap: wrap; gap: var(--cinder-space-4); align-items: flex-start;';\n  const surfaceStyle =\n    'flex: 1 1 24rem; min-width: min(100%, 20rem); max-width: 36rem; line-height: 1.6; user-select: text; cursor: text;';\n  const paragraphStyle = 'margin: 0 0 var(--cinder-space-3);';\n  const anchorBaseStyle =\n    'border-radius: var(--cinder-radius-sm); color: inherit; text-decoration-color: var(--cinder-accent); text-decoration-thickness: 0.1em; text-underline-offset: 0.15em; cursor: pointer;';\n  const panelStyle =\n    'flex: 1 1 14rem; max-width: 18rem; padding: var(--cinder-space-3); border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-md); background: var(--cinder-surface);';\n  const headingStyle =\n    'margin: 0 0 var(--cinder-space-2); font-size: var(--cinder-text-sm); font-weight: var(--cinder-font-medium);';\n  const bodyStyle =\n    'margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm); line-height: 1.5;';\n  const submittedStyle = `${panelStyle} max-width: 36rem; margin-top: var(--cinder-space-3);`;\n\n  function getAnchorStyle(active: boolean): string {\n    const background = active\n      ? 'background: color-mix(in oklch, var(--cinder-accent), transparent 72%); outline: 1px solid color-mix(in oklch, var(--cinder-accent), transparent 32%);'\n      : 'background: color-mix(in oklch, var(--cinder-accent), transparent 84%);';\n    return `${anchorBaseStyle} ${background}`;\n  }\n\n  function getSelectionAnchor(surface: HTMLElement): SelectionPopoverPosition | null {\n    const selection = window.getSelection();\n    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return null;\n\n    const range = selection.getRangeAt(0);\n    if (!surface.contains(range.commonAncestorContainer)) return null;\n\n    const rect =\n      Array.from(range.getClientRects()).find((clientRect) => {\n        return clientRect.width > 0 && clientRect.height > 0;\n      }) ?? range.getBoundingClientRect();\n\n    if (rect.width === 0 && rect.height === 0) return null;\n\n    return {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n      height: rect.height,\n    };\n  }\n\n  onMount(() => {\n    function handleSelectionChange(): void {\n      if (!surfaceElement) return;\n\n      const popoverElement = document.getElementById(popoverId);\n      if (popoverElement?.contains(document.activeElement)) return;\n      if (popoverElement?.hasAttribute('data-cinder-expanded')) return;\n\n      const anchor = getSelectionAnchor(surfaceElement);\n      if (anchor) {\n        position = anchor;\n        isOpen = true;\n      } else {\n        position = null;\n        isOpen = false;\n      }\n    }\n\n    document.addEventListener('selectionchange', handleSelectionChange);\n    return () => document.removeEventListener('selectionchange', handleSelectionChange);\n  });\n\n  function openExistingComment(event: MouseEvent, commentId: string): void {\n    event.preventDefault();\n    activeCommentId = commentId;\n    isOpen = false;\n    position = null;\n  }\n\n  function handleExistingCommentKeydown(event: KeyboardEvent, commentId: string): void {\n    if (event.key !== ' ') return;\n    event.preventDefault();\n    activeCommentId = commentId;\n    isOpen = false;\n    position = null;\n  }\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function addComment(body: string): void {\n    submittedComments = [...submittedComments, { id: crypto.randomUUID(), body }];\n    handleClose();\n  }\n</script>\n\n<div style={layoutStyle}>\n  <article bind:this={surfaceElement} style={surfaceStyle}>\n    <p style={paragraphStyle}>\n      Consumers can keep the\n      <a\n        href=\"#existing-comment-platform\"\n        data-testid=\"existing-comment-anchor\"\n        data-active={activeCommentId === 'existing-comment-platform'}\n        aria-current={activeCommentId === 'existing-comment-platform' ? 'true' : undefined}\n        aria-controls={activeCommentPanelId}\n        style={getAnchorStyle(activeCommentId === 'existing-comment-platform')}\n        onclick={(event) => openExistingComment(event, 'existing-comment-platform')}\n        onkeydown={(event) => handleExistingCommentKeydown(event, 'existing-comment-platform')}\n      >\n        platform review workflow\n      </a>\n      visibly connected to saved comments while still using SelectionPopover for brand-new selections.\n    </p>\n\n    <p style={paragraphStyle}>\n      For editor-backed documents, ReviewEditor and commentary anchor decorations keep\n      <a\n        href=\"#existing-comment-anchors\"\n        data-testid=\"existing-comment-anchor\"\n        data-active={activeCommentId === 'existing-comment-anchors'}\n        aria-current={activeCommentId === 'existing-comment-anchors' ? 'true' : undefined}\n        aria-controls={activeCommentPanelId}\n        style={getAnchorStyle(activeCommentId === 'existing-comment-anchors')}\n        onclick={(event) => openExistingComment(event, 'existing-comment-anchors')}\n        onkeydown={(event) => handleExistingCommentKeydown(event, 'existing-comment-anchors')}\n      >\n        anchored selections visible\n      </a>\n      as the document changes. Select any unhighlighted text in this example to add a new note.\n    </p>\n  </article>\n\n  <aside id={activeCommentPanelId} style={panelStyle} aria-live=\"polite\">\n    {#if activeComment}\n      <h4 id={activeComment.id} style={headingStyle}>{activeComment.quote}</h4>\n      <p style={bodyStyle}>{activeComment.body}</p>\n    {/if}\n  </aside>\n</div>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={addComment}\n/>\n\n{#if submittedComments.length > 0}\n  <section style={submittedStyle} aria-label=\"New comments\">\n    <h4 style={headingStyle}>New comments</h4>\n    {#each submittedComments as comment (comment.id)}\n      <p style={bodyStyle}>{comment.body}</p>\n    {/each}\n  </section>\n{/if}\n"
     },
     {
       "id": "keyboard",
       "title": "Keyboard submit after selection",
       "description": "Select text (by mouse or keyboard) to open the composer, then press Cmd+Enter or Ctrl+Enter to submit. The composer collapses back to the icon — the popover does not stay expanded.",
-      "code": "<script lang=\"ts\">\n  import { onMount } from 'svelte';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  const popoverId = 'keyboard-selection-popover';\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let lastSubmitted = $state<string | null>(null);\n\n  /**\n   * A bound reference to the text surface element.\n   * Used in the document-level selectionchange handler to scope\n   * selection detection to this element's subtree.\n   */\n  let surfaceElement = $state<HTMLElement | null>(null);\n\n  function getSelectionAnchor(surface: HTMLElement): SelectionPopoverPosition | null {\n    const selection = window.getSelection();\n    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return null;\n\n    const range = selection.getRangeAt(0);\n    if (!surface.contains(range.commonAncestorContainer)) return null;\n\n    const rect =\n      Array.from(range.getClientRects()).find((clientRect) => {\n        return clientRect.width > 0 && clientRect.height > 0;\n      }) ?? range.getBoundingClientRect();\n\n    if (rect.width === 0 && rect.height === 0) return null;\n\n    return {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n    };\n  }\n\n  /**\n   * `selectionchange` fires on document, not on elements.\n   * Register at document level and scope to the surface via\n   * the bound surfaceElement reference.\n   *\n   * Keyboard selection (Shift+Arrow, Shift+Home, Shift+End, etc.) fires\n   * selectionchange just like mouse-driven selection — so keyboard users\n   * get the same popover trigger without any extra wiring.\n   *\n   * Guard: when the selection collapses because the user clicked inside the\n   * popover (e.g. the \"Add comment\" button or the textarea), do NOT close the\n   * popover mid-interaction.  Two checks mirror the production review-editor\n   * pattern:\n   *\n   *   1. Focus containment — document.activeElement is inside the popover root.\n   *      Covers the common case and all non-Safari browsers.\n   *\n   *   2. data-cinder-expanded attribute — the SelectionPopover component sets\n   *      this on its root element while the comment form is open.  Safari does\n   *      not move focus to buttons on click, so the focus check alone would\n   *      miss that case.\n   */\n  onMount(() => {\n    function handleSelectionChange(): void {\n      if (!surfaceElement) return;\n\n      // Don't close the popover while the user is interacting with it.\n      const popoverElement = document.getElementById(popoverId);\n      if (popoverElement?.contains(document.activeElement)) return;\n      if (popoverElement?.hasAttribute('data-cinder-expanded')) return;\n\n      const anchor = getSelectionAnchor(surfaceElement);\n      if (anchor) {\n        position = anchor;\n        isOpen = true;\n      } else {\n        isOpen = false;\n        position = null;\n      }\n    }\n\n    document.addEventListener('selectionchange', handleSelectionChange);\n    return () => document.removeEventListener('selectionchange', handleSelectionChange);\n  });\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function recordComment(body: string): void {\n    lastSubmitted = body;\n    handleClose();\n  }\n</script>\n\n<article\n  bind:this={surfaceElement}\n  style=\"max-width: 36rem; line-height: 1.6; user-select: text; cursor: text;\"\n>\n  <p style=\"margin: 0;\">\n    Select text in this paragraph to open the comment popover — both mouse drag and keyboard\n    selection (hold <kbd>Shift</kbd> while pressing arrow keys, <kbd>Home</kbd>, or <kbd>End</kbd>)\n    trigger the popover. Click the comment icon to expand the composer, type a note, then press\n    <kbd>Cmd</kbd>+<kbd>Enter</kbd> (macOS) or <kbd>Ctrl</kbd>+<kbd>Enter</kbd> (Windows/Linux) to submit.\n    The composer collapses back to the icon after submission — the popover does not stay expanded.\n  </p>\n</article>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={recordComment}\n/>\n\n{#if lastSubmitted}\n  <section style=\"margin: 1rem 0 0;\" aria-label=\"Last submitted\">\n    <h3\n      style=\"margin: 0 0 0.5rem; font-size: var(--cinder-text-xs); font-weight: var(--cinder-font-medium); color: var(--cinder-text-muted); text-transform: uppercase; letter-spacing: 0.04em;\"\n    >\n      Last submitted\n    </h3>\n    <article\n      style=\"padding: 0.5rem 0.75rem; border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-sm); background: var(--cinder-surface);\"\n    >\n      {lastSubmitted}\n    </article>\n  </section>\n{/if}\n"
+      "code": "<script lang=\"ts\">\n  import { onMount } from 'svelte';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  const popoverId = 'keyboard-selection-popover';\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let lastSubmitted = $state<string | null>(null);\n\n  /**\n   * A bound reference to the text surface element.\n   * Used in the document-level selectionchange handler to scope\n   * selection detection to this element's subtree.\n   */\n  let surfaceElement = $state<HTMLElement | null>(null);\n\n  function getSelectionAnchor(surface: HTMLElement): SelectionPopoverPosition | null {\n    const selection = window.getSelection();\n    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return null;\n\n    const range = selection.getRangeAt(0);\n    if (!surface.contains(range.commonAncestorContainer)) return null;\n\n    const rect =\n      Array.from(range.getClientRects()).find((clientRect) => {\n        return clientRect.width > 0 && clientRect.height > 0;\n      }) ?? range.getBoundingClientRect();\n\n    if (rect.width === 0 && rect.height === 0) return null;\n\n    return {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n      height: rect.height,\n    };\n  }\n\n  /**\n   * `selectionchange` fires on document, not on elements.\n   * Register at document level and scope to the surface via\n   * the bound surfaceElement reference.\n   *\n   * Keyboard selection (Shift+Arrow, Shift+Home, Shift+End, etc.) fires\n   * selectionchange just like mouse-driven selection — so keyboard users\n   * get the same popover trigger without any extra wiring.\n   *\n   * Guard: when the selection collapses because the user clicked inside the\n   * popover (e.g. the \"Add comment\" button or the textarea), do NOT close the\n   * popover mid-interaction.  Two checks mirror the production review-editor\n   * pattern:\n   *\n   *   1. Focus containment — document.activeElement is inside the popover root.\n   *      Covers the common case and all non-Safari browsers.\n   *\n   *   2. data-cinder-expanded attribute — the SelectionPopover component sets\n   *      this on its root element while the comment form is open.  Safari does\n   *      not move focus to buttons on click, so the focus check alone would\n   *      miss that case.\n   */\n  onMount(() => {\n    function handleSelectionChange(): void {\n      if (!surfaceElement) return;\n\n      // Don't close the popover while the user is interacting with it.\n      const popoverElement = document.getElementById(popoverId);\n      if (popoverElement?.contains(document.activeElement)) return;\n      if (popoverElement?.hasAttribute('data-cinder-expanded')) return;\n\n      const anchor = getSelectionAnchor(surfaceElement);\n      if (anchor) {\n        position = anchor;\n        isOpen = true;\n      } else {\n        isOpen = false;\n        position = null;\n      }\n    }\n\n    document.addEventListener('selectionchange', handleSelectionChange);\n    return () => document.removeEventListener('selectionchange', handleSelectionChange);\n  });\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function recordComment(body: string): void {\n    lastSubmitted = body;\n    handleClose();\n  }\n</script>\n\n<article\n  bind:this={surfaceElement}\n  style=\"max-width: 36rem; line-height: 1.6; user-select: text; cursor: text;\"\n>\n  <p style=\"margin: 0;\">\n    Select text in this paragraph to open the comment popover — both mouse drag and keyboard\n    selection (hold <kbd>Shift</kbd> while pressing arrow keys, <kbd>Home</kbd>, or <kbd>End</kbd>)\n    trigger the popover. Click the comment icon to expand the composer, type a note, then press\n    <kbd>Cmd</kbd>+<kbd>Enter</kbd> (macOS) or <kbd>Ctrl</kbd>+<kbd>Enter</kbd> (Windows/Linux) to submit.\n    The composer collapses back to the icon after submission — the popover does not stay expanded.\n  </p>\n</article>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={recordComment}\n/>\n\n{#if lastSubmitted}\n  <section style=\"margin: 1rem 0 0;\" aria-label=\"Last submitted\">\n    <h3\n      style=\"margin: 0 0 0.5rem; font-size: var(--cinder-text-xs); font-weight: var(--cinder-font-medium); color: var(--cinder-text-muted); text-transform: uppercase; letter-spacing: 0.04em;\"\n    >\n      Last submitted\n    </h3>\n    <article\n      style=\"padding: 0.5rem 0.75rem; border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-sm); background: var(--cinder-surface);\"\n    >\n      {lastSubmitted}\n    </article>\n  </section>\n{/if}\n"
     },
     {
       "id": "null-position",
@@ -31,7 +31,7 @@
       "id": "toggled",
       "title": "Toggled by an external trigger",
       "description": "A button outside the popover drives open. When the consumer clicks outside the popover, the component invokes onclose and the consumer flips open back to false.",
-      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  const popoverId = 'toggled-selection-popover';\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let lastSubmitted = $state<string | null>(null);\n  let anchorElement = $state<HTMLElement | null>(null);\n\n  function openPopover(): void {\n    if (!anchorElement) return;\n\n    const rect = anchorElement.getBoundingClientRect();\n    position = {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n    };\n    isOpen = true;\n  }\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function handleSubmit(body: string): void {\n    lastSubmitted = body;\n    handleClose();\n  }\n</script>\n\n<div style=\"max-width: 36rem;\">\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    Click the button to open the popover at a visible marked phrase. Click anywhere outside the\n    popover and it closes — the component fires <code>onclose</code> and the consumer flips\n    <code>open</code> back to <code>false</code>. The <code>position</code> prop here is derived from\n    the marked phrase's viewport rectangle.\n  </p>\n\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    The comment action anchors to\n    <mark\n      bind:this={anchorElement}\n      data-testid=\"external-trigger-anchor\"\n      style=\"border-radius: var(--cinder-radius-sm); background: color-mix(in oklch, var(--cinder-accent), transparent 84%); color: var(--cinder-text); padding: 0 0.125rem;\"\n    >\n      this visible phrase\n    </mark>\n    rather than a hard-coded viewport coordinate.\n  </p>\n\n  <Button\n    label=\"Open popover\"\n    aria-expanded={isOpen}\n    aria-controls={popoverId}\n    disabled={isOpen}\n    onclick={openPopover}\n  />\n</div>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={handleSubmit}\n/>\n\n{#if lastSubmitted}\n  <section style=\"margin: 1rem 0 0;\" aria-label=\"Last submitted\">\n    <h3\n      style=\"margin: 0 0 0.5rem; font-size: var(--cinder-text-xs); font-weight: var(--cinder-font-medium); color: var(--cinder-text-muted); text-transform: uppercase; letter-spacing: 0.04em;\"\n    >\n      Last submitted\n    </h3>\n    <article\n      style=\"padding: 0.5rem 0.75rem; border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-sm); background: var(--cinder-surface);\"\n    >\n      {lastSubmitted}\n    </article>\n  </section>\n{/if}\n"
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  const popoverId = 'toggled-selection-popover';\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let lastSubmitted = $state<string | null>(null);\n  let anchorElement = $state<HTMLElement | null>(null);\n\n  function openPopover(): void {\n    if (!anchorElement) return;\n\n    const rect = anchorElement.getBoundingClientRect();\n    position = {\n      x: rect.left + rect.width / 2,\n      y: rect.top,\n      height: rect.height,\n    };\n    isOpen = true;\n  }\n\n  function handleClose(): void {\n    isOpen = false;\n    position = null;\n  }\n\n  function handleSubmit(body: string): void {\n    lastSubmitted = body;\n    handleClose();\n  }\n</script>\n\n<div style=\"max-width: 36rem;\">\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    Click the button to open the popover at a visible marked phrase. Click anywhere outside the\n    popover and it closes — the component fires <code>onclose</code> and the consumer flips\n    <code>open</code> back to <code>false</code>. The <code>position</code> prop here is derived from\n    the marked phrase's viewport rectangle.\n  </p>\n\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    The comment action anchors to\n    <mark\n      bind:this={anchorElement}\n      data-testid=\"external-trigger-anchor\"\n      style=\"border-radius: var(--cinder-radius-sm); background: color-mix(in oklch, var(--cinder-accent), transparent 84%); color: var(--cinder-text); padding: 0 0.125rem;\"\n    >\n      this visible phrase\n    </mark>\n    rather than a hard-coded viewport coordinate.\n  </p>\n\n  <Button\n    label=\"Open popover\"\n    aria-expanded={isOpen}\n    aria-controls={popoverId}\n    disabled={isOpen}\n    onclick={openPopover}\n  />\n</div>\n\n<SelectionPopover\n  id={popoverId}\n  open={isOpen}\n  {position}\n  onclose={handleClose}\n  oncommentsubmit={handleSubmit}\n/>\n\n{#if lastSubmitted}\n  <section style=\"margin: 1rem 0 0;\" aria-label=\"Last submitted\">\n    <h3\n      style=\"margin: 0 0 0.5rem; font-size: var(--cinder-text-xs); font-weight: var(--cinder-font-medium); color: var(--cinder-text-muted); text-transform: uppercase; letter-spacing: 0.04em;\"\n    >\n      Last submitted\n    </h3>\n    <article\n      style=\"padding: 0.5rem 0.75rem; border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-sm); background: var(--cinder-surface);\"\n    >\n      {lastSubmitted}\n    </article>\n  </section>\n{/if}\n"
     },
     {
       "id": "viewport-clamping",

package/src/components/selection-popover/selection-popover.svelte

@@ -50,6 +50,13 @@
   const virtualAnchor = $derived.by<VirtualElement | null>(() => {
     if (!position) return null;
 
+    // Use the selection height when provided so floating-ui sees the real bottom
+    // edge of the selection. Without this, `bottom` equals `top` (zero-height
+    // point anchor), and when `flip` switches to bottom-placement the panel's
+    // top is set to `anchor.bottom + offset = position.y + 8` — inside the
+    // selection line — causing the observed ~8.5 px overlap (issue #369).
+    const selectionHeight = position.height ?? 0;
+
     return {
       getBoundingClientRect: () =>
         ({
@@ -58,9 +65,9 @@
           top: position.y,
           left: position.x,
           right: position.x,
-          bottom: position.y,
+          bottom: position.y + selectionHeight,
           width: 0,
-          height: 0,
+          height: selectionHeight,
         }) as DOMRect,
     };
   });

package/src/components/selection-popover/selection-popover.types.ts

@@ -2,6 +2,14 @@ import type { HTMLAttributes } from 'svelte/elements';
 export type SelectionPopoverPosition = {
   x: number;
   y: number;
+  /**
+   * Height of the selection rect in CSS pixels. When provided, the virtual
+   * anchor exposes the correct `bottom` edge (`y + height`) to floating-ui so
+   * that `flip` places the panel below the selection's actual bottom edge
+   * instead of overlapping it. Defaults to 0 when omitted (zero-height point
+   * anchor — the original behaviour, which causes overlap when flipped).
+   */
+  height?: number;
 };
 export type SelectionPopoverProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
   /** Unique identifier for the popover. */

package/src/components/share-card/README.md

@@ -26,18 +26,18 @@ Compact share card with copy-link, copy-text, and native navigator.share actions
 
 <!-- generated:props:start -->
 
-| Prop              | Type       | Required | Default | Description                                                                                                                |
-| ----------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`           | `string`   | no       | —       | Additional class names merged with `.cinder-share-card`.                                                                   |
-| `confirmDuration` | `number`   | no       | `2000`  | Duration in ms to show the copied confirmation state.                                                                      |
-| `copiedLabel`     | `string`   | no       | —       | Label shown after a successful copy.                                                                                       |
-| `copyLinkLabel`   | `string`   | no       | —       | Label for the copy-link button.                                                                                            |
-| `description`     | `string`   | no       | —       | Additional descriptive text.                                                                                               |
-| `shareLabel`      | `string`   | no       | —       | Label for the native-share button.                                                                                         |
-| `title`           | `string`   | no       | —       | Human-readable title for the share card.                                                                                   |
-| `value`           | `string`   | yes      | —       | The URL or text to share/copy.                                                                                             |
-| `actions`         | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `preview`         | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop              | Type       | Required | Default | Description                                                                                                                                                    |
+| ----------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`           | `string`   | no       | —       | Additional class names merged with `.cinder-share-card`.                                                                                                       |
+| `confirmDuration` | `number`   | no       | `2000`  | Duration in ms to show the copied confirmation state.                                                                                                          |
+| `copiedLabel`     | `string`   | no       | —       | Label shown after a successful copy.                                                                                                                           |
+| `copyLinkLabel`   | `string`   | no       | —       | Label for the copy-link button.                                                                                                                                |
+| `description`     | `string`   | no       | —       | Additional descriptive text.                                                                                                                                   |
+| `shareLabel`      | `string`   | no       | —       | Label for the native-share button.                                                                                                                             |
+| `title`           | `string`   | no       | —       | Human-readable title for the share card.                                                                                                                       |
+| `value`           | `string`   | yes      | —       | The URL or text to share/copy.                                                                                                                                 |
+| `actions`         | `(opaque)` | no       | —       | Explicit actions to show. When omitted, default copy + native-share actions render. Not expressible in JSON Schema; see the component types for the signature. |
+| `preview`         | `(opaque)` | no       | —       | Preview content slot rendered above the actions. Not expressible in JSON Schema; see the component types for the signature.                                    |
 
 <!-- generated:props:end -->