@abraca/nuxt 1.9.1 → 2.0.0

package/dist/runtime/composables/useAAFocus.d.ts

@@ -0,0 +1,68 @@
+import { type DomPath } from '../utils/domPath.js';
+/**
+ * App-wide "focus" broadcast for collaborative awareness.
+ *
+ * Emits a single per-peer `peer:aa:focus` slot describing where the local
+ * user is currently looking. Two payload shapes share the same slot so
+ * downstream consumers (text-selection layer, smart scroll-follow) can pick
+ * the one they care about:
+ *
+ *   { kind: 'selection', route, start: DomPath, end: DomPath }
+ *   { kind: 'anchor',    route, anchor: DomPath }
+ *
+ * Selection takes precedence: if the user has a non-empty Selection the
+ * payload describes its endpoints; otherwise the payload anchors on the
+ * topmost scroll-visible element near the viewport top edge so that smart
+ * follow can centre the same conceptual region on a different-sized screen.
+ *
+ * The `route` discriminator scopes the payload — peers on different pages
+ * don't try to interpret each other's anchors. Other tabs only honour
+ * payloads whose route matches their own.
+ */
+/** Per-scroller anchor: identifies WHICH scroll container the anchor lives
+ *  inside (by its DOM path, or omitted for window) plus the element that's
+ *  currently top-visible inside that container and where it sits vertically.
+ *  Each scrollable container the leader has — main viewport, sidebar,
+ *  modal body, etc. — gets its own entry, so the follower can re-scroll
+ *  each local container independently. */
+export interface AAScrollAnchor {
+    /** Path to the scroll container element. Omitted = window/document. */
+    containerPath?: number[];
+    /** Path to the topmost-visible element inside that container. */
+    elementPath: number[];
+    /** Vertical position of the element relative to its container's viewport
+     *  (0 = top edge of container, 1 = bottom edge). */
+    ratio: number;
+}
+/** Element-anchored pointer: stores WHICH element the cursor is over plus
+ *  the offset within its bounding box. Receivers reconstruct the absolute
+ *  viewport position by looking up the same element in their own DOM and
+ *  adding the offset. Survives different scroll positions and viewport
+ *  sizes without falling out of sync. */
+export interface AAPointerAnchor {
+    elementPath: number[];
+    /** Offset from the element's top-left, in CSS pixels. */
+    dx: number;
+    dy: number;
+}
+export interface AAFocusPayload {
+    kind: 'selection' | 'anchor';
+    route: string;
+    start?: DomPath;
+    end?: DomPath;
+    /** Legacy single-anchor field (main viewport). Retained for backwards
+     *  compatibility with older follower clients; prefer reading `scrollers`. */
+    anchor?: DomPath;
+    anchorRatio?: number;
+    /** All scrollable containers the leader has, with their top-visible
+     *  anchor each. Lets the follower drive every scroller (main, sidebar,
+     *  modal, etc.) in step instead of just the main viewport. */
+    scrollers?: AAScrollAnchor[];
+    /** Element-anchored pointer position (path + offset within element). The
+     *  blob layer uses this to render the peer's mouse glow at the same
+     *  *content* position regardless of either tab's scroll state. */
+    pointer?: AAPointerAnchor;
+}
+export declare function useAAFocus(): {
+    snapshot: () => void;
+};

package/dist/runtime/composables/useAAFocus.js

@@ -0,0 +1,174 @@
+import { onMounted, onScopeDispose } from "vue";
+import { useRoute } from "#imports";
+import { useAAEphemeral } from "./useAAEphemeral.js";
+import { serializeRangeEndpoint, pathFromElement } from "../utils/domPath.js";
+export function useAAFocus() {
+  const { setLocal } = useAAEphemeral("aa:focus");
+  const route = useRoute();
+  let raf = 0;
+  let lastSerialized = null;
+  const pointer = { clientX: 0, clientY: 0, fresh: false };
+  function publish(payload) {
+    if (pointer.fresh) {
+      const anchor = serializePointer(pointer.clientX, pointer.clientY);
+      if (anchor) payload.pointer = anchor;
+    }
+    payload.scrollers = collectScrollers();
+    const json = JSON.stringify(payload);
+    if (json === lastSerialized) return;
+    lastSerialized = json;
+    setLocal(payload);
+  }
+  function clear() {
+    if (lastSerialized === null) return;
+    lastSerialized = null;
+    setLocal(null);
+  }
+  function isAnchorable(el) {
+    if (!el) return false;
+    if (el.closest?.("[data-aa-skip-anchor]")) return false;
+    if (el.id?.startsWith("reka-")) return false;
+    if (el.classList?.contains("aa-global-focus-layer")) return false;
+    if (el.classList?.contains("aa-presence-blobs")) return false;
+    if (el.classList?.contains("aa-follow-bar")) return false;
+    return true;
+  }
+  function pickAnchorElement() {
+    const viewportH = window.innerHeight || document.documentElement.clientHeight;
+    const targetY = viewportH * 0.25;
+    const candidates = document.elementsFromPoint(window.innerWidth / 2, targetY);
+    for (const el of candidates) {
+      if (!isAnchorable(el)) continue;
+      const rect = el.getBoundingClientRect();
+      return { el, ratio: rect.top / viewportH };
+    }
+    return null;
+  }
+  function collectScrollers() {
+    const out = [];
+    const winPick = pickElementInside(null);
+    if (winPick) out.push(winPick);
+    const all = document.querySelectorAll("*");
+    const seen = /* @__PURE__ */ new Set();
+    for (const el of all) {
+      if (seen.has(el)) continue;
+      seen.add(el);
+      if (!isAnchorable(el)) continue;
+      const style = getComputedStyle(el);
+      const oy = style.overflowY;
+      if (oy !== "auto" && oy !== "scroll" || el.scrollHeight <= el.clientHeight + 4) continue;
+      const containerPath = pathFromElement(el);
+      if (!containerPath) continue;
+      const pick = pickElementInside(el);
+      if (pick) out.push({ ...pick, containerPath });
+      if (out.length > 6) break;
+    }
+    return out;
+  }
+  function pickElementInside(container) {
+    let probeX, probeY, viewportTop, viewportH;
+    if (container) {
+      const r = container.getBoundingClientRect();
+      probeX = r.left + Math.min(r.width * 0.5, 80);
+      probeY = r.top + 6;
+      viewportTop = r.top;
+      viewportH = r.height;
+    } else {
+      const vh = window.innerHeight || document.documentElement.clientHeight;
+      probeX = window.innerWidth / 2;
+      probeY = vh * 0.05;
+      viewportTop = 0;
+      viewportH = vh;
+    }
+    const candidates = document.elementsFromPoint(probeX, probeY);
+    for (const el of candidates) {
+      if (!isAnchorable(el)) continue;
+      if (container && !container.contains(el)) continue;
+      if (container && el === container) continue;
+      const elPath = pathFromElement(el);
+      if (!elPath) continue;
+      const r = el.getBoundingClientRect();
+      const ratio = (r.top - viewportTop) / Math.max(1, viewportH);
+      return { elementPath: elPath, ratio };
+    }
+    return null;
+  }
+  function serializePointer(clientX, clientY) {
+    const candidates = document.elementsFromPoint(clientX, clientY);
+    for (const el of candidates) {
+      if (!isAnchorable(el)) continue;
+      const path = pathFromElement(el);
+      if (!path) continue;
+      const r = el.getBoundingClientRect();
+      return { elementPath: path, dx: clientX - r.left, dy: clientY - r.top };
+    }
+    return null;
+  }
+  function snapshot() {
+    cancelAnimationFrame(raf);
+    raf = requestAnimationFrame(() => {
+      const sel = window.getSelection();
+      if (sel && sel.rangeCount > 0 && !sel.isCollapsed) {
+        const range = sel.getRangeAt(0);
+        const anchor = range.startContainer instanceof Element ? range.startContainer : range.startContainer.parentElement;
+        if (anchor?.closest?.("input, textarea")) return;
+        if (anchor?.closest?.(".aa-caret-layer")) return;
+        if (anchor?.closest?.(".aa-global-focus-layer")) return;
+        const start = serializeRangeEndpoint(range.startContainer, range.startOffset);
+        const end = serializeRangeEndpoint(range.endContainer, range.endOffset);
+        if (start && end) {
+          publish({ kind: "selection", route: route.path, start, end });
+          return;
+        }
+      }
+      const picked = pickAnchorElement();
+      if (!picked) {
+        clear();
+        return;
+      }
+      const path = pathFromElement(picked.el);
+      if (!path) {
+        clear();
+        return;
+      }
+      publish({ kind: "anchor", route: route.path, anchor: { elementPath: path }, anchorRatio: picked.ratio });
+    });
+  }
+  function onSelectionChange() {
+    snapshot();
+  }
+  function onScroll() {
+    snapshot();
+  }
+  function onResize() {
+    snapshot();
+  }
+  function onPointerMove(e) {
+    pointer.clientX = e.clientX;
+    pointer.clientY = e.clientY;
+    pointer.fresh = true;
+    snapshot();
+  }
+  function onPointerLeave() {
+    pointer.fresh = false;
+    snapshot();
+  }
+  onMounted(() => {
+    document.addEventListener("selectionchange", onSelectionChange);
+    document.addEventListener("scroll", onScroll, { passive: true, capture: true });
+    document.addEventListener("pointermove", onPointerMove, { passive: true });
+    document.addEventListener("pointerleave", onPointerLeave);
+    window.addEventListener("resize", onResize, { passive: true });
+    snapshot();
+  });
+  onScopeDispose(() => {
+    cancelAnimationFrame(raf);
+    document.removeEventListener("selectionchange", onSelectionChange);
+    document.removeEventListener("scroll", onScroll, { capture: true });
+    document.removeEventListener("pointermove", onPointerMove);
+    document.removeEventListener("pointerleave", onPointerLeave);
+    window.removeEventListener("resize", onResize);
+    clear();
+  });
+  return { snapshot };
+}

package/dist/runtime/composables/useAAFollowAnchor.d.ts

@@ -0,0 +1,25 @@
+import { type Ref } from 'vue';
+import type { AAFocusPayload } from './useAAFocus.js';
+/**
+ * Smart anchor-based scroll-follow.
+ *
+ * Given a leader's `clientId` (or `publicKey`), this composable:
+ *   1. Watches the leader's `peer:aa:focus` payload
+ *   2. If the leader is on a different route, navigates the local browser
+ *      to match (via vue-router push)
+ *   3. Once on the same route, finds the leader's anchor element in the
+ *      LOCAL DOM and scrolls it to the same vertical position the leader
+ *      had it at — i.e. preserves the leader's `anchorRatio` rather than
+ *      copying raw scroll px. This keeps the experience consistent across
+ *      different viewport heights and zoom levels.
+ *
+ * Selection-kind payloads use the selection's start element as the anchor
+ * (the user is presumably reading where they're highlighting).
+ *
+ * Pass `null` (or `undefined`) for `leaderId` to disable the follow.
+ */
+export declare function useAAFollowAnchor(leaderId: Ref<number | null | undefined>): {
+    leader: import("vue").ComputedRef<import("../types.js").AwarenessPeer | null>;
+    leaderPayload: import("vue").ComputedRef<AAFocusPayload | null>;
+    scrollToLeader: () => void;
+};

package/dist/runtime/composables/useAAFollowAnchor.js

@@ -0,0 +1,69 @@
+import { computed, watch } from "vue";
+import { useRoute, useRouter } from "#imports";
+import { useAAEphemeral } from "./useAAEphemeral.js";
+import { useAwarenessPeers } from "./useAwarenessPeers.js";
+import { elementFromPath } from "../utils/domPath.js";
+export function useAAFollowAnchor(leaderId) {
+  const { peers } = useAAEphemeral("aa:focus");
+  const { peers: allPeers } = useAwarenessPeers();
+  const route = useRoute();
+  const router = useRouter();
+  let scrollRaf = 0;
+  let lastTargetKey = "";
+  const leaderPayload = computed(() => {
+    const id = leaderId.value;
+    if (id == null) return null;
+    const found = peers.value.find((p) => p.clientId === id);
+    return found?.value ?? null;
+  });
+  watch(leaderPayload, (payload) => {
+    if (!payload) return;
+    if (payload.route && payload.route !== route.path) {
+      router.push(payload.route).catch(() => {
+      });
+    }
+  }, { immediate: true });
+  function scrollToLeader() {
+    cancelAnimationFrame(scrollRaf);
+    scrollRaf = requestAnimationFrame(() => {
+      const payload = leaderPayload.value;
+      if (!payload) return;
+      if (payload.route !== route.path) return;
+      const instructions = [];
+      if (payload.scrollers && payload.scrollers.length) {
+        for (const s of payload.scrollers) {
+          instructions.push({ container: s.containerPath, element: s.elementPath, ratio: s.ratio });
+        }
+      } else if (payload.kind === "anchor" && payload.anchor) {
+        instructions.push({ element: payload.anchor.elementPath, ratio: payload.anchorRatio ?? 0.05 });
+      } else if (payload.kind === "selection" && payload.start) {
+        instructions.push({ element: payload.start.elementPath, ratio: 0.2 });
+      }
+      const fingerprint = [];
+      for (const ins of instructions) {
+        const target = elementFromPath(ins.element);
+        if (!target || !target.isConnected) continue;
+        const scroller = ins.container ? elementFromPath(ins.container) ?? window : window;
+        const isWindow = scroller === window;
+        const scrollerRect = isWindow ? { top: 0, height: window.innerHeight || document.documentElement.clientHeight } : scroller.getBoundingClientRect();
+        const desiredTop = scrollerRect.top + scrollerRect.height * Math.max(0, Math.min(0.9, ins.ratio));
+        const rect = target.getBoundingClientRect();
+        const delta = rect.top - desiredTop;
+        fingerprint.push(`${isWindow ? "w" : ins.container?.join(",")}-${Math.round(rect.top)}-${ins.ratio.toFixed(3)}`);
+        if (Math.abs(delta) < 8) continue;
+        if (isWindow) window.scrollBy({ top: delta, behavior: "smooth" });
+        else scroller.scrollBy({ top: delta, behavior: "smooth" });
+      }
+      const key = fingerprint.join("|");
+      if (key === lastTargetKey) return;
+      lastTargetKey = key;
+    });
+  }
+  watch(leaderPayload, scrollToLeader, { deep: true, flush: "post" });
+  const leader = computed(() => {
+    const id = leaderId.value;
+    if (id == null) return null;
+    return allPeers.value.find((p) => p.clientId === id) ?? null;
+  });
+  return { leader, leaderPayload, scrollToLeader };
+}

package/dist/runtime/composables/useAAFollowPeer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Follow another peer's `aware-ui` keys live. Reads the target peer's most
+ * recent writes to the shared `aware-ui` Y.Map and re-applies them locally
+ * by writing the same `{value, by, ts}` shape under our own clientId, so any
+ * `live`-bound aware component snaps to the leader's UI state (active tab,
+ * expanded accordion, current page, modal open, etc.).
+ *
+ * Activation is explicit — call `follow(clientId)` from `<AFollowBar>`. Local
+ * interaction (any keystroke, click, or scroll) calls `unfollow()` so the
+ * follower can break out at any time.
+ *
+ * Optional `keyPrefix` scopes the follow to a subset of UI keys; default
+ * follows everything the leader writes.
+ */
+export interface UseAAFollowPeerOptions {
+    /** Only mirror keys that start with this prefix. */
+    keyPrefix?: string;
+    /** Hook fired when the user breaks follow via local interaction. */
+    onBreak?: () => void;
+}
+export declare function useAAFollowPeer(options?: UseAAFollowPeerOptions): {
+    follow: (clientId: number) => void;
+    unfollow: () => void;
+    followingClientId: import("vue").Ref<number | null, number | null>;
+    followingUser: import("vue").ComputedRef<{
+        name?: string;
+        color?: string;
+    } | null>;
+};

package/dist/runtime/composables/useAAFollowPeer.js

@@ -0,0 +1,75 @@
+import { computed, onScopeDispose, ref, watch } from "vue";
+import { useAbracadabra } from "./useAbracadabra.js";
+import { useSyncedMap } from "./useYDoc.js";
+import { useAwareness } from "./useAwareness.js";
+const _followingClientId = ref(null);
+export function useAAFollowPeer(options = {}) {
+  const { doc, provider } = useAbracadabra();
+  const { data, set } = useSyncedMap(doc, "aware-ui");
+  const { states } = useAwareness();
+  const followingClientId = _followingClientId;
+  let unsubInteraction = null;
+  const followingUser = computed(() => {
+    if (followingClientId.value == null) return null;
+    const state = states.value.get(followingClientId.value);
+    return state?.user ?? null;
+  });
+  function detachInteraction() {
+    unsubInteraction?.();
+    unsubInteraction = null;
+  }
+  function attachInteractionBreaker() {
+    detachInteraction();
+    if (typeof window === "undefined") return;
+    const onBreak = () => unfollow();
+    window.addEventListener("keydown", onBreak);
+    window.addEventListener("pointerdown", onBreak);
+    window.addEventListener("wheel", onBreak, { passive: true });
+    unsubInteraction = () => {
+      window.removeEventListener("keydown", onBreak);
+      window.removeEventListener("pointerdown", onBreak);
+      window.removeEventListener("wheel", onBreak);
+    };
+  }
+  function follow(clientId) {
+    if (followingClientId.value === clientId) return;
+    followingClientId.value = clientId;
+    attachInteractionBreaker();
+  }
+  function unfollow() {
+    if (followingClientId.value == null) return;
+    followingClientId.value = null;
+    detachInteraction();
+    options.onBreak?.();
+  }
+  const myClientId = computed(() => provider.value?.awareness?.clientID);
+  watch(
+    () => Object.entries(data),
+    (entries) => {
+      const target = followingClientId.value;
+      if (target == null) return;
+      const me = myClientId.value;
+      const prefix = options.keyPrefix;
+      for (const [key, entry] of entries) {
+        if (!entry || typeof entry !== "object") continue;
+        if (entry.by !== target) continue;
+        if (prefix && !key.startsWith(prefix)) continue;
+        set(key, { value: entry.value, by: me, ts: Date.now() });
+      }
+    },
+    { deep: true }
+  );
+  watch(followingClientId, (target) => {
+    if (target == null) return;
+    const me = myClientId.value;
+    const prefix = options.keyPrefix;
+    for (const [key, entry] of Object.entries(data)) {
+      if (!entry || typeof entry !== "object") continue;
+      if (entry.by !== target) continue;
+      if (prefix && !key.startsWith(prefix)) continue;
+      set(key, { value: entry.value, by: me, ts: Date.now() });
+    }
+  });
+  onScopeDispose(detachInteraction);
+  return { follow, unfollow, followingClientId, followingUser };
+}

package/dist/runtime/composables/useAAKey.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Broadcast the local user's most recent shortcut press as a short-lived
+ * ephemeral field. Receivers (`<AKeyHint>`, presence overlays) flash a brief
+ * "Janis just pressed ⌘K" indicator on the avatar.
+ *
+ * Each `pressKey(label)` call publishes `{ label, ts }` for ~1s, then auto-
+ * clears so peers don't see stale shortcuts.
+ */
+export interface PeerKeyHint {
+    clientId: number;
+    label: string;
+    ts: number;
+    user?: {
+        name?: string;
+        color?: string;
+        publicKey?: string;
+    };
+}
+export declare function useAAKey(): {
+    pressKey: (label: string) => void;
+    hints: import("vue").ComputedRef<PeerKeyHint[]>;
+};

package/dist/runtime/composables/useAAKey.js

@@ -0,0 +1,24 @@
+import { computed, onScopeDispose } from "vue";
+import { useAAEphemeral } from "./useAAEphemeral.js";
+const HOLD_MS = 1e3;
+export function useAAKey() {
+  const { peers, setLocal } = useAAEphemeral(() => "key:last");
+  let timer = null;
+  function pressKey(label) {
+    if (timer) clearTimeout(timer);
+    setLocal({ label, ts: Date.now() });
+    timer = setTimeout(() => {
+      setLocal(null);
+      timer = null;
+    }, HOLD_MS);
+  }
+  onScopeDispose(() => {
+    if (timer) clearTimeout(timer);
+    setLocal(null);
+  });
+  const hints = computed(() => {
+    const now = Date.now();
+    return peers.value.filter((p) => p.value && now - p.value.ts < HOLD_MS).map((p) => ({ clientId: p.clientId, label: p.value.label, ts: p.value.ts, user: p.user }));
+  });
+  return { pressKey, hints };
+}

package/dist/runtime/composables/useAAPointer.d.ts

@@ -0,0 +1,30 @@
+import { type Ref } from 'vue';
+import type { MaybeRefOrGetter } from 'vue';
+/**
+ * Per-peer free-floating mouse pointer position over a scoped element.
+ *
+ * The local pointer position (relative to the scoped element's bounding box)
+ * is broadcast as `peer:pointer:<scope>` ephemeral state, RAF-throttled to
+ * the display refresh rate. Reads return every other peer's `{ x, y, vis }`
+ * with their user info attached, ready for rendering by `<APresenceCursors>`.
+ *
+ * Coordinates are normalised in [0, 1] so receivers can render at their own
+ * element size without sender-side knowledge of viewport dimensions.
+ */
+export interface PeerPointer {
+    clientId: number;
+    /** Normalised x within the scope element (0..1). */
+    x: number;
+    /** Normalised y within the scope element (0..1). */
+    y: number;
+    /** Whether the peer's pointer is inside the scope right now. */
+    vis: boolean;
+    user?: {
+        name?: string;
+        color?: string;
+        publicKey?: string;
+    };
+}
+export declare function useAAPointer(scope: MaybeRefOrGetter<string>, elementRef: Ref<HTMLElement | null | undefined>): {
+    pointers: import("vue").ComputedRef<PeerPointer[]>;
+};

package/dist/runtime/composables/useAAPointer.js

@@ -0,0 +1,53 @@
+import { computed, onScopeDispose, watch } from "vue";
+import { useAAEphemeral } from "./useAAEphemeral.js";
+export function useAAPointer(scope, elementRef) {
+  const slot = computed(() => `pointer:${typeof scope === "function" ? scope() : scope?.value ?? scope}`);
+  const { peers, setLocal } = useAAEphemeral(slot);
+  let raf = 0;
+  let pending = null;
+  function flush() {
+    raf = 0;
+    if (pending) setLocal(pending);
+  }
+  function onMove(e) {
+    const el = elementRef.value;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return;
+    const x = (e.clientX - rect.left) / rect.width;
+    const y = (e.clientY - rect.top) / rect.height;
+    pending = { x, y, vis: x >= 0 && x <= 1 && y >= 0 && y <= 1 };
+    if (!raf) raf = requestAnimationFrame(flush);
+  }
+  function onLeave() {
+    pending = { x: 0, y: 0, vis: false };
+    if (!raf) raf = requestAnimationFrame(flush);
+  }
+  let attached = null;
+  function attach(el) {
+    if (attached === el) return;
+    detach();
+    attached = el;
+    el.addEventListener("pointermove", onMove);
+    el.addEventListener("pointerleave", onLeave);
+  }
+  function detach() {
+    if (!attached) return;
+    attached.removeEventListener("pointermove", onMove);
+    attached.removeEventListener("pointerleave", onLeave);
+    attached = null;
+    setLocal(null);
+  }
+  watch(elementRef, (el) => {
+    if (el) attach(el);
+    else detach();
+  }, { immediate: true, flush: "post" });
+  onScopeDispose(() => {
+    if (raf) cancelAnimationFrame(raf);
+    detach();
+  });
+  const pointers = computed(
+    () => peers.value.filter((p) => p.value.vis).map((p) => ({ clientId: p.clientId, x: p.value.x, y: p.value.y, vis: p.value.vis, user: p.user }))
+  );
+  return { pointers };
+}

package/dist/runtime/composables/useAAUIState.d.ts

@@ -0,0 +1,29 @@
+import { type WritableComputedRef } from 'vue';
+import type { MaybeRefOrGetter } from 'vue';
+/**
+ * Shared UI state across every connected tab — the building block under the
+ * `live` prop on every aware component.
+ *
+ * Stores a single value keyed by `fieldKey` on a shared Y.Map called
+ * `aware-ui` on the root Y.Doc. All connected peers read and write the same
+ * record, so opening a dropdown / expanding an accordion / switching a tab
+ * happens *live* on every screen.
+ *
+ * Distinct from `useAAFieldValue`:
+ *   - `useAAFieldValue` stores the *bound primitive value* (input text, switch on/off)
+ *   - `useAAUIState` stores *UI chrome state* (open, expanded, sort col, current page)
+ *   - Different Y.Map names so reset / introspection / TTL logic stay separate.
+ *
+ * Each entry carries `{ value, by, ts }` so receivers can attribute the
+ * change ("opened by Janis") and apply last-write-wins on conflict.
+ */
+export interface UseAAUIStateOptions<T> {
+    /** Returned when no entry exists yet. */
+    defaultValue?: T;
+}
+export declare function useAAUIState<T = unknown>(fieldKey: MaybeRefOrGetter<string>, options?: UseAAUIStateOptions<T>): WritableComputedRef<T | undefined>;
+/**
+ * Read who last wrote a given live UI field — used to render attribution
+ * labels ("opened by Janis") in `live` components.
+ */
+export declare function useAAUIStateAuthor(fieldKey: MaybeRefOrGetter<string>): import("vue").ComputedRef<number | undefined>;

package/dist/runtime/composables/useAAUIState.js

@@ -0,0 +1,28 @@
+import { computed } from "vue";
+import { useAbracadabra } from "./useAbracadabra.js";
+import { useSyncedMap } from "./useYDoc.js";
+function resolveKey(fieldKey) {
+  if (typeof fieldKey === "function") return fieldKey();
+  if (fieldKey && typeof fieldKey === "object" && "value" in fieldKey) return fieldKey.value;
+  return fieldKey;
+}
+export function useAAUIState(fieldKey, options = {}) {
+  const { doc, provider } = useAbracadabra();
+  const { data, set } = useSyncedMap(doc, "aware-ui");
+  return computed({
+    get() {
+      const entry = data[resolveKey(fieldKey)];
+      if (!entry) return options.defaultValue;
+      return entry.value;
+    },
+    set(value) {
+      const by = provider.value?.awareness?.clientID;
+      set(resolveKey(fieldKey), { value, by, ts: Date.now() });
+    }
+  });
+}
+export function useAAUIStateAuthor(fieldKey) {
+  const { doc } = useAbracadabra();
+  const { data } = useSyncedMap(doc, "aware-ui");
+  return computed(() => data[resolveKey(fieldKey)]?.by);
+}

package/dist/runtime/composables/useAAViewport.d.ts

@@ -0,0 +1,22 @@
+import { type Ref } from 'vue';
+import type { MaybeRefOrGetter } from 'vue';
+/**
+ * IntersectionObserver-based "what section is this peer currently looking at"
+ * — broadcasts the data-section attribute of the most-visible region under a
+ * scoped container as `peer:viewport:<scope>` ephemeral state.
+ *
+ * Use case: render "Janis is reading the API section" overlays in long docs.
+ * Pair with `<APresenceCursors>` for a complete spatial-presence layer.
+ */
+export interface PeerViewport {
+    clientId: number;
+    section: string;
+    user?: {
+        name?: string;
+        color?: string;
+        publicKey?: string;
+    };
+}
+export declare function useAAViewport(scope: MaybeRefOrGetter<string>, elementRef: Ref<HTMLElement | null | undefined>): {
+    viewports: import("vue").ComputedRef<PeerViewport[]>;
+};