feat(text): adding getSelectedTextEx

Author: johnlindquist

src/lib/text.ts

@@ -2,16 +2,56 @@ import { Channel } from "../core/enum.js"
 
 global.getSelectedText = async () => {
   await global.hide()
+  await sendWait(Channel.KEYBOARD_COPY)
+  const result = await global.paste()
+  if (result?.replace(/[\r\n]/g, "") === "") return ""
+  return result
+}
+
+/**
+ * Robust selected text retrieval with polling and optional clipboard restore.
+ * Returns a structured result without changing existing getSelectedText.
+ */
+global.getSelectedTextEx = async (
+  options?: {
+    restoreClipboard?: boolean
+    timeoutMs?: number
+    pollMs?: number
+  }
+) => {
+  const restore = options?.restoreClipboard !== false
+  const timeoutMs = Number.isFinite(options?.timeoutMs) ? (options?.timeoutMs as number) : 1000
+  const pollMs = Number.isFinite(options?.pollMs) ? (options?.pollMs as number) : 75
 
+  const prev = await global.paste()
+  await global.hide()
   await sendWait(Channel.KEYBOARD_COPY)
 
-  const result = await global.paste()
+  const start = Date.now()
+  let current = ""
+  while (Date.now() - start < timeoutMs) {
+    current = await global.paste()
+    if (current && current !== prev) break
+    await new Promise((r) => setTimeout(r, pollMs))
+  }
 
-  if (result?.replace(/[\r\n]/g, "") === "") {
-    return ""
+  // Classify
+  const value = current || ""
+  const ok = Boolean(value)
+  const reason = ok ? undefined : (prev ? "unchanged" : "no-selection")
+
+  if (restore) {
+    try {
+      // Only restore if we actually changed the clipboard and we still hold that value
+      if (ok && (await global.paste()) === value) {
+        await global.copy(prev)
+      }
+    } catch {
+      // ignore restore errors
+    }
   }
 
-  return result
+  return { ok, value, reason }
 }
 
 /**
@@ -22,13 +62,15 @@ await setSelectedText(`Script Kit is awesome!`)
 ```
 */
 
-global.setSelectedText = async (text = "", hide = true) => {
+global.setSelectedText = async (
+  text: string = "",
+  options?: boolean | { hide?: boolean; method?: "typing" | "clipboard" | "auto" }
+) => {
+  // Back-compat: second param as boolean means hide
+  const hide = typeof options === "boolean" ? options : options?.hide !== false
+  const method = typeof options === "object" ? options?.method : undefined
   if (hide) await global.hide()
-
-  return await sendWait(Channel.SET_SELECTED_TEXT, {
-    text,
-    hide,
-  })
+  return await sendWait(Channel.SET_SELECTED_TEXT, { text, hide, method })
 }
 
 global.cutText = () => sendWait(Channel.CUT_TEXT)

src/types/platform.d.ts

@@ -316,7 +316,16 @@ type Say = (text: string, options?: any) => Promise<string>
 
 type Beep = () => Promise<void>
 
-type SetSelectedText = (text: string, hide?: boolean) => Promise<void>
+type SetSelectedText = (
+  text: string,
+  hideOrOptions?: boolean | { hide?: boolean; method?: 'typing' | 'clipboard' | 'auto' }
+) => Promise<void>
+
+type GetSelectedTextEx = (options?: {
+  restoreClipboard?: boolean
+  timeoutMs?: number
+  pollMs?: number
+}) => Promise<{ ok: boolean; value: string; reason?: 'unchanged' | 'no-selection' }>
 
 type KeyStroke = (keyString: string) => Promise<string>
 
@@ -646,10 +655,15 @@ declare global {
    * ```ts
    * await setSelectedText("Hello from Script Kit!");
    * ```
-   * Grab text from the focused app. Literally triggers a "cmd?ctrl+c", so expect a similar behavior.
-   * [Examples](https://scriptkit.com?query=setSelectedText) | [Docs](https://johnlindquist.github.io/kit-docs/#setSelectedText) | [Discussions](https://github.com/johnlindquist/kit/discussions?discussions_q=setSelectedText)
-   */
+  * Grab text from the focused app. Literally triggers a "cmd?ctrl+c", so expect a similar behavior.
+  * [Examples](https://scriptkit.com?query=setSelectedText) | [Docs](https://johnlindquist.github.io/kit-docs/#setSelectedText) | [Discussions](https://github.com/johnlindquist/kit/discussions?discussions_q=setSelectedText)
+  */
   var setSelectedText: SetSelectedText
+  /**
+   * Robust selected text retrieval that optionally restores the previous clipboard
+   * and provides structured results for downstream logic.
+   */
+  var getSelectedTextEx: GetSelectedTextEx
   var setSelectedFile: SetSelectedFile
   var setWindowBoundsByIndex: SetWindowBoundsByIndex
   /**