@abraca/nuxt 1.9.1 → 2.0.1

package/dist/runtime/components/renderers/timeline/ATimelineMilestone.d.vue.ts

@@ -8,6 +8,10 @@ type __VLS_Props = {
         name: string;
         color: string;
     }>;
+    viewers?: Array<{
+        name: string;
+        color: string;
+    }>;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     click: (id: string, label: string) => any;

package/dist/runtime/components/renderers/timeline/ATimelineMilestone.vue

@@ -1,10 +1,12 @@
 <script setup>
+import { avatarBorderStyle } from "../../../utils/avatarStyle";
 defineProps({
   entry: { type: Object, required: true },
   left: { type: Number, required: true },
   color: { type: String, required: true },
   isDragging: { type: Boolean, required: false },
-  focusers: { type: Array, required: false }
+  focusers: { type: Array, required: false },
+  viewers: { type: Array, required: false }
 });
 const emit = defineEmits(["pointer-down", "pointer-enter", "pointer-leave", "click"]);
 </script>
@@ -20,9 +22,24 @@ const emit = defineEmits(["pointer-down", "pointer-enter", "pointer-leave", "cli
     @pointerleave="emit('pointer-leave')"
     @click.stop="emit('click', entry.id, entry.label)"
   >
-    <!-- Remote hover badge -->
+    <!-- Remote viewer cluster (slideover/full open) — overrides hover badge -->
+    <div
+      v-if="viewers?.length"
+      class="absolute -top-2.5 left-0 flex -space-x-1 z-20 pointer-events-none"
+    >
+      <UAvatar
+        v-for="(u, i) in viewers.slice(0, 3)"
+        :key="`v-${i}`"
+        size="3xs"
+        :alt="u.name"
+        :title="u.name"
+        :style="avatarBorderStyle(u.color, 'zinc')"
+      />
+    </div>
+
+    <!-- Remote hover badge (only when no viewer is shown) -->
     <span
-      v-if="focusers?.length"
+      v-else-if="focusers?.length"
       class="absolute -top-3 left-0 text-[10px] px-1 rounded text-white leading-tight z-10 pointer-events-none"
       :style="{ backgroundColor: focusers[0].color }"
     >
@@ -34,7 +51,7 @@ const emit = defineEmits(["pointer-down", "pointer-enter", "pointer-leave", "cli
       class="w-4 h-4 rotate-45 rounded-sm shrink-0"
       :style="{
   background: color,
-  ...focusers?.length ? { outline: `2px solid ${focusers[0].color}`, outlineOffset: '1px' } : {}
+  ...viewers?.length ? { outline: `4px solid ${viewers[0].color}`, outlineOffset: '1px' } : focusers?.length ? { outline: `2px solid ${focusers[0].color}`, outlineOffset: '1px' } : {}
 }"
     />
 

package/dist/runtime/components/renderers/timeline/ATimelineMilestone.vue.d.ts

@@ -8,6 +8,10 @@ type __VLS_Props = {
         name: string;
         color: string;
     }>;
+    viewers?: Array<{
+        name: string;
+        color: string;
+    }>;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     click: (id: string, label: string) => any;

package/dist/runtime/components/renderers/timeline/ATimelineToolbar.d.vue.ts

@@ -12,18 +12,18 @@ type __VLS_Props = {
     labels?: Partial<AbracadabraLocale['renderers']['timeline']>;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    today: () => any;
     "zoom-in": () => any;
     "zoom-out": () => any;
+    today: () => any;
     "go-to-date": (date: string) => any;
     "add-epic": () => any;
     "add-milestone": () => any;
     "toggle-labels": () => any;
     fit: () => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onToday?: (() => any) | undefined;
     "onZoom-in"?: (() => any) | undefined;
     "onZoom-out"?: (() => any) | undefined;
+    onToday?: (() => any) | undefined;
     "onGo-to-date"?: ((date: string) => any) | undefined;
     "onAdd-epic"?: (() => any) | undefined;
     "onAdd-milestone"?: (() => any) | undefined;

package/dist/runtime/components/renderers/timeline/ATimelineToolbar.vue.d.ts

@@ -12,18 +12,18 @@ type __VLS_Props = {
     labels?: Partial<AbracadabraLocale['renderers']['timeline']>;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    today: () => any;
     "zoom-in": () => any;
     "zoom-out": () => any;
+    today: () => any;
     "go-to-date": (date: string) => any;
     "add-epic": () => any;
     "add-milestone": () => any;
     "toggle-labels": () => any;
     fit: () => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onToday?: (() => any) | undefined;
     "onZoom-in"?: (() => any) | undefined;
     "onZoom-out"?: (() => any) | undefined;
+    onToday?: (() => any) | undefined;
     "onGo-to-date"?: ((date: string) => any) | undefined;
     "onAdd-epic"?: (() => any) | undefined;
     "onAdd-milestone"?: (() => any) | undefined;

package/dist/runtime/components/settings/ASettingsSpacesPanel.vue

@@ -1,7 +1,7 @@
 <script setup>
 import { ref } from "vue";
 import { useSpaces } from "../../composables/useSpaces";
-const { spaces, spacesEnabled, currentSpace, create, remove, switchTo, loading, error } = useSpaces();
+const { spaces, currentSpace, create, remove, switchTo, loading, error } = useSpaces();
 const showCreateForm = ref(false);
 const newName = ref("");
 const newDescription = ref("");
@@ -59,16 +59,6 @@ async function handleDelete(id) {
       />
     </div>
 
-    <UAlert
-      v-if="!spacesEnabled"
-      color="info"
-      variant="soft"
-      icon="i-lucide-info"
-      title="Spaces not enabled"
-      description="This server does not support multiple spaces."
-      class="mb-4"
-    />
-
     <UAlert
       v-if="error"
       color="error"
@@ -115,7 +105,7 @@ async function handleDelete(id) {
     <div class="flex flex-col gap-1">
       <div
         v-for="space in spaces"
-        :key="space.doc_id"
+        :key="space.id"
         class="flex items-center gap-3 p-3 rounded-lg border border-(--ui-border) hover:bg-(--ui-bg-elevated)/50 transition-colors"
       >
         <UIcon
@@ -134,19 +124,12 @@ async function handleDelete(id) {
           </p>
         </div>
         <UBadge
-          v-if="currentSpace?.doc_id === space.doc_id"
+          v-if="currentSpace?.id === space.id"
           color="primary"
           variant="subtle"
           label="Active"
           size="xs"
         />
-        <UBadge
-          v-if="space.is_hub"
-          color="info"
-          variant="subtle"
-          label="Hub"
-          size="xs"
-        />
         <UBadge
           :color="space.visibility === 'private' ? 'neutral' : 'success'"
           variant="subtle"
@@ -155,20 +138,19 @@ async function handleDelete(id) {
         />
         <div class="flex gap-1 shrink-0">
           <UButton
-            v-if="currentSpace?.doc_id !== space.doc_id"
+            v-if="currentSpace?.id !== space.id"
             label="Switch"
             size="xs"
             color="neutral"
             variant="outline"
-            @click="switchTo(space.doc_id)"
+            @click="switchTo(space.id)"
           />
           <UButton
-            v-if="!space.is_hub"
             icon="i-lucide-trash-2"
             size="xs"
-            :color="confirmDeleteId === space.doc_id ? 'error' : 'neutral'"
+            :color="confirmDeleteId === space.id ? 'error' : 'neutral'"
             variant="ghost"
-            @click="handleDelete(space.doc_id)"
+            @click="handleDelete(space.id)"
           />
         </div>
       </div>

package/dist/runtime/components/shell/ADocPanelSettings.d.vue.ts

@@ -107,11 +107,11 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     "onFork-snapshot"?: ((version: number) => any) | undefined;
     "onLoad-more-snapshots"?: (() => any) | undefined;
 }>, {
+    snapshots: SnapshotMeta[];
     userName: string;
     docMeta: DocPageMeta | null;
-    userAvatarStyle: string;
     effectiveRole: string | null;
-    isSyncing: boolean;
+    userAvatarStyle: string;
     isOwner: boolean;
     permissions: PermissionEntry[];
     loadingPermissions: boolean;
@@ -121,10 +121,10 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     syncStatusIcon: string;
     syncStatusColor: string;
     syncStatusLabel: string;
+    isSyncing: boolean;
     lastSyncedLabel: string | null;
     syncError: string | null;
     docTypeKey: string;
-    snapshots: SnapshotMeta[];
     loadingSnapshots: boolean;
     snapshotsError: string | null;
     hasMoreSnapshots: boolean;

package/dist/runtime/components/shell/ADocPanelSettings.vue.d.ts

@@ -107,11 +107,11 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     "onFork-snapshot"?: ((version: number) => any) | undefined;
     "onLoad-more-snapshots"?: (() => any) | undefined;
 }>, {
+    snapshots: SnapshotMeta[];
     userName: string;
     docMeta: DocPageMeta | null;
-    userAvatarStyle: string;
     effectiveRole: string | null;
-    isSyncing: boolean;
+    userAvatarStyle: string;
     isOwner: boolean;
     permissions: PermissionEntry[];
     loadingPermissions: boolean;
@@ -121,10 +121,10 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     syncStatusIcon: string;
     syncStatusColor: string;
     syncStatusLabel: string;
+    isSyncing: boolean;
     lastSyncedLabel: string | null;
     syncError: string | null;
     docTypeKey: string;
-    snapshots: SnapshotMeta[];
     loadingSnapshots: boolean;
     snapshotsError: string | null;
     hasMoreSnapshots: boolean;

package/dist/runtime/components/shell/ASyncStatus.d.vue.ts

@@ -15,8 +15,8 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     onClick?: (() => any) | undefined;
 }>, {
-    syncing: boolean;
     progress: number;
+    syncing: boolean;
     collapsed: boolean;
     errorCount: number;
     pendingUploads: number;

package/dist/runtime/components/shell/ASyncStatus.vue.d.ts

@@ -15,8 +15,8 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     onClick?: (() => any) | undefined;
 }>, {
-    syncing: boolean;
     progress: number;
+    syncing: boolean;
     collapsed: boolean;
     errorCount: number;
     pendingUploads: number;

package/dist/runtime/components/shell/AUserMenu.d.vue.ts

@@ -12,13 +12,13 @@ type __VLS_Props = {
     extraItems?: DropdownMenuItem[][];
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    logout: () => any;
     "open-settings": () => any;
     "open-account": () => any;
+    logout: () => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onLogout?: (() => any) | undefined;
     "onOpen-settings"?: (() => any) | undefined;
     "onOpen-account"?: (() => any) | undefined;
+    onLogout?: (() => any) | undefined;
 }>, {
     color: string;
     collapsed: boolean;

package/dist/runtime/components/shell/AUserMenu.vue.d.ts

@@ -12,13 +12,13 @@ type __VLS_Props = {
     extraItems?: DropdownMenuItem[][];
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    logout: () => any;
     "open-settings": () => any;
     "open-account": () => any;
+    logout: () => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onLogout?: (() => any) | undefined;
     "onOpen-settings"?: (() => any) | undefined;
     "onOpen-account"?: (() => any) | undefined;
+    onLogout?: (() => any) | undefined;
 }>, {
     color: string;
     collapsed: boolean;

package/dist/runtime/components/shell/AWelcomeScreen.d.vue.ts

@@ -78,10 +78,10 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {
     currentColor: string;
     isClaimed: boolean;
     avatarStyle: string;
+    connectionError: string;
     colors: string[];
     neutrals: string[];
     currentNeutral: string;
-    connectionError: string;
     claimLoading: boolean;
     claimError: string | null;
     claimSuccess: boolean;

package/dist/runtime/components/shell/AWelcomeScreen.vue.d.ts

@@ -78,10 +78,10 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {
     currentColor: string;
     isClaimed: boolean;
     avatarStyle: string;
+    connectionError: string;
     colors: string[];
     neutrals: string[];
     currentNeutral: string;
-    connectionError: string;
     claimLoading: boolean;
     claimError: string | null;
     claimSuccess: boolean;

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

@@ -0,0 +1,29 @@
+import { type Ref } from 'vue';
+import type { MaybeRefOrGetter } from 'vue';
+/**
+ * Per-peer text-input caret ranges — the building block under the `peers`
+ * prop on `<AInput>` / `<ATextarea>`.
+ *
+ * Built on top of `useAAEphemeral`. The local element's `selectionStart`
+ * and `selectionEnd` are written into the awareness slot whenever the
+ * element gains focus or its selection changes; clear on blur. Every other
+ * peer's caret is exposed as a typed list ready to render as a coloured
+ * label inside the input.
+ *
+ * Awareness already RAF-throttles emitted updates downstream; we additionally
+ * coalesce write-side via the natural `selectionchange` cadence so a fast
+ * cursor still produces at most one frame of work per render cycle.
+ */
+export interface PeerCaret {
+    clientId: number;
+    start: number;
+    end: number;
+    user?: {
+        name?: string;
+        color?: string;
+        publicKey?: string;
+    };
+}
+export declare function useAACaret(fieldKey: MaybeRefOrGetter<string>, elementRef: Ref<HTMLInputElement | HTMLTextAreaElement | null | undefined>): {
+    carets: import("vue").ComputedRef<PeerCaret[]>;
+};

package/dist/runtime/composables/useAACaret.js

@@ -0,0 +1,64 @@
+import { computed, onScopeDispose, watch } from "vue";
+import { useAAEphemeral } from "./useAAEphemeral.js";
+export function useAACaret(fieldKey, elementRef) {
+  const { peers, setLocal } = useAAEphemeral(fieldKey);
+  let attached = null;
+  function publish() {
+    if (!attached) return;
+    const start = attached.selectionStart;
+    const end = attached.selectionEnd;
+    if (start == null || end == null) return;
+    setLocal({ start, end });
+  }
+  function clear() {
+    setLocal(null);
+  }
+  function onSelectionChange() {
+    if (!attached) return;
+    if (document.activeElement !== attached) return;
+    publish();
+  }
+  function publishSoon() {
+    queueMicrotask(publish);
+  }
+  function attach(el) {
+    if (attached === el) return;
+    detach();
+    attached = el;
+    el.addEventListener("focus", publish);
+    el.addEventListener("blur", clear);
+    el.addEventListener("keydown", publishSoon);
+    el.addEventListener("keyup", publish);
+    el.addEventListener("mouseup", publish);
+    el.addEventListener("mousedown", publishSoon);
+    el.addEventListener("input", publish);
+    document.addEventListener("selectionchange", onSelectionChange);
+  }
+  function detach() {
+    if (!attached) return;
+    attached.removeEventListener("focus", publish);
+    attached.removeEventListener("blur", clear);
+    attached.removeEventListener("keydown", publishSoon);
+    attached.removeEventListener("keyup", publish);
+    attached.removeEventListener("mouseup", publish);
+    attached.removeEventListener("mousedown", publishSoon);
+    attached.removeEventListener("input", publish);
+    document.removeEventListener("selectionchange", onSelectionChange);
+    attached = null;
+    clear();
+  }
+  watch(elementRef, (el) => {
+    if (el) attach(el);
+    else detach();
+  }, { immediate: true, flush: "post" });
+  onScopeDispose(detach);
+  const carets = computed(
+    () => peers.value.map((p) => ({
+      clientId: p.clientId,
+      start: p.value.start,
+      end: p.value.end,
+      user: p.user
+    }))
+  );
+  return { carets };
+}

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

@@ -0,0 +1,32 @@
+import type { MaybeRefOrGetter } from 'vue';
+/**
+ * Per-peer ephemeral UI state — the building block under the `peers` prop on
+ * every aware component.
+ *
+ * Each peer writes its value into a *namespaced slot* on its own awareness
+ * record (`peer:<fieldKey>`), so writes never collide across peers. Reads
+ * return every peer's current value, excluding the local user, with their
+ * `user` info already attached.
+ *
+ * Use cases:
+ *   - text input caret ranges (one per peer)
+ *   - currently-highlighted dropdown option (one per peer)
+ *   - drag delta on a slider thumb (one per peer)
+ *   - free-floating mouse cursor coords (one per peer)
+ *
+ * Awareness already RAF-throttles its `change` event in `useAwareness`, so
+ * even a 60Hz writer doesn't storm Vue render.
+ */
+export interface PeerValue<T> {
+    clientId: number;
+    value: T;
+    user?: {
+        name?: string;
+        color?: string;
+        publicKey?: string;
+    };
+}
+export declare function useAAEphemeral<T = unknown>(fieldKey: MaybeRefOrGetter<string>): {
+    peers: import("vue").ComputedRef<PeerValue<T>[]>;
+    setLocal: (value: T | null) => void;
+};

package/dist/runtime/composables/useAAEphemeral.js

@@ -0,0 +1,33 @@
+import { computed } from "vue";
+import { useAwareness } from "./useAwareness.js";
+import { useAbracadabra } from "./useAbracadabra.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 useAAEphemeral(fieldKey) {
+  const { states, setField } = useAwareness();
+  const { provider } = useAbracadabra();
+  const slot = computed(() => `peer:${resolveKey(fieldKey)}`);
+  function setLocal(value) {
+    setField(slot.value, value);
+  }
+  const peers = computed(() => {
+    const out = [];
+    const key = slot.value;
+    const localId = provider.value?.awareness?.clientID;
+    for (const [clientId, state] of states.value.entries()) {
+      if (clientId === localId) continue;
+      const v = state[key];
+      if (v === null || v === void 0) continue;
+      out.push({
+        clientId,
+        value: v,
+        user: state.user
+      });
+    }
+    return out;
+  });
+  return { peers, setLocal };
+}

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

@@ -1,4 +1,4 @@
-import type { MaybeRef } from 'vue';
+import type { MaybeRefOrGetter } from 'vue';
 import type { AwarenessPeer } from '../types.js';
 /**
  * Per-element interaction awareness.
@@ -16,11 +16,13 @@ import type { AwarenessPeer } from '../types.js';
  *
  * Field convention: "{scope}:{element-id}", e.g. "doc:toolbar:bold", "settings:save-btn"
  */
-export declare function useAAField(key: MaybeRef<string>): {
+export declare function useAAField(key: MaybeRefOrGetter<string>): {
     hoverers: import("vue").ComputedRef<AwarenessPeer[]>;
     pressers: import("vue").ComputedRef<AwarenessPeer[]>;
     focusers: import("vue").ComputedRef<AwarenessPeer[]>;
     hasRemoteActivity: import("vue").ComputedRef<boolean>;
+    localPress: import("vue").Ref<boolean, boolean>;
+    isPressed: import("vue").ComputedRef<boolean>;
     handlers: {
         mouseenter: () => void;
         mouseleave: () => void;
@@ -33,6 +35,12 @@ export declare function useAAField(key: MaybeRef<string>): {
         mouseenter: () => void;
         mouseleave: () => void;
     };
+    hoverPressHandlers: {
+        mouseenter: () => void;
+        mouseleave: () => void;
+        mousedown: () => void;
+        mouseup: () => void;
+    };
     onMouseenter: () => void;
     onMouseleave: () => void;
     onMousedown: () => void;

package/dist/runtime/composables/useAAField.js

@@ -1,10 +1,12 @@
-import { computed, isRef } from "vue";
+import { computed, isRef, onScopeDispose, ref } from "vue";
 import { useAwareness } from "./useAwareness.js";
 import { useAwarenessPeers } from "./useAwarenessPeers.js";
 export function useAAField(key) {
   const { setField } = useAwareness();
   const { peers } = useAwarenessPeers();
-  const fieldKey = computed(() => isRef(key) ? key.value : key);
+  const fieldKey = computed(
+    () => typeof key === "function" ? key() : isRef(key) ? key.value : key
+  );
   const hoverers = computed(
     () => peers.value.filter((p) => p.hover === fieldKey.value)
   );
@@ -17,6 +19,21 @@ export function useAAField(key) {
   const hasRemoteActivity = computed(
     () => hoverers.value.length > 0 || pressers.value.length > 0 || focusers.value.length > 0
   );
+  const localPress = ref(false);
+  function releaseLocalPress() {
+    if (!localPress.value) return;
+    localPress.value = false;
+  }
+  if (typeof window !== "undefined") {
+    window.addEventListener("pointerup", releaseLocalPress);
+    window.addEventListener("pointercancel", releaseLocalPress);
+    window.addEventListener("blur", releaseLocalPress);
+    onScopeDispose(() => {
+      window.removeEventListener("pointerup", releaseLocalPress);
+      window.removeEventListener("pointercancel", releaseLocalPress);
+      window.removeEventListener("blur", releaseLocalPress);
+    });
+  }
   function onMouseenter() {
     setField("hover", fieldKey.value);
   }
@@ -24,9 +41,11 @@ export function useAAField(key) {
     setField("hover", null);
   }
   function onMousedown() {
+    localPress.value = true;
     setField("press", fieldKey.value);
   }
   function onMouseup() {
+    localPress.value = false;
     setField("press", null);
   }
   function onFocus() {
@@ -35,6 +54,7 @@ export function useAAField(key) {
   function onBlur() {
     setField("focus", null);
   }
+  const isPressed = computed(() => localPress.value || pressers.value.length > 0);
   const handlers = {
     mouseenter: onMouseenter,
     mouseleave: onMouseleave,
@@ -47,13 +67,22 @@ export function useAAField(key) {
     mouseenter: onMouseenter,
     mouseleave: onMouseleave
   };
+  const hoverPressHandlers = {
+    mouseenter: onMouseenter,
+    mouseleave: onMouseleave,
+    mousedown: onMousedown,
+    mouseup: onMouseup
+  };
   return {
     hoverers,
     pressers,
     focusers,
     hasRemoteActivity,
+    localPress,
+    isPressed,
     handlers,
     hoverHandlers,
+    hoverPressHandlers,
     onMouseenter,
     onMouseleave,
     onMousedown,

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

@@ -0,0 +1,26 @@
+import { type WritableComputedRef } from 'vue';
+/**
+ * Optional collaborative value-sync layer for <AInput>, <ATextarea>, <ASelect>,
+ * and other Aware form components.
+ *
+ * Stores a single value keyed by `fieldKey` on a shared Y.Map called
+ * `aware-fields` on the root Y.Doc. All connected peers see edits in real time.
+ *
+ * Usage policy inside Aware components:
+ *   - If consumer passes their own `v-model`, that takes precedence — sync is
+ *     skipped unless `sync` is explicitly true.
+ *   - When `sync` is true (or no v-model is provided), the composable produces
+ *     a writable computed that reads/writes the Y.Map.
+ *
+ * Writes are debounced ~120ms to avoid storming the doc with every keystroke
+ * while still feeling immediate.
+ */
+export declare function useAAFieldValue<T = unknown>(fieldKey: () => string, options?: {
+    debounceMs?: number;
+    defaultValue?: T;
+}): WritableComputedRef<T | undefined>;
+/**
+ * Marker watcher: when `fieldKey` changes (rare), flush immediately
+ * to avoid writing the new value to the OLD key.
+ */
+export declare function watchFieldKey(fieldKey: () => string, onChange: (key: string, prev: string) => void): void;

package/dist/runtime/composables/useAAFieldValue.js

@@ -0,0 +1,32 @@
+import { computed, watch } from "vue";
+import { useAbracadabra } from "./useAbracadabra.js";
+import { useSyncedMap } from "./useYDoc.js";
+export function useAAFieldValue(fieldKey, options = {}) {
+  const { doc } = useAbracadabra();
+  const { data, set } = useSyncedMap(doc, "aware-fields");
+  const debounceMs = options.debounceMs ?? 120;
+  let timer = null;
+  let pending;
+  const flush = () => {
+    timer = null;
+    if (pending !== void 0) {
+      set(fieldKey(), pending);
+    } else {
+      set(fieldKey(), "");
+    }
+  };
+  return computed({
+    get() {
+      const v = data[fieldKey()];
+      return v === void 0 ? options.defaultValue : v;
+    },
+    set(value) {
+      pending = value;
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(flush, debounceMs);
+    }
+  });
+}
+export function watchFieldKey(fieldKey, onChange) {
+  watch(() => fieldKey(), (k, prev) => onChange(k, prev));
+}