feat(core): add text selection affordances

packages/core/README.md

@@ -105,14 +105,31 @@ Use `createAskableTextSelectionCapture()` when the user should highlight page
 text and send that exact selected range as structured context.
 
 ```ts
-import { createAskableContext, createAskableTextSelectionCapture } from '@askable-ui/core';
+import {
+  ASKABLE_TEXT_SELECTION_CAPTURE_THEME,
+  createAskableContext,
+  createAskableTextSelectionCapture,
+} from '@askable-ui/core';
 
 const ctx = createAskableContext({ viewport: true });
 ctx.observe(document);
 
 const selection = createAskableTextSelectionCapture(ctx, {
   intent: 'answer using this selected text',
   includeViewport: true,
+  selectionAffordance: {
+    label: 'Selected text',
+    prompt: {
+      placeholder: 'Ask about this text...',
+      onSubmit(question, packet) {
+        sendToAgent({ question, context: packet });
+      },
+    },
+  },
+  theme: {
+    ...ASKABLE_TEXT_SELECTION_CAPTURE_THEME,
+    selectionFill: 'rgba(124,58,237,0.14)',
+  },
   onCapture(packet) {
     sendToAgent(packet);
   },
@@ -124,6 +141,10 @@ selection.start();
 The packet uses `capture.mode` of `text-selection`, marks consent as explicit,
 and includes the highlighted copy in `target.text`. Call `captureNow()` for
 button-driven flows where selection should be read on demand.
+Set `selectionAffordance` to keep selected text visually marked after capture
+and optionally attach a small prompt to the highlighted range. The affordance
+accepts class names, inline styles, theme overrides, and a custom `render()`
+escape hatch.
 
 ## API Reference
 

packages/core/src/__tests__/selection.test.ts

@@ -17,6 +17,9 @@ function selectText(
   Object.defineProperty(range, 'getBoundingClientRect', {
     value: () => bounds,
   });
+  Object.defineProperty(range, 'getClientRects', {
+    value: () => [bounds],
+  });
 
   const selection = document.getSelection()!;
   selection.removeAllRanges();
@@ -66,6 +69,7 @@ describe('createAskableTextSelectionCapture', () => {
         metadata: {
           kind: 'text-selection',
           length: 29,
+          rectCount: 1,
         },
       },
       privacy: { consent: 'explicit' },
@@ -79,6 +83,95 @@ describe('createAskableTextSelectionCapture', () => {
     ctx.destroy();
   });
 
+  it('can persist selected text affordance after capture', () => {
+    const ctx = createAskableContext();
+    const capture = createAskableTextSelectionCapture(ctx, {
+      selectionAffordance: {
+        label: 'Quoted text',
+        className: 'custom-text-affordance',
+        style: { opacity: '0.9' },
+      },
+    });
+
+    selectText('Selected sentence.');
+    capture.captureNow();
+
+    const affordance = document.getElementById('askable-text-selection-affordance')!;
+    expect(affordance).toBeInstanceOf(HTMLElement);
+    expect(affordance.getAttribute('data-askable-text-selection-affordance')).toBe('true');
+    expect(affordance.className).toBe('custom-text-affordance');
+    expect(affordance.style.opacity).toBe('0.9');
+    expect(affordance.textContent).toContain('Quoted text');
+    expect(affordance.querySelectorAll('span').length).toBeGreaterThanOrEqual(2);
+
+    capture.clearSelection();
+    expect(document.getElementById('askable-text-selection-affordance')).toBeNull();
+
+    capture.destroy();
+    ctx.destroy();
+  });
+
+  it('renders an anchored selected text prompt and calls onSubmit with the captured packet', () => {
+    const ctx = createAskableContext();
+    const onSubmit = vi.fn();
+    const capture = createAskableTextSelectionCapture(ctx, {
+      source: { app: 'reader' },
+      selectionAffordance: {
+        prompt: {
+          placeholder: 'Ask about quote',
+          submitLabel: 'Send text question',
+          onSubmit,
+        },
+      },
+    });
+
+    selectText('Explain this sentence.');
+    capture.captureNow();
+
+    const affordance = document.getElementById('askable-text-selection-affordance')!;
+    const input = affordance.querySelector('input')!;
+    const button = affordance.querySelector('button')!;
+    input.value = 'What does this mean?';
+    button.click();
+
+    expect(input.placeholder).toBe('Ask about quote');
+    expect(button.getAttribute('aria-label')).toBe('Send text question');
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit.mock.calls[0][0]).toBe('What does this mean?');
+    expect(onSubmit.mock.calls[0][1]).toMatchObject({
+      source: { app: 'reader' },
+      capture: { mode: 'text-selection' },
+      target: { text: 'Explain this sentence.' },
+    });
+    expect(onSubmit.mock.calls[0][2]).toMatchObject({
+      text: 'Explain this sentence.',
+      bounds: { x: 12, y: 20, width: 80, height: 18 },
+    });
+    expect(input.value).toBe('');
+
+    capture.destroy();
+    ctx.destroy();
+  });
+
+  it('keeps the selected text affordance when once stops listeners', () => {
+    const ctx = createAskableContext();
+    const capture = createAskableTextSelectionCapture(ctx, {
+      once: true,
+      selectionAffordance: true,
+    });
+
+    capture.start();
+    selectText('One shot selected text.');
+    const packet = capture.captureNow();
+
+    expect(packet).not.toBeNull();
+    expect(capture.isActive()).toBe(false);
+    expect(document.getElementById('askable-text-selection-affordance')).toBeInstanceOf(HTMLElement);
+
+    capture.destroy();
+    ctx.destroy();
+  });
+
   it('ignores selections outside the configured root', () => {
     const root = document.createElement('section');
     const outside = selectText('Outside selection');

packages/core/src/index.ts

@@ -1,6 +1,6 @@
 export { createAskableInspector } from './inspector.js';
 export { ASKABLE_REGION_CAPTURE_THEME, createAskableRegionCapture } from './capture.js';
-export { createAskableTextSelectionCapture } from './selection.js';
+export { ASKABLE_TEXT_SELECTION_CAPTURE_THEME, createAskableTextSelectionCapture } from './selection.js';
 export { a11yTextExtractor } from './a11y.js';
 export { createAskableCollectionSource, createAskableSource } from './sources.js';
 export { createAskablePageSource } from './page-source.js';
@@ -43,9 +43,13 @@ export type {
   AskableRegionCaptureTheme,
 } from './capture.js';
 export type {
+  AskableTextSelectionCaptureAffordanceOptions,
   AskableTextSelectionCaptureHandle,
   AskableTextSelectionCaptureOptions,
+  AskableTextSelectionCapturePromptOptions,
   AskableTextSelectionCaptureSelection,
+  AskableTextSelectionCaptureStyle,
+  AskableTextSelectionCaptureTheme,
 } from './selection.js';
 export type {
   AskableCollectionSourceData,