@yottagraph-app/aether-instructions 1.1.36 → 1.1.38

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.36",
+    "version": "1.1.38",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/cookbook-data.mdc

@@ -403,3 +403,148 @@ relationship PID. See the `data` rule for the two-layer architecture.
     }
 </script>
 ```
+
+## 5. Async Entity Search with Live Suggestions
+
+Type-ahead search that shows results in a dropdown as the user types. Uses
+`searchEntities()` from the gateway helpers with a debounced watcher.
+
+> **Do not use `v-autocomplete` for async search.** Vuetify's `v-autocomplete`
+> with `hide-no-data` + `no-filter` + async item loading has a timing bug:
+> the menu hides while items are empty (during the fetch) and does not reopen
+> when results arrive. Use `v-text-field` with a manual dropdown instead.
+
+```vue
+<template>
+    <div class="entity-search" style="position: relative">
+        <v-text-field
+            v-model="searchQuery"
+            :label="label"
+            :prepend-inner-icon="icon"
+            variant="solo-filled"
+            rounded="lg"
+            clearable
+            density="comfortable"
+            :loading="searching"
+            @focus="showMenu = suggestions.length > 0"
+            @click:clear="onClear"
+        />
+
+        <v-card
+            v-if="showMenu && suggestions.length > 0"
+            class="search-dropdown"
+            elevation="8"
+        >
+            <v-list density="compact">
+                <v-list-item
+                    v-for="item in suggestions"
+                    :key="item.neid"
+                    :title="item.name"
+                    :subtitle="item.neid"
+                    @click="onSelect(item)"
+                />
+            </v-list>
+        </v-card>
+    </div>
+</template>
+
+<script setup lang="ts">
+    import { searchEntities } from '~/utils/elementalHelpers';
+
+    const props = withDefaults(
+        defineProps<{
+            label?: string;
+            icon?: string;
+            flavors?: string[];
+        }>(),
+        { label: 'Search', icon: 'mdi-magnify', flavors: undefined },
+    );
+
+    const emit = defineEmits<{
+        selected: [entity: { neid: string; name: string }];
+    }>();
+
+    const searchQuery = ref('');
+    const suggestions = ref<{ neid: string; name: string }[]>([]);
+    const searching = ref(false);
+    const showMenu = ref(false);
+    let selectedName = '';
+    let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+    watch(searchQuery, (val) => {
+        if (debounceTimer) clearTimeout(debounceTimer);
+        if (val === selectedName) return;
+        if (!val || val.length < 2) {
+            suggestions.value = [];
+            showMenu.value = false;
+            return;
+        }
+        debounceTimer = setTimeout(() => doSearch(val), 300);
+    });
+
+    async function doSearch(query: string) {
+        searching.value = true;
+        try {
+            suggestions.value = await searchEntities(query, {
+                maxResults: 8,
+                flavors: props.flavors,
+            });
+            showMenu.value = suggestions.value.length > 0;
+        } catch {
+            suggestions.value = [];
+            showMenu.value = false;
+        } finally {
+            searching.value = false;
+        }
+    }
+
+    function onSelect(item: { neid: string; name: string }) {
+        selectedName = item.name;
+        searchQuery.value = item.name;
+        suggestions.value = [];
+        showMenu.value = false;
+        emit('selected', item);
+    }
+
+    function onClear() {
+        selectedName = '';
+        suggestions.value = [];
+        showMenu.value = false;
+    }
+
+    onMounted(() => {
+        document.addEventListener('click', (e) => {
+            const el = (e.target as HTMLElement)?.closest('.entity-search');
+            if (!el) showMenu.value = false;
+        });
+    });
+</script>
+
+<style scoped>
+    .entity-search {
+        max-width: 600px;
+    }
+
+    .search-dropdown {
+        position: absolute;
+        top: 100%;
+        left: 0;
+        right: 0;
+        z-index: 100;
+        max-height: 300px;
+        overflow-y: auto;
+        margin-top: -8px;
+    }
+</style>
+```
+
+Usage:
+
+```vue
+<EntitySearch
+    label="Search for a company"
+    icon="mdi-domain"
+    :flavors="['organization']"
+    @selected="onCompanySelected"
+/>
+```

package/rules/data.mdc

@@ -142,8 +142,8 @@ Elemental API patterns. **Use these instead of writing from scratch:**
 ```typescript
 const { flavors, properties, flavorByName, pidByName, refresh } = useElementalSchema();
 await refresh();                                // fetches once, then cached
-const articleFid = flavorByName('article');      // → number | null
-const namePid = pidByName('name');              // → typically 8
+const articleFid = flavorByName('article');      // → string | null
+const namePid = pidByName('name');              // → string | null
 ```
 
 Handles the dual response shapes (`res.schema.flavors` vs `res.flavors`)
@@ -297,15 +297,31 @@ Same value, different key. Always use a fallback:
 
 ```typescript
 const articleFlavor = flavors.find(f => f.name === 'article');
-const articleFid = articleFlavor?.fid ?? articleFlavor?.findex ?? null;
+// Always use String() — safe for small IDs (12) and required for large ones
+const articleFid = String(articleFlavor?.fid ?? articleFlavor?.findex ?? '');
 
 // When building a FID lookup map:
-const fidMap = new Map(flavors.map(f => [f.fid ?? f.findex, f.name]));
+const fidMap = new Map(flavors.map(f => [String(f.fid ?? f.findex), f.name]));
 ```
 
 The `is_type` expression in `/elemental/find` always uses the `fid` key
 regardless of which schema endpoint provided the value.
 
+### Some FIDs and PIDs are 64-bit -- `JSON.parse` will silently corrupt them
+
+FIDs and PIDs are stored as 64-bit signed integers. Many are small
+(e.g. `12`), but others exceed JavaScript's `Number.MAX_SAFE_INTEGER`
+(2^53 - 1) -- for example, `3466547124233281063`. `JSON.parse` silently
+rounds these large values (that example becomes `3466547124233281000`). An `is_type` query with
+the rounded FID returns empty results and no error, making it look like
+the data doesn't exist.
+
+**Always treat FIDs and PIDs as strings in TypeScript/JavaScript.**
+Before `JSON.parse`, rewrite large numeric `fid`/`pid` fields to
+quoted strings. Store them as `string`, not `number`. Build expressions
+and `pids` arrays via string interpolation, not `JSON.stringify` of a
+JS number. This is safe for small IDs too.
+
 ### Relationship property values need zero-padding to form valid NEIDs
 
 Relationship properties (`data_nindex`) return linked entity IDs as raw