@glassly/miniapp 0.3.0-dev.1

package/src/react/useCapabilities.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview useCapabilities — React hook for the connected glasses'
+ * capability profile.
+ *
+ * The glasses `GlassesCapabilities` profile is *background-only* state: it
+ * arrives on the background `MiniappSession` (CONNECT_ACK / CAPABILITIES_UPDATE)
+ * and is never injected into the UI WebView, so there is no WebView-side source
+ * for it — this hook always returns `null`.
+ *
+ * If a UI page needs glasses capabilities, relay them from the background half
+ * over an app channel: read `session.capabilities` in a `session.ui.onOpen`
+ * handler, `session.ui.send("caps", ...)`, then read it in the UI with
+ * `glassly.on("caps", ...)`. See the example miniapp's `captions:snapshot`
+ * channel for the pattern.
+ *
+ * IMPORTANT: this hook must NOT construct a `MiniappSession`. That is the
+ * *background* (JSContext) API; inside a UI WebView its `CONNECT` never gets an
+ * ACK from the host's UI router and `session.connect()` times out
+ * ("CONNECT_ACK timeout") — the original reason this hook was rewritten.
+ *
+ * (Note: `window.Glassly.capabilities` is a different thing — host *feature*
+ * flags like "share" / "open_url", not the glasses hardware profile.)
+ */
+
+import {type GlassesCapabilities} from "../session"
+
+export function useCapabilities(): GlassesCapabilities | null {
+  return null
+}

package/src/react/useCapsuleHeaderStyle.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview useCapsuleHeaderStyle — ready-to-spread React CSS props that
+ * vertically align a header row with the host's floating capsule menu.
+ *
+ * Use this when you want full control over header markup but want the
+ * alignment math done for you. If you just want a stock header, use
+ * <MiniappHeader> instead.
+ *
+ * Example:
+ *   const style = useCapsuleHeaderStyle()
+ *   <header style={style}>
+ *     <h1>Hello</h1>
+ *   </header>
+ */
+
+import type {CSSProperties} from "react"
+
+import {getCapsuleHeaderPaddingRight} from "./capsuleHeaderLayout"
+import {useSafeArea} from "./useSafeArea"
+
+export interface UseCapsuleHeaderStyleOptions {
+  /** Extra left padding beyond the safe area. Default 20px. */
+  leftPadding?: number
+  /** Extra space between the header content and the capsule menu. Default 16px. */
+  rightGap?: number
+  /** Fallback header height when no capsule menu is present. Default 32px. */
+  fallbackHeight?: number
+  /** Fallback top margin when no capsule menu is present. Default 16px. */
+  fallbackMarginTop?: number
+}
+
+export function useCapsuleHeaderStyle(options: UseCapsuleHeaderStyleOptions = {}): CSSProperties {
+  const {leftPadding = 20, rightGap = 16, fallbackHeight = 32, fallbackMarginTop = 16} = options
+  const {insets, capsuleMenu} = useSafeArea()
+
+  const height = capsuleMenu?.height ?? fallbackHeight
+  const center = capsuleMenu ? capsuleMenu.top + capsuleMenu.height / 2 - insets.top : fallbackMarginTop + height / 2
+  const marginTop = Math.max(0, center - height / 2)
+  const paddingRight = capsuleMenu
+    ? typeof window === "undefined"
+      ? capsuleMenu.width + rightGap
+      : getCapsuleHeaderPaddingRight(capsuleMenu, window.innerWidth, insets.right, rightGap)
+    : leftPadding
+
+  return {
+    display: "flex",
+    flexShrink: 0,
+    alignItems: "center",
+    justifyContent: "space-between",
+    paddingLeft: leftPadding,
+    paddingRight,
+    marginTop,
+    height,
+  }
+}

package/src/react/useColorScheme.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview useColorScheme — React hook that returns the host's current
+ * color scheme.
+ *
+ * WebView-side hook: reads `window.Glassly.colorScheme`, injected by the host
+ * before the miniapp's content loads. Like `useSafeArea`, this is read once at
+ * mount — the host doesn't push color-scheme changes to the WebView at runtime;
+ * flipping the phone's theme forces a reload.
+ *
+ * IMPORTANT: this hook must NOT construct a `MiniappSession`. `MiniappSession`
+ * is the *background* (JSContext) API; inside a UI WebView its transport falls
+ * back to PostMessage and its `CONNECT` never gets an ACK from the host's UI
+ * router, so `session.connect()` times out ("CONNECT_ACK timeout"). UI hooks
+ * read host-injected globals instead (see `useSafeArea`).
+ */
+
+import {useState} from "react"
+
+import {getGlasslyGlobals, type MiniappColorScheme} from "../globals"
+
+export function useColorScheme(): MiniappColorScheme {
+  const [scheme] = useState<MiniappColorScheme>(() => {
+    return getGlasslyGlobals().colorScheme === "dark" ? "dark" : "light"
+  })
+  return scheme
+}

package/src/react/useConnected.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview useConnected — React hook that returns true while the miniapp's
+ * UI WebView is bridged to its background JSContext.
+ *
+ * WebView-side hook. "Connected" here means the `window.glassly` bridge is open:
+ * the shim has fired `glassly.ready()` and the host has bound the WebView so
+ * `glassly.send/on/request` flow. Tracked via the shim's `onOpen` / `onClose`.
+ * `onOpen` fires its callback immediately if the bridge is already open (see
+ * the shim), so late mounts still observe the connected state.
+ *
+ * IMPORTANT: this hook must NOT construct a `MiniappSession`. That is the
+ * *background* (JSContext) API; inside a UI WebView its `CONNECT` never gets an
+ * ACK from the host's UI router and `session.connect()` times out
+ * ("CONNECT_ACK timeout").
+ */
+
+import {useEffect, useState} from "react"
+
+interface Bridge {
+  onOpen?: (cb: () => void) => () => void
+  onClose?: (cb: () => void) => () => void
+}
+
+function getBridge(): Bridge | null {
+  if (typeof window === "undefined") return null
+  return (window as unknown as {glassly?: Bridge}).glassly ?? null
+}
+
+export function useConnected(): boolean {
+  const [connected, setConnected] = useState<boolean>(false)
+
+  useEffect(() => {
+    const bridge = getBridge()
+    if (!bridge) return
+
+    // onOpen fires immediately when the bridge is already open, so this also
+    // seeds the initial value without a separate synchronous read.
+    const offOpen = bridge.onOpen?.(() => setConnected(true))
+    const offClose = bridge.onClose?.(() => setConnected(false))
+    return () => {
+      offOpen?.()
+      offClose?.()
+    }
+  }, [])
+
+  return connected
+}

package/src/react/useRpc.ts

@@ -0,0 +1,103 @@
+/**
+ * useRpc — React hook around `glassly.request(channel, ...)`.
+ *
+ * Returns a stable callable plus an `.abort()` method. The internal
+ * AbortController is recreated per call and bound to component lifecycle:
+ *
+ *   - Calling the returned function once: abort() the previous in-flight
+ *     call (if any), then issue a fresh request. Useful for per-keystroke
+ *     autocomplete — every keystroke aborts the stale request.
+ *   - Unmount: all in-flight calls abort.
+ *   - Caller-provided `options.signal` is merged with the internal one
+ *     via `AbortSignal.any` when available; manual fan-out otherwise.
+ */
+
+import {useCallback, useEffect, useRef} from "react"
+
+import type {RpcReq, RpcRes, RpcRequestOptions} from "../modules/ui"
+
+type RequestFn = (channel: string, payload: unknown, options?: RpcRequestOptions) => Promise<unknown>
+
+/** Walk to the global `glassly.request` (typed). */
+function getGlasslyRequest(): RequestFn {
+  const m = (globalThis as unknown as {glassly?: {request?: RequestFn}}).glassly
+  if (!m || typeof m.request !== "function") {
+    throw new Error(
+      "useRpc: window.glassly.request is not available — is this miniapp running in a UI WebView with the shim injected?",
+    )
+  }
+  return m.request
+}
+
+/** AbortSignal.any polyfill — combine multiple signals into one. */
+function mergeSignals(signals: AbortSignal[]): AbortSignal {
+  type WithAny = {any?: (s: AbortSignal[]) => AbortSignal}
+  const ctor = AbortSignal as unknown as WithAny
+  if (typeof ctor.any === "function") return ctor.any(signals)
+  const ctrl = new AbortController()
+  const onAbort = (sig: AbortSignal) => {
+    if (!ctrl.signal.aborted) ctrl.abort(sig.reason)
+  }
+  for (const s of signals) {
+    if (s.aborted) {
+      onAbort(s)
+      break
+    }
+    s.addEventListener("abort", () => onAbort(s))
+  }
+  return ctrl.signal
+}
+
+export interface RpcCallable<TChannels extends object, C extends keyof TChannels & string> {
+  (payload: RpcReq<TChannels[C]>, options?: RpcRequestOptions): Promise<RpcRes<TChannels[C]>>
+  /** Abort the current in-flight call (if any). No-op if nothing is pending. */
+  abort(): void
+}
+
+/**
+ * Returns a stable callable for an RPC channel. The callable auto-aborts
+ * on unmount and exposes `.abort()` for cancel-previous patterns.
+ *
+ *   const autocomplete = useRpc<Channels, "places:autocomplete">("places:autocomplete")
+ *   const suggestions = await autocomplete({query: "..."})
+ *   autocomplete.abort()   // cancel the latest in-flight call
+ */
+export function useRpc<TChannels extends object, C extends keyof TChannels & string>(
+  channel: C,
+): RpcCallable<TChannels, C> {
+  // Latest in-flight controller. Replaced on each call.
+  const currentRef = useRef<AbortController | null>(null)
+  // Mount controller — aborts every in-flight call on unmount.
+  const mountRef = useRef<AbortController | null>(null)
+  if (mountRef.current == null) mountRef.current = new AbortController()
+
+  useEffect(() => {
+    const mount = mountRef.current!
+    return () => {
+      mount.abort()
+      currentRef.current?.abort()
+      currentRef.current = null
+    }
+  }, [])
+
+  const callable = useCallback(
+    (payload: RpcReq<TChannels[C]>, options?: RpcRequestOptions) => {
+      // Abort any previous call for this hook.
+      currentRef.current?.abort()
+      const ctrl = new AbortController()
+      currentRef.current = ctrl
+      const signals: AbortSignal[] = [ctrl.signal, mountRef.current!.signal]
+      if (options?.signal) signals.push(options.signal)
+      const signal = mergeSignals(signals)
+      return getGlasslyRequest()(channel, payload, {signal, timeout: options?.timeout}) as Promise<RpcRes<TChannels[C]>>
+    },
+    [channel],
+  ) as RpcCallable<TChannels, C>
+
+  callable.abort = () => {
+    currentRef.current?.abort()
+    currentRef.current = null
+  }
+
+  return callable
+}

package/src/react/useSafeArea.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview useSafeArea — React hook exposing the host's safe-area insets
+ * and the capsule menu rect to miniapp UIs.
+ *
+ * The host injects these via window.Glassly before content loads. This hook
+ * reads them once at mount — they don't currently change at runtime (the host
+ * would have to force a reload to update them, e.g. on orientation change).
+ */
+
+import {useState} from "react"
+
+import {getGlasslyGlobals, type MiniappCapsuleMenuRect, type MiniappSafeAreaInsets} from "../globals"
+
+const EMPTY_INSETS: MiniappSafeAreaInsets = {top: 0, bottom: 0, left: 0, right: 0}
+
+export interface UseSafeAreaResult {
+  /** Pixel insets around the WebView content. Apply as padding on your root element. */
+  insets: MiniappSafeAreaInsets
+  /**
+   * Bounding rect of the host's floating capsule menu (top-right overlay).
+   * Null when the host doesn't render one (e.g. older builds). Use this to
+   * avoid placing clickable content underneath the menu.
+   */
+  capsuleMenu: MiniappCapsuleMenuRect | null
+}
+
+export function useSafeArea(): UseSafeAreaResult {
+  const [result] = useState<UseSafeAreaResult>(() => {
+    const globals = getGlasslyGlobals()
+    return {
+      insets: globals.safeAreaInsets ?? EMPTY_INSETS,
+      capsuleMenu: globals.capsuleMenu ?? null,
+    }
+  })
+  return result
+}