@lostgradient/cinder 0.2.0 → 0.4.0

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

@@ -7,31 +7,31 @@
       "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",
       "title": "Null position clears the popover",
       "description": "Setting position to null hides the popover even while open is true — the consumer can clear an active selection without changing the open flag.",
-      "code": "<script lang=\"ts\">\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { Button } from '@lostgradient/cinder/button';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  const popoverId = 'null-position-selection-popover';\n\n  /**\n   * A fixed anchor used to demonstrate the null-clear behavior without requiring\n   * a real text selection in this example. The coordinates are viewport-relative,\n   * consistent with how a real selection anchor would be computed.\n   */\n  const demonstrationPosition: SelectionPopoverPosition = { x: 220, y: 220 };\n\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n\n  function showPopover(): void {\n    position = demonstrationPosition;\n    isOpen = true;\n  }\n\n  function clearPosition(): void {\n    position = null;\n    // open stays true — the component should hide because position is null.\n  }\n\n  function restorePosition(): void {\n    position = demonstrationPosition;\n  }\n</script>\n\n<div style=\"max-width: 36rem;\">\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    Demonstrates that setting <code>position</code> to <code>null</code> hides the popover even when\n    <code>open</code>\n    remains <code>true</code>. Click <em>Show popover</em> to open it, then use\n    <em>Clear position</em>\n    to set <code>position=null</code> while leaving\n    <code>open=true</code> — the popover disappears because the component has no anchor point to\n    position against. Use <em>Restore position</em> to bring it back without changing\n    <code>open</code>.\n  </p>\n\n  <div style=\"display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 0.75rem;\">\n    <Button label=\"Show popover\" onclick={showPopover} />\n    <Button label=\"Clear position (set null)\" onclick={clearPosition} disabled={!isOpen} />\n    <Button label=\"Restore position\" onclick={restorePosition} disabled={!isOpen} />\n  </div>\n\n  <p style=\"margin: 0; font-size: var(--cinder-text-sm); color: var(--cinder-text-muted);\">\n    Status: open={isOpen}, position={position ? `{x:${position.x},y:${position.y}}` : 'null'}\n  </p>\n</div>\n\n<SelectionPopover id={popoverId} open={isOpen} {position} />\n"
+      "code": "<script lang=\"ts\">\n  import type { SelectionPopoverPosition } from '@lostgradient/cinder/selection-popover';\n  import { Button } from '@lostgradient/cinder/button';\n  import { SelectionPopover } from '@lostgradient/cinder/selection-popover';\n\n  const popoverId = 'null-position-selection-popover';\n\n  let isOpen = $state(false);\n  let position = $state<SelectionPopoverPosition | null>(null);\n  let anchorElement = $state<HTMLElement | null>(null);\n\n  function showPopover(): 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 clearPosition(): void {\n    position = null;\n    // open stays true — the component should hide because position is null.\n  }\n\n  function restorePosition(): void {\n    showPopover();\n  }\n</script>\n\n<div style=\"max-width: 36rem;\">\n  <p style=\"margin: 0 0 0.75rem; line-height: 1.5;\">\n    Demonstrates that setting <code>position</code> to <code>null</code> hides the popover even when\n    <code>open</code>\n    remains <code>true</code>. Click <em>Show popover</em> to open it, then use\n    <em>Clear position</em>\n    to set <code>position=null</code> while leaving\n    <code>open=true</code> — the popover disappears because the component has no anchor point to\n    position against. Use <em>Restore position</em> to bring it back without changing\n    <code>open</code>.\n  </p>\n\n  <div style=\"display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 0.75rem;\">\n    <span bind:this={anchorElement} style=\"display: inline-flex;\">\n      <Button label=\"Show popover\" onclick={showPopover} />\n    </span>\n    <Button label=\"Clear position (set null)\" onclick={clearPosition} disabled={!isOpen} />\n    <Button label=\"Restore position\" onclick={restorePosition} disabled={!isOpen} />\n  </div>\n\n  <p style=\"margin: 0; font-size: var(--cinder-text-sm); color: var(--cinder-text-muted);\">\n    Status: open={isOpen}, position={position ? `{x:${position.x},y:${position.y}}` : 'null'}\n  </p>\n</div>\n\n<SelectionPopover id={popoverId} open={isOpen} {position} />\n"
     },
     {
       "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 -->
 

package/src/components/share-card/share-card.css

@@ -24,7 +24,7 @@
   }
 
   .cinder-share-card__title {
-    font-weight: 600;
+    font-weight: var(--cinder-font-semibold);
     font-size: var(--cinder-text-sm);
     margin: 0;
     color: var(--cinder-text);
@@ -76,10 +76,10 @@
     color: var(--cinder-text);
     cursor: pointer;
     font-size: var(--cinder-text-sm);
-    font-weight: 500;
+    font-weight: var(--cinder-font-medium);
     transition:
-      background-color 0.15s ease,
-      border-color 0.15s ease;
+      background-color var(--cinder-duration-fast) var(--cinder-ease-standard),
+      border-color var(--cinder-duration-fast) var(--cinder-ease-standard);
     white-space: nowrap;
   }
 
@@ -97,6 +97,17 @@
       0 0 0 calc(var(--cinder-ring-offset) + var(--cinder-ring-width)) var(--cinder-ring-color);
   }
 
+  @media (forced-colors: active) {
+    .cinder-share-card__action:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      /* 3px separates the outline from ButtonBorder (which renders in forced-colors
+         on all bordered controls and shares the ButtonText color family in HCM);
+         at 2px the ring and border can visually merge. */
+      outline-offset: 3px;
+      box-shadow: none;
+    }
+  }
+
   .cinder-share-card__action[data-cinder-copied] {
     color: var(--cinder-color-success-fg);
     border-color: var(--cinder-color-success-border);

package/src/components/share-card/share-card.svelte

@@ -16,9 +16,6 @@
 </script>
 
 <script lang="ts">
-  import { onDestroy } from 'svelte';
-  import { BROWSER } from 'esm-env';
-
   import { classNames } from '../../utilities/class-names.ts';
   import { copyToClipboard } from '../../utilities/clipboard.ts';
   import VisuallyHiddenLiveRegion from '../_visually-hidden-live-region.svelte';
@@ -43,9 +40,22 @@
   let resetTimer: ReturnType<typeof setTimeout> | undefined;
   let announcement = $state('');
 
-  // Detect native share support. Only available in a browser with a secure origin.
+  // Hydration gate. The native-share button depends on `navigator.share`, which
+  // only exists in the browser — but gating it on a plain browser check would
+  // make the client's first render add a button the server never emitted,
+  // producing a hydration mismatch. `$effect` runs only on the client, AFTER
+  // hydration, so the server render and the initial client render both omit the
+  // button; it appears on the next tick once `hydrated` flips. Matches the
+  // toast-region / drawer hydration-gate convention.
+  let hydrated = $state(false);
+  $effect(() => {
+    hydrated = true;
+  });
+
+  // Detect native share support. Gated on `hydrated` (not a bare browser flag)
+  // so it is always `false` during SSR and the initial hydration render.
   const canNativeShare = $derived(
-    BROWSER && typeof navigator !== 'undefined' && typeof navigator.share === 'function',
+    hydrated && typeof navigator !== 'undefined' && typeof navigator.share === 'function',
   );
 
   let announceTimer: ReturnType<typeof setTimeout> | undefined;
@@ -149,35 +159,26 @@
   // the value actually looks like a URL, otherwise "Text to share".
   const valueRegionLabel = $derived(looksLikeUrl(value) ? 'Link to share' : 'Text to share');
 
-  onDestroy(() => {
+  $effect(() => {
     // clearTimer() clears BOTH resetTimer and announceTimer.
-    clearTimer();
+    return () => clearTimer();
   });
 
-  // Build the default actions when no explicit actions are provided. The default
-  // surface always offers copy (the universal fallback); the native-share button
-  // is added only where `navigator.share` exists, so there is no redundant
-  // "Share" button that merely re-copies on unsupported platforms. A consumer who
-  // wants a share button that copies-when-unavailable can pass an explicit action
-  // with `useNativeShare: true` — `handleNativeShare` falls back to copy for it.
-  const resolvedActions = $derived.by((): ShareCardAction[] => {
-    if (actions) return actions;
-    const defaultActions: ShareCardAction[] = [
-      {
-        key: 'copy-link',
-        label: copyLinkLabel,
-        copyValue: value,
-      },
-    ];
-    if (canNativeShare) {
-      defaultActions.push({
-        key: 'native-share',
-        label: shareLabel,
-        useNativeShare: true,
-      });
-    }
-    return defaultActions;
-  });
+  // The action list: explicit `actions` verbatim, else the copy-link default.
+  // The default native-share button is NOT in this array — it is rendered by a
+  // standalone `{#if !actions && canNativeShare}` in the template. `canNativeShare`
+  // only flips true after hydration (it is gated on the `hydrated` $effect), and
+  // when the native-share action was instead appended to this reactive array
+  // post-hydration, the keyed `{#each}` did not render it. The standalone `{#if}`
+  // (matching the drawer/sheet hydration convention) renders reliably on the flip.
+  const defaultActions: ShareCardAction[] = $derived([
+    {
+      key: 'copy-link',
+      label: copyLinkLabel,
+      copyValue: value,
+    },
+  ]);
+  const resolvedActions = $derived(actions ?? defaultActions);
 </script>
 
 <div {...rest} class={classNames('cinder-share-card', customClassName)}>
@@ -206,125 +207,140 @@
   <div class="cinder-share-card__actions" role="group" aria-label="Share actions">
     {#each resolvedActions as action (action.key)}
       {#if action.key === 'native-share' || action.useNativeShare}
-        <!-- When native share is unavailable or fails, `handleNativeShare` falls
-             back to a clipboard copy keyed `share-fallback`. Reflect that copied
-             state on the share button so the visual matches the live-region
-             announcement instead of silently staying on the Share label. -->
-        {@const shareCopied = copiedKey === 'share-fallback'}
-        <button
-          type="button"
-          class="cinder-share-card__action"
-          data-cinder-action={action.key}
-          data-cinder-copied={shareCopied ? '' : undefined}
-          onclick={() => {
-            // Honour a consumer onClick (analytics/side-effects) on the native
-            // share action too, then run the share. `void` marks the floating
-            // promise as intentional (the handler is synchronous).
-            action.onClick?.();
-            void handleNativeShare();
-          }}
-          aria-label={shareCopied ? copiedLabel : action.label}
-        >
-          {#if shareCopied}
-            <!-- Copied state icon (after a fallback copy) -->
-            <span class="cinder-share-card__action-icon" aria-hidden="true">
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                viewBox="0 0 24 24"
-                fill="none"
-                stroke="currentColor"
-                stroke-width="2"
-                stroke-linecap="round"
-                stroke-linejoin="round"
-                class="cinder-share-card__icon"
-              >
-                <polyline points="20,6 9,17 4,12" />
-              </svg>
-            </span>
-            {copiedLabel}
-          {:else}
-            <!-- Share icon -->
-            <span class="cinder-share-card__action-icon" aria-hidden="true">
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                viewBox="0 0 24 24"
-                fill="none"
-                stroke="currentColor"
-                stroke-width="2"
-                stroke-linecap="round"
-                stroke-linejoin="round"
-                class="cinder-share-card__icon"
-              >
-                <circle cx="18" cy="5" r="3" />
-                <circle cx="6" cy="12" r="3" />
-                <circle cx="18" cy="19" r="3" />
-                <line x1="8.59" y1="13.51" x2="15.42" y2="17.49" />
-                <line x1="15.41" y1="6.51" x2="8.59" y2="10.49" />
-              </svg>
-            </span>
-            {action.label}
-          {/if}
-        </button>
+        {@render shareButton(action)}
       {:else}
-        <button
-          type="button"
-          class="cinder-share-card__action"
-          data-cinder-action={action.key}
-          data-cinder-copied={copiedKey === action.key ? '' : undefined}
-          onclick={() => {
-            // onClick is a side-effect callback (e.g. analytics), NOT an
-            // override — run it AND still perform the copy when copyValue is
-            // present, matching the native-share button's behaviour. An empty
-            // string is a legitimate copyValue, so test for `undefined`, not
-            // truthiness. `void` marks the floating promise as intentional.
-            action.onClick?.();
-            if (action.copyValue !== undefined) {
-              void handleCopy(action.key, action.copyValue);
-            }
-          }}
-          aria-label={copiedKey === action.key ? copiedLabel : action.label}
-        >
-          {#if copiedKey === action.key}
-            <!-- Copied state icon -->
-            <span class="cinder-share-card__action-icon" aria-hidden="true">
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                viewBox="0 0 24 24"
-                fill="none"
-                stroke="currentColor"
-                stroke-width="2"
-                stroke-linecap="round"
-                stroke-linejoin="round"
-                class="cinder-share-card__icon"
-              >
-                <polyline points="20,6 9,17 4,12" />
-              </svg>
-            </span>
-            {copiedLabel}
-          {:else}
-            <!-- Copy icon -->
-            <span class="cinder-share-card__action-icon" aria-hidden="true">
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                viewBox="0 0 24 24"
-                fill="none"
-                stroke="currentColor"
-                stroke-width="2"
-                stroke-linecap="round"
-                stroke-linejoin="round"
-                class="cinder-share-card__icon"
-              >
-                <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
-                <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
-              </svg>
-            </span>
-            {action.label}
-          {/if}
-        </button>
+        {@render copyButton(action)}
       {/if}
     {/each}
+    <!-- The default native-share button is gated by a standalone `{#if}` rather
+         than pushed into `resolvedActions`, so it reconciles correctly when
+         `canNativeShare` flips from false to true after hydration. Only rendered
+         in the default surface (no explicit `actions`); a consumer-supplied
+         native-share action goes through the `{#each}` above. -->
+    {#if !actions && canNativeShare}
+      {@render shareButton({ key: 'native-share', label: shareLabel, useNativeShare: true })}
+    {/if}
   </div>
 </div>
 
+<!-- Native-share button. Reflects the `share-fallback` copied state so that when
+     `handleNativeShare` falls back to a clipboard copy (native share unavailable
+     or failed) the visual matches the live-region announcement instead of staying
+     on the Share label. -->
+{#snippet shareButton(action: ShareCardAction)}
+  {@const shareCopied = copiedKey === 'share-fallback'}
+  <button
+    type="button"
+    class="cinder-share-card__action"
+    data-cinder-action={action.key}
+    data-cinder-copied={shareCopied ? '' : undefined}
+    onclick={() => {
+      // Honour a consumer onClick (analytics/side-effects) on the native share
+      // action too, then run the share. `void` marks the floating promise as
+      // intentional (the handler is synchronous).
+      action.onClick?.();
+      void handleNativeShare();
+    }}
+    aria-label={shareCopied ? copiedLabel : action.label}
+  >
+    {#if shareCopied}
+      <!-- Copied state icon (after a fallback copy) -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <polyline points="20,6 9,17 4,12" />
+        </svg>
+      </span>
+      {copiedLabel}
+    {:else}
+      <!-- Share icon -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <circle cx="18" cy="5" r="3" />
+          <circle cx="6" cy="12" r="3" />
+          <circle cx="18" cy="19" r="3" />
+          <line x1="8.59" y1="13.51" x2="15.42" y2="17.49" />
+          <line x1="15.41" y1="6.51" x2="8.59" y2="10.49" />
+        </svg>
+      </span>
+      {action.label}
+    {/if}
+  </button>
+{/snippet}
+
+<!-- Copy button. `onClick` is a side-effect callback (e.g. analytics), NOT an
+     override — it runs AND the copy still fires when `copyValue` is present. An
+     empty string is a legitimate copyValue, so test for `undefined`, not
+     truthiness. -->
+{#snippet copyButton(action: ShareCardAction)}
+  <button
+    type="button"
+    class="cinder-share-card__action"
+    data-cinder-action={action.key}
+    data-cinder-copied={copiedKey === action.key ? '' : undefined}
+    onclick={() => {
+      action.onClick?.();
+      if (action.copyValue !== undefined) {
+        void handleCopy(action.key, action.copyValue);
+      }
+    }}
+    aria-label={copiedKey === action.key ? copiedLabel : action.label}
+  >
+    {#if copiedKey === action.key}
+      <!-- Copied state icon -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <polyline points="20,6 9,17 4,12" />
+        </svg>
+      </span>
+      {copiedLabel}
+    {:else}
+      <!-- Copy icon -->
+      <span class="cinder-share-card__action-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          class="cinder-share-card__icon"
+        >
+          <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+          <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+        </svg>
+      </span>
+      {action.label}
+    {/if}
+  </button>
+{/snippet}
+
 <!-- Announce copy/share outcomes to assistive technology. -->
 <VisuallyHiddenLiveRegion message={announcement} />