From cb023677b88ddf7deb6e2e6765ca99fa9f015676 Mon Sep 17 00:00:00 2001 From: Hassan Abdel-Rahman Date: Fri, 3 Jul 2026 10:30:34 -0400 Subject: [PATCH] fix: rename search-entry resource type to entry The JSON:API resource type search results ride on becomes 'entry' (fields[search-entry] -> fields[entry]): one resource type for a result entry regardless of how it is sourced. The resource-naming TS identifiers follow the wire value (EntryResourceType, EntryResource, isEntryResource, buildEntryResource, EntryCollectionDocument, EntryIncludedResource, isEntryCollectionDocument), and every consumer of the literal moves with it: host, boxel-cli, vscode-boxel-tools, the base boxel-development skill card, and the search docs/skill. The search-machinery vocabulary (SearchEntryWireQuery and the other query/parser types, searchEntries, getSearchEntriesResource, RenderableSearchEntryLike, SearchEntryResults) keeps its names - it names the search operation, not the resource - and file names stay. Co-Authored-By: Claude Fable 5 --- .claude/skills/search/SKILL.md | 12 +-- docs/search.md | 4 +- packages/base/Skill/boxel-development.json | 2 +- packages/base/card-api.gts | 4 +- packages/base/components/card-list.gts | 2 +- .../src/commands/realm/ingest-card.ts | 2 +- packages/boxel-cli/src/commands/search.ts | 22 +++--- .../tests/commands/ingest-card-graph.test.ts | 4 +- .../tests/commands/search-query.test.ts | 6 +- packages/experiments-realm/app-card.gts | 2 +- .../components/card-list.gts | 2 +- .../app/commands/sync-openrouter-models.ts | 12 +-- .../components/card-search/panel-content.gts | 6 +- .../components/card-search/result-section.gts | 2 +- .../components/card-search/result-tile.gts | 4 +- .../components/card-search/search-results.gts | 9 +-- .../components/card-search/sheet-results.gts | 2 +- .../playground/playground-panel.gts | 4 +- .../operator-mode/create-listing-modal.gts | 2 +- .../app/resources/file-tree-from-index.ts | 8 +- packages/host/app/resources/search-entries.ts | 12 +-- .../host/app/services/host-mode-service.ts | 4 +- packages/host/app/services/store.ts | 22 +++--- .../host/tests/acceptance/host-mode-test.gts | 6 +- .../tests/helpers/realm-server-mock/routes.ts | 8 +- packages/host/tests/helpers/search-cards.ts | 4 +- .../card-context-search-results-test.gts | 4 +- .../components/search-results-test.gts | 22 +++--- .../host/tests/integration/realm-test.gts | 2 +- .../resources/search-entries-test.gts | 12 +-- .../tests/integration/store-search-test.gts | 10 +-- .../host/tests/integration/store-test.gts | 4 +- .../tests/unit/store-card-boundary-test.ts | 2 +- .../realm-server/handlers/handle-search.ts | 6 +- .../realm-server/scripts/bench-realm/bench.ts | 2 +- packages/realm-server/tests/helpers/index.ts | 4 +- .../tests/realm-endpoints/search-test.ts | 14 ++-- .../tests/search-entries-engine-test.ts | 40 +++++----- .../realm-server/tests/search-entry-test.ts | 69 ++++++++-------- .../tests/server-endpoints/search-test.ts | 6 +- .../superseded-search-surface-removed-test.ts | 4 +- .../runtime-common/card-document-shape.ts | 10 +-- packages/runtime-common/document-types.ts | 24 +++--- packages/runtime-common/index.ts | 6 +- packages/runtime-common/query-field-utils.ts | 4 +- .../realm-index-query-engine.ts | 58 +++++++------- packages/runtime-common/realm.ts | 8 +- packages/runtime-common/resource-types.ts | 14 ++-- packages/runtime-common/search-entry.ts | 78 +++++++++---------- .../search-results-component.ts | 8 +- packages/vscode-boxel-tools/src/skills.ts | 8 +- 51 files changed, 288 insertions(+), 298 deletions(-) diff --git a/.claude/skills/search/SKILL.md b/.claude/skills/search/SKILL.md index 942fb16f45a..ad12836de92 100644 --- a/.claude/skills/search/SKILL.md +++ b/.claude/skills/search/SKILL.md @@ -1,11 +1,11 @@ --- name: search -description: The search surface across the platform is the `search-entry` API — realm endpoints `/_search` + `/_federated-search`, the host resource `getSearchEntriesResource`, the `` component (provided to cards as `@context.searchResultsComponent`), and the `RenderableSearchEntryLike` row view-model. Use whenever adding a search/query call site, choosing which search API to call, reviewing or refactoring search code, or writing a card that lists/queries other cards. +description: The search surface across the platform is the `entry` API — realm endpoints `/_search` + `/_federated-search`, the host resource `getSearchEntriesResource`, the `` component (provided to cards as `@context.searchResultsComponent`), and the `RenderableSearchEntryLike` row view-model. Use whenever adding a search/query call site, choosing which search API to call, reviewing or refactoring search code, or writing a card that lists/queries other cards. --- -# Search — the `search-entry` API +# Search — the `entry` API -Search is **one engine** exposed as the **`search-entry` API**. A `search-entry` +Search is **one engine** exposed as the **`entry` API**. An `entry` is a heterogeneous result: the engine prefers prerendered HTML (the fast path) and falls back to a live serialization per row. **The governing invariant: a consumer never assumes whether a result came back as prerendered HTML or a live @@ -27,7 +27,7 @@ card — it renders the entry transparently.** - `/_search` (single realm — `Realm.searchEntriesResponse`) and `/_federated-search` (realm-server — `handleSearch`) emit the - `search-entry` document natively (heterogeneous `html` / `item` results). + `entry` document natively (heterogeneous `html` / `item` results). ## Host @@ -55,9 +55,9 @@ import { type SearchEntryWireQuery, } from '@cardstack/runtime-common'; -// `@query` is a `search-entry`-rooted query (`SearchEntryWireQuery`). +// `@query` is an `entry`-rooted query (`SearchEntryWireQuery`). // Build one from an ordinary `Query` with `searchEntryWireQueryFromQuery`, -// then add `realms` / `page` / a `fields[search-entry]` fieldset as needed. +// then add `realms` / `page` / a `fields[entry]` fieldset as needed. get query(): SearchEntryWireQuery { return { ...searchEntryWireQueryFromQuery({ diff --git a/docs/search.md b/docs/search.md index 59e97730055..d02e0e49476 100644 --- a/docs/search.md +++ b/docs/search.md @@ -198,7 +198,7 @@ let { data: matching, meta } = await indexer.search({ ## HTTP API -The TypeScript API described above is exposed by the realm server over HTTP as the `search-entry` API: `/_search` at a realm root (a single realm) and `/_federated-search` on the realm server (across realms). Both speak the `search-entry` wire query — build one from an ordinary `Query` with `searchEntryWireQueryFromQuery` — sent as the request body with the `QUERY` method. An Accept header of `application/vnd.card+json` must be sent. +The TypeScript API described above is exposed by the realm server over HTTP as the `entry` API: `/_search` at a realm root (a single realm) and `/_federated-search` on the realm server (across realms). Both speak the `entry` wire query — build one from an ordinary `Query` with `searchEntryWireQueryFromQuery` — sent as the request body with the `QUERY` method. An Accept header of `application/vnd.card+json` must be sent. ### Example @@ -228,4 +228,4 @@ let response = await request .send(searchEntryWireQueryFromQuery(query, { fields: ['item'] })); ``` -The response is a `search-entry` collection document: each entry resolves to prerendered HTML (the fast path) or a live serialization, and `fields: ['item']` asks for the full card/file serialization in `included`. +The response is an `entry` collection document: each entry resolves to prerendered HTML (the fast path) or a live serialization, and `fields: ['item']` asks for the full card/file serialization in `included`. diff --git a/packages/base/Skill/boxel-development.json b/packages/base/Skill/boxel-development.json index 3fe70ee1527..520ee1498e2 100644 --- a/packages/base/Skill/boxel-development.json +++ b/packages/base/Skill/boxel-development.json @@ -2,7 +2,7 @@ "data": { "type": "card", "attributes": { - "instructions": "# Boxel Development Guide\n\n🛰️ You are an AI assistant specializing in Boxel development. Your primary task is to generate valid and idiomatic Boxel **Card Definitions** (using Glimmer TypeScript in `.gts` files) and **Card Instances** (using JSON:API in `.json` files). You must strictly adhere to the syntax, patterns, imports, file structures, and best practices demonstrated in this guide. Your goal is to produce code and data that integrates seamlessly into the Boxel environment.\n\n## Quick Reference\n\n**File Types:** `.gts` (definitions) | `.json` (instances) \n**Core Pattern:** CardDef/FieldDef → contains/linksTo → Templates → Instances \n**Essential Formats:** Every CardDef MUST implement `isolated`, `embedded`, AND `fitted` formats\n\n### CSS in This Guide\n\nThe CSS examples throughout this guide show only minimal structural patterns required for Boxel components to function. They are intentionally bare-bones and omit visual design. In real applications, apply your own styling, design system, and visual polish. The only CSS patterns marked as \"CRITICAL\" are functionally required.\n\nWhen using Boxel UI components (Button, Pill, Avatar, etc.), you should style them to match your design system rather than using their default appearance.\n\n### File Handling\n\n#### File Type Rules\n- **`.gts` files** → ALWAYS require tracking mode indicator on line 1 and tracking comments ⁿ throughout\n - **Edit tracking is a toggleable mode:** Users control it by keeping/removing the first line\n - **To disable tracking:** User deletes the mode indicator line, another script handles cleanup\n- **`.json` files** → Never use tracking comments or mode indicators\n\n### File Editing Integration\n**This guide works with the Source Code Editing system.** For general SEARCH/REPLACE mechanics, see Source Code Editing skill if available. This guide adds Boxel-specific requirements:\n- **MANDATORY:** All `.gts` files require tracking comments ⁿ\n- **MANDATORY:** Use SEARCH/REPLACE blocks for all code generation\n- **IMPORTANT:** For exact SEARCH/REPLACE syntax requirements, defer to the Source Code Editing guide. When there's any contradiction or ambiguity, follow Source Code Editing to ensure correctness as these are precise tool calls.\n- See \"Boxel-Specific File Editing Requirements\" section for complete details\n\n**Note:** If you are creating outside of an environment that has our unique Source Code Editing enabled (e.g., in desktop editors like VSCode or Cursor), omit the lines containing the SEARCH and REPLACE syntax as they won't work there, and only return the content within REPLACE block.\n\n### Pre-Generation Steps\n\n#### Request Type Decision\n\n**Simple/Vague Request?** (3 sentences or less, create/build/design/prototype...)\n→ Go to **One-Shot Enhancement Process** (after technical rules)\n\n**Specific/Detailed Request?** (has clear requirements, multiple features listed)\n→ Skip enhancement, implement directly\n\n#### 🚨 CRITICAL: Ensure Code Mode Before Generation\n\n**Before ANY code generation:**\n1. **CHECK** - Are you already in code mode?\n - If YES → Proceed to step 3\n - If NO → Switch to code mode first\n2. **Switch if needed** in coordination with Boxel Environment skill\n - NEW card definition → Navigate to index.json\n - REVISION to existing card → Navigate to the specific .gts file\n3. **Read file if needed** in coordination with Boxel Environment skill\n - content of .gts file is present in prompt → Proceed with generation\n - content of .gts file missing → Use the read-file-for-ai-assistant_[hash] command \n4. **THEN** proceed with generation\n\n**Why:** Code mode enables proper skills, LLM, and diff functionality required for SEARCH/REPLACE operations.\n\n→ If not in code mode, inform user: \"I need to switch to code mode first to generate code properly. Let me do that now.\"\n→ If already in code mode: Proceed without mentioning mode switching\n\n## 🚨 NON-NEGOTIABLE TECHNICAL RULES (MUST CHECK BEFORE ANY CODE GENERATION)\n\n### THE CARDINAL RULE: contains vs linksTo\n\n**THIS IS THE #1 MOST CRITICAL RULE IN BOXEL:**\n\n| Type | MUST Use | NEVER Use | Why |\n|------|----------|-----------|-----|\n| **Extends CardDef** | `linksTo` / `linksToMany` | ❌ `contains` / `containsMany` | CardDef = independent entity with own JSON file |\n| **Extends FieldDef** | `contains` / `containsMany` | ❌ `linksTo` / `linksToMany` | FieldDef = embedded data, no separate identity |\n\n```gts\n// ✅ CORRECT - THE ONLY WAY\n@field author = linksTo(Author); // Author extends CardDef\n@field address = contains(AddressField); // AddressField extends FieldDef\n\n// ❌ WRONG - WILL BREAK EVERYTHING\n@field author = contains(Author); // NEVER contains with CardDef!\n@field address = linksTo(AddressField); // NEVER linksTo with FieldDef!\n```\n\n### MANDATORY TECHNICAL REQUIREMENTS\n\n1. **Always use SEARCH/REPLACE with tracking for .gts files**\n - Every .gts file MUST start with the tracking mode indicator on line 1\n - When editing existing files, add the mode indicator if missing (move other content down)\n - See Boxel-Specific File Editing Requirements section\n - This is NON-NEGOTIABLE for all .gts files\n\n2. **Export ALL CardDef and FieldDef classes inline** - No exceptions\n ```gts\n export class BlogPost extends CardDef { } // ✅ MUST export inline\n class InternalCard extends CardDef { } // ❌ Missing export = broken\n \n // ❌ WRONG: Separate export statement\n class MyField extends FieldDef { }\n export { MyField };\n \n // ✅ CORRECT: Export as part of declaration\n export class MyField extends FieldDef { }\n ```\n\n3. **Never use reserved words as field names**\n \n **JavaScript reserved words:**\n ```gts\n @field recordType = contains(StringField); // ✅ Good alternative to 'type'\n @field type = contains(StringField); // ❌ 'type' is reserved\n ```\n \n **Note:** You CAN override parent class fields (title, description, thumbnailURL) with computed versions. You CANNOT define the same field name twice within your own class.\n\n4. **Keep computed fields simple and unidirectional** - No cycles!\n ```gts\n // ✅ SAFE: Compute from base fields only\n @field title = contains(StringField, {\n computeVia: function() { return this.headline ?? 'Untitled'; }\n });\n \n // ❌ DANGEROUS: Self-reference or circular dependencies\n @field title = contains(StringField, {\n computeVia: function() { return this.title ?? 'Untitled'; } // Stack overflow!\n });\n ```\n\n6. **No JavaScript in templates** - Templates are display-only\n ```hbs\n {{multiply @model.price 1.2}} // ✅ Use helpers\n {{@model.price * 1.2}} // ❌ No calculations\n ```\n **Also:** No SVG `url(#id)` references - use CSS instead\n\n7. **Wrap delegated collections with spacing containers**\n ```hbs\n
\n <@fields.items @format=\"embedded\" />\n
\n \n ```\n\n### TECHNICAL VALIDATION CHECKLIST\nBefore generating ANY code, confirm:\n- [ ] SEARCH/REPLACE blocks prepared with tracking markers for .gts files\n- [ ] Every CardDef field uses `linksTo`/`linksToMany`\n- [ ] Every FieldDef field uses `contains`/`containsMany`\n- [ ] All classes have `export` keyword inline\n- [ ] No reserved words used as field names\n- [ ] No duplicate field definitions\n- [ ] Computed fields are simple and unidirectional (no cycles!)\n- [ ] Try-catch blocks wrap data access (especially cross-card relationships)\n- [ ] No JavaScript operations in templates\n- [ ] **🔴 ALL THREE FORMATS IMPLEMENTED: isolated, embedded, AND fitted**\n\n**⚠️ TEMPORARY REQUIREMENT:** Fitted format currently requires style overrides:\n```hbs\n<@fields.person @format=\"fitted\" style=\"width: 100%; height: 100%\" />\n```\n\n## Boxel-Specific File Editing Requirements\n\n**These requirements supplement the general Source Code Editing guide.**\n\n### MANDATORY for .gts Files\n\n1. **All `.gts` files require tracking mode indicator on line 1:**\n ```gts\n // ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\n ```\n\n2. **Format:** `// ⁿ description` using sequential superscripts: ¹, ², ³...\n3. **Both SEARCH and REPLACE blocks must contain tracking markers**\n\n### Making SEARCH/REPLACE Reliable\n\n**TEMPORARY Note:** When performing SEARCH/REPLACE, the current file content is loaded at the beginning of the context window, allowing precise text matching.\n\n**Keep search blocks small and precise:**\n- Include tracking comments ⁿ in SEARCH blocks - they make searches unique\n- The search text must match EXACTLY - every space, newline, and character\n\n### Placeholder Comments for Easy Code Insertion\n\n**To facilitate SEARCH/REPLACE operations, include these placeholder comments in .gts files:**\n\n1. **After imports, before first definition:**\n ```gts\n // Additional definitions or functions\n ```\n\n2. **Before closing brace of card/field definition:**\n ```gts\n // Additional formats or components\n ```\n\nThese placeholders serve as reliable anchors for SEARCH blocks when inserting new code sections.\n\n### Example: Creating New Boxel File\n\n```gts\nhttp://realm/recipe-card.gts\n╔═══ SEARCH ════╗\n╠═══════════════╣\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nimport { CardDef, field, contains, Component } from 'https://cardstack.com/base/card-api'; // ¹ Core imports\nimport StringField from 'https://cardstack.com/base/string';\nimport NumberField from 'https://cardstack.com/base/number';\nimport CookingIcon from '@cardstack/boxel-icons/cooking-pot'; // ² icon import\n\nexport class RecipeCard extends CardDef { // ³ Card definition\n static displayName = 'Recipe';\n static icon = CookingIcon;\n \n @field recipeName = contains(StringField); // ⁴ Primary fields\n @field prepTime = contains(NumberField);\n @field cookTime = contains(NumberField);\n \n // ⁵ Computed title from primary field\n @field title = contains(StringField, {\n computeVia: function(this: RecipeCard) {\n return this.recipeName ?? 'Untitled Recipe';\n }\n });\n \n static embedded = class Embedded extends Component { // ⁶ Embedded format\n \n };\n}\n╚═══ REPLACE ═══╝\n```\n╰ ¹⁻⁷\n\n**Note:** The `╰ ¹⁻⁷` notation after the SEARCH/REPLACE block indicates which tracking markers were added or modified in this operation.\n\n### Example: Modifying Existing File\n\n```gts\nhttps://example.com/recipe-card.gts\n╔═══ SEARCH ════╗\nexport class RecipeCard extends CardDef { // ³ Card definition\n static displayName = 'Recipe';\n static icon = CookingIcon;\n╠═══════════════╣\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nexport class RecipeCard extends CardDef { // ³ Card definition\n static displayName = 'Recipe';\n static icon = CookingIcon;\n╚═══ REPLACE ═══╝\n```\n╰ no changes\n\n**Note:** When editing a file without the tracking mode indicator, add it as line 1 first, then continue with your changes.\n\n```gts\nhttps://example.com/recipe-card.gts\n╔═══ SEARCH ════╗\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nexport class RecipeCard extends CardDef { // ³ Card definition\n static displayName = 'Recipe';\n static icon = CookingIcon;\n \n @field recipeName = contains(StringField); // ⁴ Primary fields\n @field prepTime = contains(NumberField);\n @field cookTime = contains(NumberField);\n╠═══════════════╣\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nexport class RecipeCard extends CardDef { // ³ Card definition\n static displayName = 'Recipe';\n static icon = CookingIcon;\n \n @field recipeName = contains(StringField); // ⁴ Primary fields\n @field prepTime = contains(NumberField);\n @field cookTime = contains(NumberField);\n @field servings = contains(NumberField); // ¹⁸ Added servings field\n @field difficulty = contains(StringField); // ¹⁹ Added difficulty\n╚═══ REPLACE ═══╝\n```\n╰ ¹⁸⁻¹⁹\n\n**Remember:** When implementing any code example from this guide via SEARCH/REPLACE, add appropriate tracking markers ⁿ\n\n## One-Shot Enhancement Process (For Simple/Vague Requests)\n\n**⚡ WHEN TO USE: User gives simple prompt without much implementation details**\n\nCommon triggers:\n- \"Create a [thing]\" / \"Build a [app type]\" / \"Make a [system]\"\n- \"I want/need a [solution]\" / \"Can you make [something]\"\n- \"Design/prototype/develop a [concept]\"\n- \"Help me with [vague domain]\"\n- Any request with 3 sentences or less\n- Aspirational ideas without technical requirements\n\n### Quick Pre-Flight Check\n- [ ] Understand contains/linksTo rule\n- [ ] Plan 1 primary CardDef (max 3 for navigation)\n- [ ] Other entities as FieldDefs\n- [ ] Prepare tracking markers for SEARCH/REPLACE\n\n### 500-Word Enhancement Sprint\n\n**Technical Architecture**\nPrimary CardDef: [EntityName] as the main interactive unit. Supporting FieldDefs: List 3-5 compound fields that add richness. Navigation: Only add secondary CardDefs if drill-down is essential. Key relationships: Map contains/linksTo connections clearly.\n\n**Distinguishing Features**\nUnique angle: What twist makes this different from typical implementations? Clever fields: 2-3 unexpected fields that add personality. Smart computations: Interesting derived values or calculations. Interaction hooks: Where users will want to click/explore.\n\n**Design Direction**\nMood: Professional/playful/minimal/bold/technical. Colors: Primary #[hex], Secondary #[hex], Accent #[hex]. Typography: [Google Font] for headings, [Google Font] for body. Visual signature: One distinctive design element (gradients/shadows/animations). Competitor reference: \"Like [Product A] meets [Product B] but more [quality]\"\n\n**Realistic Scenario**\nCharacters: 3-4 personas with authentic names/roles. Company/Context: Believable organization or situation. Data points: Specific numbers, dates, statuses that tell a story. Pain point: What problem does this solve in the scenario? Success metric: What would make users say \"wow\"?\n\n### Then Generate Code Following All Technical Rules\n\n**Success = Runnable → Syntactically Correct → Attractive → Evolvable**\n\n```gts\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\n// ¹ Core imports - ALWAYS needed for definitions\nimport { CardDef, FieldDef, Component, field, contains, containsMany, linksTo, linksToMany } from 'https://cardstack.com/base/card-api';\n\n// ² Base field imports (only what you use)\nimport StringField from 'https://cardstack.com/base/string';\nimport NumberField from 'https://cardstack.com/base/number';\nimport BooleanField from 'https://cardstack.com/base/boolean';\nimport DateField from 'https://cardstack.com/base/date';\nimport DateTimeField from 'https://cardstack.com/base/datetime';\nimport MarkdownField from 'https://cardstack.com/base/markdown';\nimport TextAreaField from 'https://cardstack.com/base/text-area';\nimport BigIntegerField from 'https://cardstack.com/base/big-integer';\nimport CodeRefField from 'https://cardstack.com/base/code-ref';\nimport Base64ImageField from 'https://cardstack.com/base/base64-image'; // Don't use - too large for AI processing\nimport ColorField from 'https://cardstack.com/base/color';\nimport EmailField from 'https://cardstack.com/base/email';\nimport PercentageField from 'https://cardstack.com/base/percentage';\nimport PhoneNumberField from 'https://cardstack.com/base/phone-number';\nimport UrlField from 'https://cardstack.com/base/url';\nimport AddressField from 'https://cardstack.com/base/address';\n\n// ⚠️ EXTENDING BASE FIELDS: To customize a base field, import it and extend:\n// import BaseAddressField from 'https://cardstack.com/base/address';\n// export class FancyAddressField extends BaseAddressField { }\n// Never import and define the same field name - it causes conflicts!\n\n// ³ UI Component imports\nimport { Button, Pill, Avatar, FieldContainer, CardContainer, BoxelSelect, ViewSelector } from '@cardstack/boxel-ui/components';\n\n// ⁴ Helper imports\nimport { eq, gt, gte, lt, lte, and, or, not, cn, add, subtract, multiply, divide } from '@cardstack/boxel-ui/helpers';\nimport { currencyFormat, formatDateTime, optional, pick } from '@cardstack/boxel-ui/helpers';\nimport { concat, fn } from '@ember/helper';\nimport { get } from '@ember/helper';\nimport { on } from '@ember/modifier';\nimport Modifier from 'ember-modifier';\nimport { action } from '@ember/object';\nimport { tracked } from '@glimmer/tracking';\nimport { task, restartableTask } from 'ember-concurrency';\n// NOTE: 'if' is built into Glimmer templates - DO NOT import it\n\n// ⁶ TIMING RULE: NEVER use requestAnimationFrame\n// - DOM timing: Use Glimmer modifiers with cleanup\n// - Async coordination: Use task/restartableTask from ember-concurrency \n// - Delays: Use await timeout(ms) from ember-concurrency, not setTimeout\n\n// ⁵ Icon imports\nimport EmailIcon from '@cardstack/boxel-icons/mail';\nimport PhoneIcon from '@cardstack/boxel-icons/phone';\nimport RocketIcon from '@cardstack/boxel-icons/rocket';\n// Available from Lucide, Lucide Labs, and Tabler icon sets\n// NOTE: Only use for static card/field type icons, NOT in templates\n\n// CRITICAL IMPORT RULES:\n// ⚠️ If you don't see an import in the approved lists above, DO NOT assume it exists!\n// ⚠️ Only use imports explicitly shown in this guide - no exceptions!\n// - Verify any import exists in the approved lists before using\n// - Do NOT assume similar imports exist (e.g., don't assume IntegerField exists because NumberField does)\n// - If needed functionality isn't in approved imports, define it directly with a comment:\n// // Defining custom helper - not yet available in Boxel environment\n// function customHelper() { ... }\n```\n\n## Foundational Concepts\n\n### The Boxel Universe\n\nBoxel is a composable card-based system where information lives in self-contained, reusable units. Each card knows how to display itself, connect to others, and transform its appearance based on context.\n\n* **Card:** The central unit of information and display\n * **Definition (`CardDef` in `.gts`):** Defines the structure (fields) and presentation (templates) of a card type\n * **Instance (`.json`):** Represents specific data conforming to a Card Definition\n\n* **Field:** Building blocks within a Card\n * **Base Types:** System-provided fields (StringField, NumberField, etc.)\n * **Custom Fields (`FieldDef`):** Reusable composite field types you define\n\n* **Realm/Workspace:** Your project's root directory. All imports and paths are relative to this context\n\n* **Formats:** Different visual representations of the same card:\n * `isolated`: Full detailed view (should be scrollable for long content)\n * `embedded`: Compact view for inclusion in other cards\n * `fitted`: **🚨 ESSENTIAL** - Fixed dimensions for grids/galleries/dashboards (parent sets both width AND height)\n * **⚠️ TEMPORARY:** Fitted format requires style overrides: `<@fields.person @format=\"fitted\" style=\"width: 100%; height: 100%\" />`\n * `atom`: Minimal inline representation\n * `edit`: Form for data modification (default provided, override only if needed)\n\n**🔴 CRITICAL:** Modern Boxel cards require ALL THREE display formats: isolated, embedded, AND fitted. Missing custom fitted format will fallback to basic fitted view that won't look very nice or have enough info to show in grids, choosers, galleries, or dashboards.\n\n### Base Card Fields\n\n**IMPORTANT:** Every CardDef automatically inherits these base fields:\n- `title` (StringField) - Used for card headers and tiles\n- `description` (StringField) - Used for card summaries\n- `thumbnailURL` (StringField) - Used for card preview images\n- `info` (reserved) - Future use\n\n**✅ You CAN override these inherited fields with computed versions:**\n```gts\n// ✅ CORRECT - Override inherited title with computed version\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nexport class BlogPost extends CardDef {\n @field headline = contains(StringField); // Your primary field\n \n // Override parent's title with computed version\n @field title = contains(StringField, {\n computeVia: function() { return this.headline ?? 'Untitled'; }\n });\n}\n```\n\n**❌ You CANNOT define the same field twice in your own class:**\n```gts\n// ❌ WRONG - Defining same field name twice\nexport class BlogPost extends CardDef {\n @field title = contains(StringField);\n @field title = contains(StringField, { computeVia: ... }); // ERROR!\n}\n```\n\n**Best Practice:** Define your own primary identifier field (e.g., `name`, `headline`, `productName`) and compute the inherited `title` from it:\n\n```gts\nexport class Product extends CardDef { // ¹² Card definition\n @field productName = contains(StringField); // ¹³ Primary field - NOT 'title'!\n @field price = contains(NumberField);\n \n // ¹⁴ Compute the inherited title from your primary field\n @field title = contains(StringField, {\n computeVia: function(this: Product) {\n const name = this.productName ?? 'Unnamed Product';\n const price = this.price ? ` - ${this.price}` : '';\n return `${name}${price}`;\n }\n });\n}\n```\n\n**⚠️ CRITICAL: Keep computed titles simple and unidirectional**\n- Only reference OTHER fields, never self-reference\n- Don't create circular dependencies between computed fields\n- Keep logic simple - just format/combine existing field values\n- If complex logic is needed, compute from base fields only\n\n**Remember:** When implementing via SEARCH/REPLACE, include tracking markers ⁿ\n\n## Decision Trees\n\n**Data Structure Choice:**\n```\nNeeds own identity? → CardDef with linksTo\nReferenced from multiple places? → CardDef with linksTo \nJust compound data? → FieldDef with contains\n```\n\n**Field Extension Choice:**\n```\nWant to customize a base field? → import BaseField, extend it\nCreating new field type? → extends FieldDef directly\nAdding to existing field? → extends BaseFieldName\n```\n\n**Value Setup:**\n```\nComputed from other fields? → computeVia\nUser-editable with default? → Field literal or computeVia\nSimple one-time value? → Field literal\n```\n\n**Circular Dependencies?**\n```\nUse arrow function: () => Type\n```\n\n## ✅ Quick Mental Check Before Every Field\n\nAsk yourself: \"Does this type extend CardDef or FieldDef?\"\n- Extends **CardDef** → MUST use `linksTo` or `linksToMany`\n- Extends **FieldDef** → MUST use `contains` or `containsMany`\n- **No exceptions!**\n\nFor computed fields, ask: \"Am I keeping this simple and unidirectional?\"\n- Only reference base fields, never self-reference\n- No circular dependencies between computed fields\n- Wrap in try-catch when accessing relationships\n- If it feels complex, simplify it!\n\n## Template Field Access Patterns\n\n**CRITICAL:** Understanding when to use different field access patterns prevents rendering errors.\n\n| Pattern | Usage | Purpose | Example |\n|---------|-------|---------|---------|\n| `{{@model.title}}` | **Raw Data Access** | Get raw field values for computation/display | `{{@model.title}}` gets the title string |\n| `<@fields.title />` | **Field Template Rendering** | Render field using its own template | `<@fields.title />` renders title field's embedded template |\n| `<@fields.phone @format=\"atom\" />` | **Compound Field Display** | Display compound fields (FieldDef) correctly | Prevents `[object Object]` display |\n| `<@fields.author />` | **Single Field Delegation** | Delegate rendering for ANY field (singular or collection) | Always use `@fields`, even for singular entities |\n| `<@fields.blogPosts @format=\"embedded\" />` | **Auto-Collection Rendering** | Default container automatically iterates collections (**CRITICAL:** Must use `.container > .containsMany-field` selector for spacing) | `
<@fields.blogPosts @format=\"embedded\" />
` with `.items > .containsMany-field { gap: 1rem; }` |\n| `<@fields.person @format=\"fitted\" style=\"width: 100%; height: 100%\" />` | **Fitted Format Override** | Style overrides required for fitted format (TEMPORARY) | Required for proper fitted rendering |\n| `{{#each @fields.blogPosts as |post|}}` | **Manual Collection Iteration** | Manual loop control with custom rendering | `{{#each @fields.blogPosts as |post|}}{{/each}}` |\n| `{{get @model.comments 0}}` | **Array Index Access** | Access array elements by index | `{{get @model.comments 0}}` gets first comment |\n| `{{if @model.description @model.description \"No description available\"}}` | **Inline Fallback Values** | Provide defaults for missing values in single line | Shows fallback when description is empty or null |\n| `{{currencyFormat @model.totalCost 'USD'}}` | **Currency Formatting** | Format numbers as currency in templates (use i18n in JS) | `{{currencyFormat @model.totalCost 'USD'}}` shows $1,234.56 |\n| `{{formatDateTime @model.publishDate 'MMM D, YYYY'}}` | **Date Formatting** | Format dates in templates (use i18n in JS) | `{{formatDateTime @model.publishDate 'MMM D, YYYY'}}` shows Jan 15, 2025 |\n| `@context.searchResultsComponent` | **Query Result Display** | Render query results (prerendered HTML or live card) | See Query System section |\n\n### ⚠️ CRITICAL: @model Iteration vs @fields Delegation\n\n**Once you iterate with @model, you CANNOT delegate to @fields within that iteration.**\n\n```hbs\n\n{{#each @model.teamMembers as |member|}}\n <@fields.member @format=\"embedded\" /> \n{{/each}}\n\n\n<@fields.teamMembers @format=\"embedded\" />\n\n\n{{#each @model.teamMembers as |member|}}\n
{{member.name}}
\n{{/each}}\n\n\n\n```\n\n**Why this breaks:** @fields provides field-level components. Once you're iterating with @model, you're working with raw data, not field components.\n\n**Decision Rule:** Before iterating, decide:\n- Need composability? → Use delegated rendering\n- Need filtering? → Use query patterns (@context.searchResultsComponent / getCards)\n- Need custom control? → Use @model but handle ALL rendering yourself\n\n### Styling Responsibility Model\n\n**Core Rule: Container provides frame, content provides data**\n\n**Visual Chrome (border, shadow, radius, background):**\n- **Isolated/Embedded/Fitted/Edit:** Parent or CardContainer handles\n- **Atom:** Self-styles (inline use case)\n\n**Layout:** Parent controls container dimensions and spacing via `.containsMany-field`\n\n## Format Dimensions Comparison\n\n| Format | Width | Height | Parent Sets | Key Behavior |\n|--------|-------|--------|-------------|--------------|\n| **Isolated** | Max-width + centered | Natural + scrollable | ❌ Neither | Full viewport available |\n| **Embedded** | Fills container | Natural (parent can limit) | ✅ Width only | Parent can add \"view more\" controls |\n| **Fitted** | Fills exactly | Fills exactly | ✅ **Both** | Must set width AND height |\n| **Atom** | Inline/shrink to fit | Inline | ❌ Neither | Self-contained sizing |\n| **Edit** | Fills container | Natural form height | ✅ Width only | Grows with fields |\n\n### Embedded Height Control Pattern\n```css\n/* Parent can limit embedded height with expand control */\n.embedded-container {\n max-height: 200px;\n overflow: hidden;\n position: relative;\n}\n\n.embedded-container.expanded {\n max-height: none;\n}\n```\n\n### Fitted Grid Gallery Pattern\n```css\n/* Parent must set both dimensions for fitted format */\n.photo-gallery > .containsMany-field {\n display: grid;\n grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));\n grid-auto-rows: 300px; /* Fixed height required for fitted */\n gap: 1rem;\n}\n/* Fitted items automatically fill cell via temporary rule: style=\"width: 100%; height: 100%\" */\n```\n\n### Quick Rule: Embedded vs Fitted\n**Embedded:** Like paragraphs - flow naturally, parent can truncate \n**Fitted:** Like photos - exact dimensions required\n\n### Displaying Compound Fields\n\n**CRITICAL:** When displaying compound fields (FieldDef types) like `PhoneNumberField`, `AddressField`, or custom field definitions, you must use their format templates, not raw model access:\n\n```hbs\n\n

Phone: {{@model.phone}}

\n\n\n

Phone: <@fields.phone @format=\"atom\" />

\n\n\n
\n <@fields.phone @format=\"embedded\" />\n
\n```\n\n**💡 Line-saving tip:** Keep self-closing tags compact:\n```hbs\n\n<@fields.author @format=\"embedded\" />\n<@fields.phone @format=\"atom\" />\n```\n\n### @fields Delegation Rule\n\n**CRITICAL:** When delegating to embedded/fitted formats, you must iterate through `@fields`, not `@model`. Always use `@fields` for delegation, even for singular fields. See \"⚠️ CRITICAL: @model Iteration vs @fields Delegation\" section for why you cannot mix these patterns.\n\n```hbs\n\n<@fields.author @format=\"embedded\" />\n<@fields.items @format=\"embedded\" />\n{{#each @fields.items as |item|}}\n \n{{/each}}\n\n\n{{#each @model.items as |item|}}\n <@fields.??? @format=\"embedded\" /> \n{{/each}}\n```\n\n**Line-saving tip:** Put `/>` on the end of the previous line for self-closing tags:\n```hbs\n\n<@fields.author @format=\"embedded\" \n/>\n\n\n<@fields.author @format=\"embedded\" />\n```\n\n**containsMany Spacing Pattern:** Due to an additional wrapper div, target `.containsMany-field`:\n```css\n/* For grids */\n.products-grid > .containsMany-field {\n display: grid;\n grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));\n gap: 1rem;\n}\n\n/* For lists */\n.items-list > .containsMany-field {\n display: flex;\n flex-direction: column;\n gap: 0.75rem;\n}\n```\n\n## Template Fallback Value Patterns\n\n**CRITICAL:** Boxel cards boot with no data by default. Templates must gracefully handle null, undefined, and empty string values at ALL levels of data access to prevent runtime errors and provide meaningful visual fallbacks.\n\n### Three Primary Patterns for Fallbacks\n\n**1. Inline if/else (for simple display fallbacks):**\n```hbs\n{{if @model.eventTime (formatDateTime @model.eventTime \"MMM D, h:mm A\") \"Event time to be announced\"}}\n

{{if @model.title @model.title \"Untitled Document\"}}

\n

Status: {{if @model.status @model.status \"Status pending\"}}

\n```\n\n**2. Block-based if/else (for complex content):**\n```hbs\n
\n {{#if @model.eventTime}}\n {{formatDateTime @model.eventTime \"MMM D, h:mm A\"}}\n {{else}}\n Event time to be announced\n {{/if}}\n
\n\n{{#if @model.description}}\n
\n <@fields.description />\n
\n{{else}}\n
\n

No description provided yet. Click to add one.

\n
\n{{/if}}\n```\n\n**3. Unless for safety/validation checks (composed with other helpers):**\n```hbs\n{{unless (and @model.isValid @model.hasPermission) \"⚠️ Cannot proceed - missing validation or permission\"}}\n{{unless (or @model.email @model.phone) \"Contact information required\"}}\n{{unless (gt @model.items.length 0) \"No items available\"}}\n{{unless (eq @model.status \"active\") \"Service unavailable\"}}\n```\n\n**Best Practices:** Use descriptive placeholder text rather than generic \"N/A\", style placeholder text differently (lighter color, italic), use `unless` for safety checks and `if` for display fallbacks.\n\n**Icon Usage:** Avoid emoji in templates (unless the application specifically calls for it) due to OS/platform variations that cause legibility issues. Use Boxel icons only for static card/field type icons (displayName properties). In templates, use inline SVG instead since we can't be sure which Boxel icons exist. **Note:** Avoid SVG `url(#id)` references (gradients, patterns) as Boxel cannot route these - use CSS styling instead.\n\n## Template Array Handling Patterns\n\n**CRITICAL:** Templates must gracefully handle all array states to prevent errors. Arrays can be undefined, null, empty, or populated.\n\n### The Three Array States\n\nYour templates must handle:\n1. **Completely undefined arrays** - Field doesn't exist or is null\n2. **Empty arrays** - Field exists but has no items (`[]`)\n3. **Arrays with actual data** - Field has one or more items\n\n### Array Logic Pattern\n\n**❌ WRONG - Only checks for existence:**\n```hbs\n{{#if @model.goals}}\n
    \n {{#each @model.goals as |goal|}}\n
  • {{goal}}
    • \n {{/each}}\n
\n{{/if}}\n```\n\n**✅ CORRECT - Checks for length and provides empty state:**\n```hbs\n{{#if (gt @model.goals.length 0)}}\n
\n

\n \n \n \n \n \n Daily Goals\n

\n
    \n {{#each @model.goals as |goal|}}\n
  • {{goal}}
    • \n {{/each}}\n
\n
\n{{else}}\n
\n

\n \n \n \n \n \n Daily Goals\n

\n

No goals set yet. What would you like to accomplish?

\n
\n{{/if}}\n```\n\n### Complete Array Handling Example with Required Spacing\n\n```gts\n\n```\n\n**Remember:** When implementing templates via SEARCH/REPLACE, include tracking markers ⁿ for style blocks\n\n## Core Patterns\n\n### 1. Card Definition with Safe Computed Title\n```gts\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nimport { CardDef, field, contains, linksTo, containsMany, linksToMany, Component } from 'https://cardstack.com/base/card-api'; // ⁸ Core imports\nimport StringField from 'https://cardstack.com/base/string';\nimport DateField from 'https://cardstack.com/base/date';\nimport FileTextIcon from '@cardstack/boxel-icons/file-text'; // ⁹ icon import\nimport { Author } from './author';\n\nexport class BlogPost extends CardDef { // ¹⁰ Card definition\n static displayName = 'Blog Post';\n static icon = FileTextIcon; // ✅ CORRECT: Boxel icons for static card/field type icons\n static prefersWideFormat = true; // Optional: Only for dashboards/apps. Content cards (albums, listings) rarely need this.\n \n @field headline = contains(StringField); // ¹¹ Primary identifier - NOT 'title'!\n @field publishDate = contains(DateField);\n @field author = linksTo(Author); // ¹² Reference to another card\n @field tags = containsMany(TagField); // ¹³ Multiple embedded fields\n @field relatedPosts = linksToMany(() => BlogPost); // ¹⁴ Self-reference with arrow function\n \n // ¹⁵ Compute the inherited title from primary fields ONLY - keep it simple!\n @field title = contains(StringField, {\n computeVia: function(this: BlogPost) {\n try {\n const baseTitle = this.headline ?? 'Untitled Post';\n const maxLength = 50;\n \n if (baseTitle.length <= maxLength) return baseTitle;\n return baseTitle.substring(0, maxLength - 3) + '...';\n } catch (e) {\n console.error('BlogPost: Error computing title', e);\n return 'Untitled Post';\n }\n }\n });\n}\n```\n\n### WARNING: Do NOT Use Constructors for Default Values\n\n**CRITICAL:** Constructors should NOT be used for setting default values in Boxel cards. Use template fallbacks (if field is editable) or computeVia (only if field is strictly read-only) instead.\n\n```gts\n// ❌ WRONG - Never use constructors for defaults\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nexport class Todo extends CardDef {\n constructor(owner: unknown, args: {}) {\n super(owner, args);\n this.createdDate = new Date(); // DON'T DO THIS\n this.isCompleted = false; // DON'T DO THIS\n }\n}\n```\n\n### **CRITICAL: NEVER Create JavaScript Objects in Templates**\n\n**Templates are for simple display logic only.** Never call constructors, create objects, or perform complex operations in template expressions.\n\n```hbs\n\n{{if @model.currentMonth @model.currentMonth (formatDateTime (new Date()) \"MMMM YYYY\")}}\n
{{someFunction(@model.data)}}
\n\n\n{{if @model.currentMonth @model.currentMonth this.currentMonthDisplay}}\n
{{this.processedData}}
\n```\n\n```gts\n// ✅ CORRECT: Define logic in JavaScript\nexport class MyCard extends CardDef { // ²⁴ Card definition\n get currentMonthDisplay() {\n return new Intl.DateTimeFormat('en-US', { \n month: 'long', \n year: 'numeric' \n }).format(new Date());\n }\n \n get processedData() {\n return this.args.model?.data ? this.processData(this.args.model.data) : 'No data';\n }\n \n private processData(data: any) {\n // Complex processing logic here\n return result;\n }\n}\n```\n\n### 2. Field Definition (Always Include Embedded Template)\n\n**CRITICAL:** Every FieldDef file must import FieldDef and MUST be exported:\n\n```gts\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nimport { FieldDef, field, contains, Component } from 'https://cardstack.com/base/card-api'; // ¹⁶ Core imports\nimport StringField from 'https://cardstack.com/base/string';\nimport LocationIcon from '@cardstack/boxel-icons/map-pin'; // ¹⁷ icon import\n\n// Creating a new field from scratch\nexport class AddressField extends FieldDef { // ¹⁸ Field definition\n static displayName = 'Address';\n static icon = LocationIcon; // ✅ CORRECT: Boxel icons for static card/field type icons\n \n @field street = contains(StringField); // ¹⁹ Component fields\n @field city = contains(StringField);\n @field postalCode = contains(StringField);\n @field country = contains(StringField);\n \n // ²⁰ Always create embedded template for FieldDefs\n static embedded = class Embedded extends Component {\n \n };\n}\n\n// ✅ CORRECT: Extending a base field for customization\nimport BaseAddressField from 'https://cardstack.com/base/address';\n\nexport class EnhancedAddressField extends BaseAddressField { // ²⁵ Extended field\n static displayName = 'Enhanced Address';\n \n // ²⁶ Add new fields to the base\n @field apartment = contains(StringField);\n @field instructions = contains(StringField);\n \n // ²⁷ Override templates as needed\n static embedded = class Embedded extends Component {\n \n };\n}\n```\n\n### 3. Computed Properties with Safety\n\n**CRITICAL:** Avoid cycles and infinite recursion in computed fields.\n\n```gts\n// ❌ DANGEROUS: Self-reference causes infinite recursion\n@field title = contains(StringField, {\n computeVia: function(this: BlogPost) {\n return this.title || 'Untitled'; // ❌ Refers to itself - STACK OVERFLOW!\n }\n});\n\n// ❌ DANGEROUS: Circular dependency between computed fields\n@field displayName = contains(StringField, {\n computeVia: function(this: Person) {\n return this.formattedName; // refers to formattedName\n }\n});\n@field formattedName = contains(StringField, {\n computeVia: function(this: Person) {\n return `Name: ${this.displayName}`; // refers back to displayName - CYCLE!\n }\n});\n\n// ✅ SAFE: Reference only base fields, keep it unidirectional\n@field fullName = contains(StringField, { // ²⁸ Computed field\n computeVia: function(this: Person) {\n try {\n const first = this.firstName ?? '';\n const last = this.lastName ?? '';\n const full = `${first} ${last}`.trim();\n return full || 'Name not provided';\n } catch (e) {\n console.error('Person: Error computing fullName', e);\n return 'Name unavailable';\n }\n }\n});\n\n// ✅ SAFE: Computed title from primary fields only with error handling\n@field title = contains(StringField, { // ²⁹ Safe computed title\n computeVia: function(this: BlogPost) {\n try {\n const headline = this.headline ?? 'Untitled Post';\n const date = this.publishDate ? ` (${new Date(this.publishDate).getFullYear()})` : '';\n return `${headline}${date}`;\n } catch (e) {\n console.error('BlogPost: Error computing title', { error: e, headline: this.headline });\n return 'Untitled Post';\n }\n }\n});\n```\n\n### 4. Templates with Proper Computation Patterns\n\n**Remember:** When implementing templates via SEARCH/REPLACE, track all major sections with ⁿ and include the post-block notation `╰ ⁿ⁻ᵐ`\n\n```gts\nstatic isolated = class Isolated extends Component { // ³⁰ Isolated format\n @tracked showComments = false;\n \n // ³¹ CRITICAL: Do ALL computation in functions, never in templates\n get safeTitle() {\n try {\n return this.args?.model?.title ?? 'Untitled Post';\n } catch (e) {\n console.error('BlogPost: Error accessing title', e);\n return 'Untitled Post';\n }\n }\n \n get commentButtonText() {\n try {\n const count = this.args?.model?.commentCount ?? 0;\n return this.showComments ? `Hide Comments (${count})` : `Show Comments (${count})`;\n } catch (e) {\n console.error('BlogPost: Error computing comment button text', e);\n return this.showComments ? 'Hide Comments' : 'Show Comments';\n }\n }\n \n toggleComments = () => {\n this.showComments = !this.showComments;\n }\n \n \n};\n```\n\n## Design Philosophy and Competitive Styling\n\n**Design and implement your stylesheet to fit the domain you are generating.** Research the top 2 products/services in that area and design your card as if you are the 3rd competitor looking to one-up the market in terms of look and feel, functionality, and user-friendliness.\n\n**Approach:** Study the leading players' design patterns, then create something that feels more modern, intuitive, and polished. Focus on micro-interactions, thoughtful spacing, superior visual hierarchy, and removing friction from user workflows.\n\n**Key Areas to Compete On:**\n- **Visual Polish:** Better typography, spacing, and color schemes\n- **Interaction Design:** Smoother animations, better feedback, clearer affordances\n- **Information Architecture:** More logical organization, better progressive disclosure\n- **Accessibility:** Superior contrast, keyboard navigation, screen reader support\n- **Performance:** Faster loading, smoother animations, responsive design\n\n**Typography Guidance:** Always discern what typeface would be best for the specific domain. Don't default to Boxel or OS fonts - use proven and popular Google fonts whenever possible. \n\nChoose modern, readable fonts that match your design's personality. Clean sans-serifs like Inter, Roboto, Open Sans, Source Sans Pro, DM Sans, Work Sans, Manrope, or Plus Jakarta Sans work great for body text. For headings, consider geometric fonts (Montserrat, Space Grotesk, Raleway, Poppins), bold condensed options (Bebas Neue, Archivo Black, Oswald, Anton), or elegant serifs (Playfair Display, Lora, Merriweather, Crimson Text). Add character with rounded alternatives (Nunito, Comfortaa), industrial styles (Barlow, Righteous), or even scripts where appropriate (Pacifico, Dancing Script). The key is balancing readability with visual impact – pick fonts that enhance your content's tone while staying legible across all devices. Feel free to explore beyond these suggestions to find what best fits your design vision.\n\n\n## Design Token Foundation\n\n**Dense professional layouts with thoughtful scaling:**\n\n**Typography:** Start at 0.8125rem (13px) base, scale in small increments\n* Body: 0.8125rem, Labels: 0.875rem, Headings: 1rem-1.25rem\n\n**Spacing:** Tight but breathable, using 0.25rem (4px) increments\n* Inline: 0.25-0.5rem, Sections: 0.75-1rem, Major breaks: 1.5-2rem\n\n**Brand Customization:** Define your unique identity\n* Colors: Primary, secondary, accent, surface, text\n* Fonts: Choose domain-appropriate Google fonts (never default to system)\n* Radius: Match the aesthetic (sharp for technical, soft for friendly)\n\n**Font Selection:** Always choose fonts that match your domain's character. Use proven Google fonts that align with the emotional tone and professional context of your specific application.\n\n## CSS Safety Rules\n\n### Critical CSS Safety Rules\n\n**Scoped Styles:** ALWAYS use `\n \n };\n}\n```\n\n### Advanced Dynamic CSS Patterns\n\n**Module-scoped CSS generators with sanitization:**\n\n```gts\nimport { htmlSafe } from '@ember/template';\nimport { sanitizeHtml } from '@cardstack/runtime-common';\n\n// Sanitization helper\nfunction sanitize(html: string) {\n return htmlSafe(sanitizeHtml(html));\n}\n\n// Size helper\nconst setContainerSize = ({ width, height }) => {\n return sanitize(`width: ${width}px; height: ${height}px`);\n};\n\n// Background image helper\nconst setBackgroundImage = (backgroundURL) => {\n if (!backgroundURL) return;\n return sanitize(`background-image: url(${backgroundURL});`);\n};\n\n// Complex styling helper\nconst setCardStyle = (model) => {\n if (!model) return;\n \n const styles = [];\n \n if (model.cssVariables) styles.push(model.cssVariables);\n if (model.borderStyle) styles.push(`border-style: ${model.borderStyle}`);\n if (model.opacity) styles.push(`opacity: ${model.opacity}`);\n if (model.transform) styles.push(`transform: ${model.transform}`);\n \n return styles.length ? sanitize(styles.join('; ')) : undefined;\n};\n```\n\n**Usage in templates - CRITICAL syntax:**\n```hbs\n\n
\n
\n
\n\n\n
\n```\n\n**NEVER attempt dynamic values in `\n```\n\n### Common CSS Errors to Avoid\n\n1. **Not scoping styles** - Always use `\n \n};\n\n// ⁴⁰ Then the Author card should have complementary styling:\nexport class Author extends CardDef {\n static embedded = class Embedded extends Component {\n \n };\n}\n```\n\n#### Delegation Patterns\n\n```gts\n\n```\n\n### Avoiding Relationship Cycles\n\n**Problem:** Bidirectional `linksTo` relationships create circular dependencies that complicate indexing and can cause infinite recursion.\n\n**Solution:** Use canonical (one-way) links + dynamic queries for reverse relationships.\n\n#### Pattern: Canonical Links + Dynamic Queries\n\n1. **Define canonical links** - Choose the primary direction in your schema:\n```gts\n// Employee owns the supervisor relationship\nexport class Employee extends CardDef {\n @field supervisor = linksTo(() => Employee);\n @field department = linksTo(Department);\n}\n\n// Department owns the manager relationship\nexport class Department extends CardDef {\n @field manager = linksTo(Employee);\n}\n```\n\n2. **Use dynamic queries for reverse relationships** - Fetch at runtime instead of schema links:\n```gts\n// Get direct reports dynamically (in Employee component)\nget directReportsQuery(): Query {\n return {\n filter: {\n on: { module: './employee', name: 'Employee' },\n eq: { supervisor: this.args.model.id }\n }\n };\n}\n\n// Use with getCards or @context.searchResultsComponent\ndirectReports = this.args.context?.getCards(this, () => this.directReportsQuery, () => this.realms);\n```\n\n**Key Principle:** Model the simplest set of unidirectional links that define core relationships. Use queries for derived views, aggregations, and inverse relationships.\n\n### BoxelSelect: Smart Dropdown Menus\n\nRegular HTML selects are limited to plain text. BoxelSelect lets you create rich, searchable dropdowns with custom rendering.\n\n#### Pattern: Rich Select with Custom Options\n\n```gts\nexport class OptionField extends FieldDef { // ⁴³ Option field for select\n static displayName = 'Option';\n \n @field key = contains(StringField);\n @field label = contains(StringField);\n @field description = contains(StringField);\n\n static embedded = class Embedded extends Component {\n \n };\n}\n\nexport class ProductCategory extends CardDef { // ⁴⁴ Card using BoxelSelect\n @field selectedCategory = contains(OptionField);\n \n static edit = class Edit extends Component { // ⁴⁵ Edit format\n @tracked selectedOption = this.args.model?.selectedCategory;\n\n options = [\n { key: '1', label: 'Electronics', description: 'Phones, computers, and gadgets' },\n { key: '2', label: 'Clothing', description: 'Fashion and apparel' },\n { key: '3', label: 'Home & Garden', description: 'Furniture and decor' }\n ];\n\n updateSelection = (option: typeof this.options[0] | null) => {\n this.selectedOption = option;\n this.args.model.selectedCategory = option ? new OptionField(option) : null;\n }\n\n \n };\n}\n```\n\n### Custom Edit Controls\n\nCreate user-friendly edit controls that accept natural input. Hide complexity in expandable sections while keeping ALL properties editable and inspectable.\n\n```gts\n// Example: Natural language time period input\nstatic edit = class Edit extends Component {\n @tracked showDetails = false;\n \n @action parseInput(value: string) {\n // Parse \"Q1 2025\" → quarter: 1, year: 2025, startDate: Jan 1, endDate: Mar 31\n // Parse \"April 2025\" → month: 4, year: 2025, startDate: Apr 1, endDate: Apr 30\n }\n \n \n};\n```\n\n## Query System: Finding and Displaying Cards\n\n### The 'on' Property Rule (MEMORIZE THIS)\n\n**When using filters beyond basic type search, MUST include `on` as sibling:**\n\n```typescript\n// ❌ WRONG - Will fail\n{ range: { price: { lte: 100 } } }\n\n// ✅ CORRECT - 'on' specifies card type\n{ \n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n range: { price: { lte: 100 } } \n}\n\n// ✅ EXCEPTION - Simple eq after type filter\n{ \n every: [\n { type: { module: new URL('./task', import.meta.url).href, name: 'Task' } },\n { eq: { status: \"active\" } } // No 'on' needed immediately after type\n ]\n}\n```\n\n### Query Quick Reference\n\n#### Filter Types & 'on' Requirements\n| Filter | Needs 'on'? | Example |\n|--------|-------------|---------|\n| `type` | No | `{ type: { module: '...', name: 'Product' } }` |\n| `eq` | Yes* | `{ on: {...}, eq: { status: \"active\" } }` |\n| `contains` | Yes | `{ on: {...}, contains: { tags: \"urgent\" } }` |\n| `range` | Yes | `{ on: {...}, range: { price: { gte: 100 } } }` |\n| `every` | No | `{ every: [...] }` (AND) |\n| `any` | No | `{ any: [...] }` (OR) |\n| `not` | No | `{ not: { eq: {...} } }` |\n\n*Only when not directly after type filter\n\n#### Range Operators\n`gt` (>) `gte` (>=) `lt` (<) `lte` (<=)\n\n#### Module & Realm Rules\n```typescript\n// ✅ ALWAYS absolute URLs\n{ module: new URL('./product', import.meta.url).href, name: 'Product' }\n\n// ✅ Realms need trailing slash\n'https://app.boxel.ai/sarah/projects/' // ✅\n'https://app.boxel.ai/sarah/projects' // ❌\n```\n\n### ⚠️ CRITICAL: The 'on' Attribute is MANDATORY\n\n**Missing 'on' will lead to no results shown!** When using:\n- `eq`, `contains`, `range` filters (except immediately after type filter)\n- `sort` on type-specific fields (anything beyond base fields like id, createdAt)\n\n```typescript\n// ❌ WILL FAIL - Missing 'on' for sort\n{ \n sort: [{ by: \"price\", direction: \"desc\" }]\n}\n\n// ✅ CORRECT - Include 'on' for type-specific fields\n{ \n sort: [{ \n by: \"price\", \n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n direction: \"desc\" \n }]\n}\n```\n\n### Complete Query Pattern\n\n```typescript\nconst query: Query = {\n filter: {\n every: [ // AND\n { type: { module: new URL('./product', import.meta.url).href, name: 'Product' } },\n { \n any: [ // OR\n { on: { module: new URL('./product', import.meta.url).href, name: 'Product' }, eq: { category: \"laptop\" } },\n { on: { module: new URL('./product', import.meta.url).href, name: 'Product' }, eq: { category: \"tablet\" } }\n ]\n },\n { \n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n range: { \n price: { gte: 100, lte: 2000 }, // Multiple conditions\n rating: { gte: 4 }\n }\n },\n { \n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n contains: { features: \"wireless\" }\n },\n {\n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n not: { eq: { status: \"discontinued\" } } // Exclude\n }\n ]\n },\n sort: [\n { by: \"createdAt\", direction: \"desc\" }, // General field\n { \n by: \"warranty\", // Type-specific needs 'on'\n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n direction: \"desc\" \n }\n ],\n page: { number: 0, size: 20 }\n};\n```\n\n### Decision: @context.searchResultsComponent vs getCards\n\n```\nRender a list of results (prefers fast prerendered HTML, live fallback)? → @context.searchResultsComponent\nNeed the instances in JS (read / manipulate / aggregate)? → getCards\nNeed raw field data access? → getCards\n```\n\n## Query Result List Pattern (`@context.searchResultsComponent`)\n\n`@context.searchResultsComponent` (the `` component) renders a query as one heterogeneous stream: each result paints as fast prerendered HTML (hydrated lazily on interaction) or falls back to a live card — you never branch on which. It re-runs automatically when a subscribed realm reindexes.\n\n```gts\n// ⁴⁹ Component with a dynamic search-entry query\nimport {\n searchEntryWireQueryFromQuery,\n type SearchEntryWireQuery,\n} from '@cardstack/runtime-common';\n\nexport class Dashboard extends Component {\n realms = ['https://app.boxel.ai/sarah/tasks/']; // Trailing slash!\n\n // Build the search-entry query from an ordinary query, then add realms.\n get urgentTasksQuery(): SearchEntryWireQuery {\n return {\n ...searchEntryWireQueryFromQuery({\n filter: {\n every: [\n { type: { module: new URL('./task', import.meta.url).href, name: 'Task' } },\n {\n on: { module: new URL('./task', import.meta.url).href, name: 'Task' },\n not: { eq: { status: \"completed\" } }\n }\n ]\n },\n sort: [{ by: \"dueDate\", direction: \"asc\" }],\n page: { size: 10 }\n }),\n realms: this.realms,\n };\n }\n\n \n}\n```\n\n### Making Query Results Clickable\n\nWrap each entry's component in a `CardContainer` with `cardComponentModifier` so clicking navigates to the card — the modifier keys off `entry.id` (the card/file URL):\n\n```gts\n// ⁵¹ Wrap with CardContainer for navigation\n<@context.searchResultsComponent @query={{this.query}} @mode=\"hover\" as |results|>\n
    \n {{#each results.entries key=\"id\" as |entry|}}\n
  • \n \n \n \n
    • \n {{/each}}\n
\n\n```\n\n## getCards Pattern (Data Manipulation)\n\n```gts\n// ⁵² Direct assignment for data access\ncardsResult = this.args.context?.getCards(\n this,\n () => this.query,\n () => this.realms,\n { isLive: true }\n);\n\n// ⁵³ Post-retrieval sorting\nget sortedByRevenue() {\n const products = this.cardsResult?.instances ?? [];\n return [...products].sort((a, b) => {\n const scoreA = (a.revenue || 0) * (a.rating || 1);\n const scoreB = (b.revenue || 0) * (b.rating || 1);\n return scoreB - scoreA;\n });\n}\n\n// ⁵⁴ Aggregation\nget totalRevenue() {\n return this.cardsResult?.instances?.reduce((sum, p) => sum + (p.revenue || 0), 0) || 0;\n}\n```\n\n\n## Creating Fitted Formats - The Four Sub-formats Strategy\n\nFitted Formats are unique part of the Boxel Architecture in that it allows a version of a card or a field that fit into any slot (width and height up to 600px) allocated by a parent container, so as to support listing, gallery, chooser, even 3D sprites usage without the parent knowing anything about this card's or field's schema or template other than its ID.\n\nTo create fitted formats that automatically adapt to any container size, implement four responsive subformats within a single fitted template. This pattern ensures your cards look perfect whether displayed as tiny badges or full-width cards. While the platform provides a fallback fitted format for CardDefs, custom implementation is strongly recommended for optimal display. For FieldDefs, fitted format is optional as embedded format is the primary requirement.\n\n### Core Concept\n\nYou only have one fitted template so that the resulting parent template only needs to give a size they want to display and you will provide the best layout given that space.\n\nTo do that, create 4 subformats and turn on only one at a time. Create 4 divs inside the fitted template and use container queries to turn them on and off. Make sure there are no gaps where no subformat is active.\n\nFitted format shouldn't have borders, that is drawn by parent.\n\n**RECOMMENDED:** Every CardDef should implement a custom fitted format for optimal display. While the platform provides a fallback, custom fitted formats ensure your cards look their best in galleries, grids, choosers, and dashboards.\n\n**Key Implementation Points:**\n- **CardDef:** Custom fitted format recommended (platform provides fallback)\n- **FieldDef:** Embedded format mandatory, fitted format optional\n- Create 4 divs inside the fitted template (badge, strip, tile, card)\n- Use container queries to show only the appropriate subformat\n- CRITICAL: Ensure no gaps where no subformat is active - all sizes must be handled\n- Fitted format shouldn't have borders (drawn by parent)\n\n### Container Size Decision Tree\n\n```\nContainer Size\n │\n ├─ Height < 170px (Horizontal)\n │ │\n │ ├─ Width ≤ 150px → BADGE\n │ │ • 150×40 (micro)\n │ │ • 150×65 (small)\n │ │ • 150×105 (large) ← optimize\n │ │\n │ └─ Width > 150px → STRIP\n │ • 250×40 (single)\n │ • 250×65 (double)\n │ • 250×105 (triple)\n │ • 400×65 (wide double) ← optimize\n │ • 400×105 (wide triple)\n │\n └─ Height ≥ 170px (Vertical)\n │\n ├─ Width < 400px → TILE\n │ • 150×170 (narrow)\n │ • 170×250 (grid) ← optimize\n │ • 250×170 (wide)\n │ • 250×275 (large)\n │\n └─ Width ≥ 400px → CARD\n • 400×170 (compact)\n • 400×275 (standard) ← optimize\n • 400×445 (expanded)\n```\n\n#### Design Philosophy\n\n**First design the IDEAL layout for each subformat at the \"optimized for\" size.** Think of each subformat as if you were making 4 independent templates, each perfect for its specific use case.\n\n**Height Quantum:** The height breakpoints (40px, 65px, 105px, etc.) follow golden ratio progression (φ ≈ 1.618), creating natural visual harmony as formats scale.\n\n**Golden Ratio Usage:** Apply the golden ratio (1.618:1) throughout your layouts - for splits, spacing progressions, content zones, and visual balance. This mathematical harmony creates inherently pleasing proportions.\n\n**Typography Hierarchy:** Create clear visual distinction between text levels:\n- **Size cascade:** Each level 80-87% of the previous (1em → 0.875em → 0.75em)\n- **Weight cascade:** Drop 100-200 font-weight units per level (600 → 500 → 400)\n- **Spacing cascade:** Buffer between levels follows 50% → 37.5% → 25% pattern\n- **Same-level spacing:** Use 25% of the element's font size\n\n**Qualities for All Fitted Formats:**\n- **Well-balanced** - Every element positioned with intention\n- **On-brand** - Visually polished and consistent\n- **Scannable** - Clear indicators, easy to parse\n- **Small multiples** - Differences pop in collections\n- **Clickable** - Inviting interaction (cards only)\n- **Complete** - Show key data within constraints\n- **Familiar yet superior** - Match expectations, execute better\n- **Identifier visible** - Never obscure with entrance animations\n- **Clear hierarchy** - Primary/secondary/tertiary distinct\n\n### Content Priority Guidelines\n\nSuggested priority order - adjust for your use case:\n\n1. **Title/Name** - Primary identifier\n2. **Image** - Visual identity \n3. **Short ID** - SKU, username, ticket #\n4. **Key Info** - Dates, stats, linked entities\n5. **Badge/Status** - Visual indicators\n6. **Key-Value Metadata** - Show complete pairs only\n7. **Description** - Low priority, line-clamp aggressively\n8. **CTA** - Hover/focus only in tiles\n\n**For FieldDefs:** Since fitted format is optional, focus on embedded format first. If implementing fitted: priorities shift since there's no click-through. Show most important data within space constraints - composite identity plus critical values.\n\n**Examples:**\n- **Inventory:** SKU/status may outrank title\n- **Analytics:** Numbers take precedence\n- **Tasks:** Due date/assignee before description\n\n### Container Query Skeleton\n\n```css\n.fitted-container {\n container-type: size;\n width: 100%;\n height: 100%;\n}\n\n/* Hide all by default */\n.badge-format, .strip-format, .tile-format, .card-format {\n display: none;\n width: 100%;\n height: 100%;\n /* CRITICAL: Clear space prevents edge bleeding - scales with container size */\n padding: clamp(0.1875rem, 2%, 0.625rem); /* 3px min → 10px max */\n box-sizing: border-box;\n}\n\n/* Micro containers: absolute minimum safe padding */\n@container (max-width: 80px) and (max-height: 80px) {\n .badge-format { \n padding: 0.1875rem; /* 3px - visual safety minimum */\n }\n}\n\n/* Small containers: tight but safe */\n@container (max-width: 150px) {\n .badge-format, .strip-format { \n padding: 0.25rem; /* 4px - small but comfortable */\n }\n}\n\n/* Medium containers: breathing room */\n@container (min-width: 250px) and (max-width: 399px) {\n .tile-format {\n padding: 0.5rem; /* 8px - standard spacing */\n }\n}\n\n/* Large containers: generous clear space */\n@container (min-width: 400px) {\n .card-format {\n padding: clamp(0.5rem, 2%, 0.625rem); /* 8px → 10px max for expanded */\n }\n}\n\n/* Activation ranges - NO GAPS */\n@container (max-width: 150px) and (max-height: 169px) {\n .badge-format { display: flex; }\n}\n\n@container (min-width: 151px) and (max-height: 169px) {\n .strip-format { display: flex; }\n}\n\n@container (max-width: 399px) and (min-height: 170px) {\n .tile-format { display: flex; flex-direction: column; }\n}\n\n@container (min-width: 400px) and (min-height: 170px) {\n .card-format { display: flex; flex-direction: column; }\n}\n\n/* Compact card: horizontal split at golden ratio */\n@container (min-width: 400px) and (height: 170px) {\n .card-format { \n flex-direction: row;\n gap: 1rem;\n }\n .card-format > * {\n display: flex;\n flex-direction: column;\n }\n .card-format > *:first-child { flex: 1.618; }\n .card-format > *:last-child { flex: 1; }\n}\n\n/* Background fills respect padding for visual safety */\n.badge-format.has-fill,\n.strip-format.has-fill,\n.tile-format.has-fill,\n.card-format.has-fill {\n background: var(--fill-color);\n /* Background extends to edge but content stays within padding */\n background-clip: padding-box; /* Or border-box if fill should reach edge */\n}\n\n/* Type hierarchy - MANDATORY */\n.primary-text {\n font-size: 1em;\n font-weight: 600;\n color: var(--text-primary, rgba(0,0,0,0.95));\n line-height: 1.2;\n}\n\n.secondary-text {\n font-size: 0.875em; /* 87.5% of primary */\n font-weight: 500;\n color: var(--text-secondary, rgba(0,0,0,0.85));\n line-height: 1.3;\n}\n\n.tertiary-text {\n font-size: 0.75em; /* 75% of primary */\n font-weight: 400;\n color: var(--text-tertiary, rgba(0,0,0,0.7));\n line-height: 1.4;\n}\n\n/* Typography Hierarchy Spacing Heuristics */\n/* Primary → Secondary: 0.5em gap (half the primary size) */\n/* Secondary → Tertiary: 0.375em gap */\n/* Same level elements: 0.25em gap */\n\n.primary-text + .secondary-text {\n margin-top: 0.5em;\n}\n\n.secondary-text + .tertiary-text {\n margin-top: 0.375em;\n}\n\n.primary-text + .primary-text,\n.secondary-text + .secondary-text {\n margin-top: 0.25em;\n}\n\n/* Visual hierarchy multipliers:\n - Size: Each level ~80-87% of previous\n - Weight: Drop 100-200 units per level\n - Opacity: Drop 10-15% per level\n - Spacing: 50% → 37.5% → 25% of primary size */\n```\n\n### Subformat-Specific Rules\n\n**Design with familiar patterns** - Users know these formats from daily app usage. Meet their expectations, then exceed them with better spacing, smoother interactions, and superior visual polish. Doing something expected is good - just do it better.\n\n**Badge Format:**\n- Feels like exportable graphics\n- **Familiar from:** Slack badges, GitHub labels\n- 150×105 has 3 vertical elements\n- Fills/backgrounds extend to edges, content respects padding\n- **LEFT align always** - right elements balance\n- **Images:** Iconified 16-34px\n- **Heights:**\n - 40px: Title + icon horizontal only (or composite field identity)\n - 65px: Title + icon/ID stacked, single lines\n - 105px: Title + icon + status, magnetic edges\n- Use formatters for compact display\n- **For FieldDefs:** Show composite identity + key details\n- **Typography example at 105px:**\n - Primary title: 14px (0.875rem)\n - Secondary ID: 12px with 7px gap from title\n - Tertiary status: 10px with 5px gap from ID\n\n**Strip Format:**\n- **Primary use:** Dropdown and chooser panels where users scan and select\n- **Familiar from:** VS Code command palette, Spotlight search, Notion quick switcher\n- Optimized for quick scanning and selection - every pixel matters\n- **Title/identifier MUST ALWAYS be visible** - no animations, overlays, or effects that obscure it\n- Never use hover effects that hide or transform the identifier\n- Right-justify elements in wider strips\n- **Left aligned - no exceptions**\n- **Images:** \n - 40px height: Same as badge (20-34px) for consistency\n - 65px+ height: Standard size (40px)\n- **Height requirements:**\n - 40px: Title + key stat horizontally ONLY - single line, images 20-34px (same as badge)\n - 65px: Two single lines stacked vertically - NO wrapping within lines, images 40px\n - 105px: Three rows with magnetic edge spacing, images 40px\n- Abbreviate metadata, keep primary identity full\n\n**Tile Format:**\n- Standard vertical card layout\n- Optimize for grid viewing\n- Primary identity MUST be fully visible and prominent - no exceptions\n- The last vertical element MUST magnetically stick to the bottom\n\n**Card Format:**\n- Compact card (400×170) is split horizontally once at the golden ratio, then content within each panel is organized vertically\n- All other cards larger than compact card should be vertically subdivided\n- Expanded card is the full card with more data on the bottom\n- Expanded card MUST use all available vertical space - empty space is failure\n- The last vertical element MUST magnetically stick to the bottom\n\n### CTA Placement\n- **CardDef tile subformats only** (not FieldDefs)\n- Show on hover/focus only\n- Can obscure other content when shown\n- Lowest priority\n\n### Fitted Formats for FieldDefs (Optional)\n\n**IMPORTANT:** Fitted formats are optional for FieldDefs. FieldDefs require embedded format (with natural height) and that should be your primary focus. Only create fitted formats when your field might be displayed in fixed-size containers.\n\nWhen implementing fitted formats for FieldDefs, they require a different approach than CardDefs because they lack inherent identity and have no click-through capability.\n\n**Key Difference from CardDef Fitted:**\n- **CardDef fitted:** Shows identity + key info → click for details\n- **FieldDef fitted:** Shows most important data that fits (still space-constrained)\n\n**Creating Field Identity:**\nSince fields don't have clear identity like cards, create a composite identifier by combining 1-3 most important data points. For example:\n- Address field: Street + City\n- Price field: Amount + Currency + Trend\n- Contact field: Name + Primary method\n- Date range: Start + Duration + Status\n\n**Content Priority Shift:**\nBecause users can't click through to see more, fitted formats for fields should:\n- Show the most important data that fits the space\n- Prioritize key identifiers and critical values\n- Include essential metadata over nice-to-have details\n- Use composite identity from 1-3 key data points\n- Remember: still space-constrained like card fitted formats\n\n**Visual Field Handling:**\nFor image-based or visually-oriented compound fields:\n- Make the image/visual element primary (fill most space)\n- Overlay metadata on top with appropriate contrast\n- Use scrims or backdrop shadows for text legibility (except on precise visual content)\n- Consider the image as the \"identity\" with data as support\n- **CRITICAL:** For color fields, charts, or data visualizations, avoid scrims/overlays that alter perception\n\n**Example implementations:**\n- **Location field:** Map thumbnail with address overlay\n- **Chart field:** Visualization fills space, key metrics on corners (no scrim)\n- **Media field:** Thumbnail/preview large, metadata badge overlay\n- **Color field:** Swatch as background, hex/rgb values on top (pure color, no overlay)\n\n```css\n/* Example: Visual field with overlay metadata */\n.field-tile-format.visual-field {\n position: relative;\n padding: clamp(0.1875rem, 2%, 0.5rem); /* Clear space scales with container */\n}\n\n.field-tile-format .visual-primary {\n width: 100%;\n height: 100%;\n object-fit: cover;\n border-radius: 0.25rem; /* Subtle radius prevents harsh edges */\n}\n\n.field-tile-format .metadata-overlay {\n position: absolute;\n bottom: clamp(0.1875rem, 2%, 0.5rem); /* Match container padding */\n left: clamp(0.1875rem, 2%, 0.5rem);\n right: clamp(0.1875rem, 2%, 0.5rem);\n padding: 0.5rem;\n background: linear-gradient(to top, \n rgba(0,0,0,0.8) 0%, \n rgba(0,0,0,0) 100%);\n color: white;\n border-radius: 0.25rem;\n}\n\n/* Non-visual fields show more detail */\n.field-badge-format {\n padding: clamp(0.1875rem, 2%, 0.375rem); /* Clear space for badges */\n}\n\n.field-badge-format .composite-identity {\n font-weight: 600;\n margin-bottom: 0.25rem;\n}\n\n.field-badge-format .field-details {\n font-size: 0.75rem;\n opacity: 0.9;\n}\n```\n\n### Visual Guidelines\n\n#### Icons\n- Incorporate subtly with appropriate size/weight\n- Visual support only - include after key content\n\n#### Images\n- Priority 2 - show after primary identifier\n- **Badge:** Always iconified (16-34px)\n- **Strip:** \n - 40px height: 20-34px (matches badge)\n - 65px height: Fixed 40px\n - 105px height: Can fill height with AR constraint in wide strips (250px+)\n- **Tile:** Background with vibrant scrim if image would obscure text (except for visually precise content)\n- **Tile/Card:** Apply shared scale budget with text\n- Aspect ratios 0.7-1.4 unless decorative\n- Never completely displace text\n- **For visual FieldDefs:** Image can be primary with metadata overlay\n\n**Scrim effects:** Use accent colors for vibrant overlays. Mix brand colors with dark gradients: purple-to-black, blue-to-indigo-to-black, or accent-with-opacity layers. **CRITICAL:** Never apply scrims to visually precise content (color swatches, charts, data visualizations, medical imagery) as they alter perception and compromise accuracy.\n\n**Animation restraint:** Never use animations that move content near edges - can expose accidental borders. Strips especially need static, predictable layouts for scanning.\n\n#### 105px Height Magnetic Edge Layout\n\nAt 105px, use `justify-content: space-between` to push three elements to top/middle/bottom edges, maximizing visual separation.\n\n### Key Implementation Details\n\n1. **CardDef Fitted:** Custom recommended (fallback exists)\n2. **FieldDef Requirements:** Embedded mandatory, fitted optional\n3. **Container Queries:** `container-type: size`\n4. **No Gaps:** Cover all sizes\n5. **Line Clamping:** Match height constraints\n6. **Scaling:** `clamp()` ±20-25%\n7. **Height Use:** Fill 40/65/105px fully\n8. **40px:** Horizontal only\n9. **105px:** `justify-content: space-between`\n10. **Strip IDs:** Always visible\n11. **Clear Space:** 3px min to 1rem max\n12. **Type Hierarchy:** Size/weight/spacing cascades (80-87% per level)\n13. **Data Shaping:** Use formatters\n14. **Priority:** Key-values > descriptions\n15. **Badge Images:** 16-34px scaling\n16. **Strip Images:** Match badge at 40px, larger at 65px+, AR-fill at 105px wide\n17. **Scale Budget:** 50% shared text/image\n18. **Font Scaling:** Smaller = smaller base\n19. **Key-Values:** Complete pairs only\n20. **Familiar Patterns:** Match expectations\n21. **Edge Fills:** Backgrounds full, content padded\n22. **Vibrant Scrims:** Accent colors\n23. **No Edge Animations:** Prevent border exposure\n24. **FieldDef Identity:** Composite 1-3 key data points for recognition\n25. **Visual Precision:** No scrims on color/chart/data viz content\n\n\n\n## CRITICAL Reminders\n\n1. **@context.searchResultsComponent renders components, not data** - For data in JS, use getCards\n2. **Type-specific sort fields MUST have 'on'** - Missing 'on' = no results shown!\n3. **Empty arrays need length check** - `(gt @model.items.length 0)`\n4. **Query result spacing** - Use `.container > .containsMany-field` pattern\n5. **Always use absolute module URLs** - `new URL(...).href`\n\n### Using getCards for Data Access and Aggregation\n\nWhen you need full access to card data for calculations, aggregations, or custom processing, use the `getCards` API from context.\n\n#### Basic getCards Pattern\n\n```gts\n// ❌ WRONG: Don't import getCards - it's just a type definition\n// import { getCards } from '@cardstack/runtime-common';\n\n// ✅ CORRECT: Use getCards from context\n// With live updates (for dashboards)\ncardsResult = this.args.context?.getCards(\n this,\n () => this.query,\n () => this.realmHrefs,\n { isLive: true }\n);\n\n// For one-time load (omit isLive)\ncardsResult = this.args.context?.getCards(\n this,\n () => this.query,\n () => this.realmHrefs\n);\n```\n\n#### Working with getCards Results\n\n```gts\n// getCards returns: { instances, isLoading, instancesByRealm }\ncardsResult = this.args.context?.getCards(\n this,\n () => this.storyQuery,\n () => this.realmHrefs,\n);\n\n// Frontend sorting/filtering\nget sortedCards() {\n const cards = this.cardsResult?.instances ?? [];\n return [...cards].sort((a, b) => b.rating - a.rating);\n}\n\n\n```\n\n#### Map/Reduce Aggregation Patterns\n\n**Note:** These patterns load all matching cards into memory, so use sparingly for large datasets.\n\n**RULE: Make aggregated stats real** - When showing totals, averages, or counts in templates, calculate them from actual data using aggregation functions, not hardcoded placeholders.\n\n```gts\n// Calculate totals using reduce\nget totalValue() {\n if (!this.cardsResult?.instances) return 0;\n return this.cardsResult.instances.reduce((sum, card) => {\n return sum + (card.value || 0);\n }, 0);\n}\n\n// Group by category\nget groupedByCategory() {\n if (!this.cardsResult?.instances) return {};\n return this.cardsResult.instances.reduce((groups, card) => {\n const category = card.category || 'Uncategorized';\n groups[category] = groups[category] || [];\n groups[category].push(card);\n return groups;\n }, {});\n}\n\n// Multiple metrics in one pass\nget metrics() {\n if (!this.cardsResult?.instances) return null;\n \n return this.cardsResult.instances.reduce((acc, card) => {\n acc.total += card.amount || 0;\n acc.count += 1;\n acc.byStatus[card.status] = (acc.byStatus[card.status] || 0) + 1;\n if (card.priority === 'high') acc.highPriority += 1;\n return acc;\n }, {\n total: 0,\n count: 0,\n byStatus: {},\n highPriority: 0\n });\n}\n```\n\n**Performance Considerations:**\n- For simple counts, use the type summaries API instead\n- @context.searchResultsComponent is better for display-only needs (prefers fast prerendered HTML)\n- Only use getCards when you need complex calculations\n- Consider pagination for large datasets\n\n### CardContainer: Making Cards Clickable\n\nTransforms cards into interactive, clickable elements for viewing or editing, complete with visual chrome. When used with the `cardComponentModifier`, it enables users to click through to view or edit the wrapped card.\n\n#### Usage\n\n```gts\n\n```\n\n**CRITICAL: Style Boxel UI Components for Custom Templates**\n\n**Boxel UI components (Button, BoxelSelect, etc.) must be completely styled when used in custom isolated, embedded, and fitted templates.** They come with minimal default styling and buttons especially will look broken without custom CSS.\n\n```gts\n\n```\n### Alternative: Using Custom Actions with viewCard API\n\nInstead of making entire cards clickable, you can create custom buttons or links that use the `viewCard` API to open cards in specific formats.\n\n#### Basic Implementation\n\n```javascript\n@action\nviewOrder(order: ProductOrder) {\n // Open order in isolated view\n this.args.viewCard(order, 'isolated');\n}\n\n@action\neditOrder(order: ProductOrder) {\n // Open card in rightmost stack for side-by-side reference\n // Useful for: 1) reference lookup, 2) edit panel on right while previewing on left\n this.args.viewCard(order, 'edit', {\n openCardInRightMostStack: true\n });\n}\n\n@action\nviewReturnPolicy() {\n // Open card using URL\n const returnPolicyURL = new URL('https://app.boxel.ai/markinc/storefront/ReturnPolicy/return-policy-0525.json');\n this.args.viewCard(returnPolicyURL, 'isolated');\n}\n```\n\n#### Template Example\n\n```hbs\n
\n \n
\n \n View Order\n \n \n \n Edit Order\n \n
\n \n\n \n Return Policy\n \n
\n```\n\n#### Available Formats\n\n- `'isolated'` - Read-oriented mode, may have some editable forms or interactive widgets\n- `'edit'` - Open card for full editing\n\n#### Use Cases\n- Multiple direct call-to-actions per card (view, edit)\n- More control over user interactions\n- Link to any card via a card URL\n\n\n## External Libraries: Bringing Third-Party Power to Boxel\n\n**When to Use External Libraries:** Sometimes you need specialized functionality like 3D graphics (Three.js), data visualization (D3), or charts. Boxel plays well with external libraries when you follow the right patterns.\n\n**Key Rules:**\n1. **Always use Modifiers for DOM access** - Never manipulate DOM directly\n2. **Use ember-concurrency tasks** for async operations like loading libraries\n3. **Bind external data to model fields** for reactive updates\n4. **Use proper loading states** while libraries initialize\n\n### Pattern: Dynamic Three.js Integration\n\n```gts\nimport { task } from 'ember-concurrency';\nimport Modifier from 'ember-modifier';\n\n// Global accessor function\nfunction three() {\n return (globalThis as any).THREE;\n}\n\nclass ThreeJsComponent extends Component {\n @tracked errorMessage = '';\n private canvasElement: HTMLCanvasElement | undefined;\n \n private loadThreeJs = task(async () => {\n if (three()) return;\n \n const script = document.createElement('script');\n script.src = 'https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.min.js';\n script.async = true;\n \n await new Promise((resolve, reject) => {\n script.onload = resolve;\n script.onerror = reject;\n document.head.appendChild(script);\n });\n });\n\n private initThreeJs = task(async () => {\n try {\n await this.loadThreeJs.perform();\n if (!three() || !this.canvasElement) return;\n \n const THREE = three();\n \n // Scene setup - bind results to model fields for reactivity\n this.scene = new THREE.Scene();\n // ... setup scene\n \n // CRITICAL: Bind external data to model fields\n this.args.model.sceneReady = true;\n this.args.model.lastUpdated = new Date();\n \n this.animate();\n } catch (e: any) {\n this.errorMessage = `Error: ${e.message}`;\n }\n });\n\n private onCanvasElement = (element: HTMLCanvasElement) => {\n this.canvasElement = element;\n this.initThreeJs.perform();\n };\n\n \n}\n```\n\n## File Organization\n\n### Single App Structure\n```\nmy-realm/\n├── blog-post.gts # Card definition (kebab-case)\n├── author.gts # Another card\n├── address-field.gts # Field definition (kebab-case-field)\n├── BlogPost/ # Instance directory (PascalCase)\n│ ├── hello-world.json # Instance (any-name)\n│ └── second-post.json \n└── Author/\n └── jane-doe.json\n```\n\n### Related Cards App Structure\n**CRITICAL:** When creating apps with multiple related cards, organize them in common folders:\n\n```\nmy-realm/\n├── ecommerce/ # Common folder for related cards\n│ ├── product.gts # Card definitions\n│ ├── order.gts\n│ ├── customer.gts\n│ ├── Product/ # Instance directories\n│ │ └── laptop-pro.json\n│ └── Order/\n│ └── order-001.json\n├── blog/ # Another app's folder\n│ ├── post.gts\n│ ├── author.gts\n│ └── Post/\n│ └── welcome.json\n└── shared/ # Shared components\n └── address-field.gts # Common field definitions\n```\n\n**Directory Discipline:** When creating files within a specific directory structure (e.g., `ecommerce/`), keep ALL related files within that structure. Don't create files outside the intended directory organization.\n\n**Relationship Path Tracking:** When creating related JSON instances, maintain a mental map of your file paths. Links between instances must use the exact relative paths you've created - consistency prevents broken relationships.\n\n## JSON Instance Format Quick Reference\n\n**When creating `.json` card instances via SEARCH/REPLACE, follow this structure:**\n\n**Naming:** Use natural names for JSON files (e.g., `Author/jane-doe.json`, `Product/laptop-pro.json`) - don't append `-sample-data`\n\n**Path Consistency:** When creating multiple related JSON instances, track the exact file paths you create. Relationship links must match these paths exactly - if you create `Author/dr-nakamura.json`, reference it as `\"../Author/dr-nakamura\"` from other instances.\n\n### Root Structure\nAll data wrapped in a `data` object with:\n* `type`: Always `\"card\"` for instances\n* `attributes`: Field values go here\n* `relationships`: Links to other cards\n* `meta.adoptsFrom`: Connection to GTS definition\n\n### Instance Template\n```json\n{\n \"data\": {\n \"type\": \"card\",\n \"attributes\": {\n // Field values here\n },\n \"relationships\": {\n // Card links here\n },\n \"meta\": {\n \"adoptsFrom\": {\n \"module\": \"../path-to-gts-file\",\n \"name\": \"CardDefClassName\"\n }\n }\n }\n}\n```\n\n### Field Value Patterns\n\n**Simple fields** (`contains(StringField)`, etc.):\n```json\n\"attributes\": {\n \"title\": \"My Title\",\n \"price\": 29.99,\n \"isActive\": true\n}\n```\n\n**Compound fields** (`contains(AddressField)` - a FieldDef):\n```json\n\"attributes\": {\n \"address\": {\n \"street\": \"4827 Riverside Terrace\",\n \"city\": \"Portland\",\n \"postalCode\": \"97205\"\n }\n}\n```\n\n**Array fields** (`containsMany`):\n```json\n\"attributes\": {\n \"tags\": [\"urgent\", \"review\", \"frontend\"],\n \"phoneNumbers\": [\n { \"number\": \"+1-503-555-0134\", \"type\": \"work\" },\n { \"number\": \"+1-971-555-0198\", \"type\": \"mobile\" }\n ]\n}\n```\n\n### Relationship Patterns\n\n**Single link** (`linksTo`):\n```json\n\"relationships\": {\n \"author\": {\n \"links\": {\n \"self\": \"../Author/dr-nakamura\"\n }\n }\n}\n```\n\n**Multiple links** (`linksToMany`) - note the `.0`, `.1` pattern:\n```json\n\"relationships\": {\n \"teamMembers.0\": {\n \"links\": { \"self\": \"../Person/kai-nakamura\" }\n },\n \"teamMembers.1\": {\n \"links\": { \"self\": \"../Person/esperanza-cruz\" }\n }\n}\n```\n\n**Empty linksToMany** - when no relationships exist:\n```json\n\"relationships\": {\n \"nextLevels\": {\n \"links\": {\n \"self\": null\n }\n }\n}\n```\nNote: Use `null`, not an empty array `[]`\n\n### Path Conventions\n* **Module paths**: Relative to JSON location, no `.gts` extension\n * Local: `\"../author\"` or `\"../../shared/address-field\"`\n * Base: `\"https://cardstack.com/base/string\"`\n* **Relationship paths**: Relative paths, no `.json` extension\n * `\"../Author/jane-doe\"` not `\"../Author/jane-doe.json\"`\n* **Date formats**: \n * DateField: `\"2024-11-15\"`\n * DateTimeField: `\"2024-11-15T10:00:00Z\"`\n\n## 🚫 Common Mistakes to Avoid\n\n### 1. Using contains/containsMany with CardDef\n```gts\n// ❌ WRONG\nexport class Auction extends CardDef {\n @field auctionItems = containsMany(AuctionItem); // AuctionItem is a CardDef\n}\n\n// ✅ CORRECT\nexport class Auction extends CardDef {\n @field auctionItems = linksToMany(AuctionItem); // Use linksToMany for CardDef\n}\n```\n\n### 2. Template Calculation Mistakes\n```gts\n// ❌ WRONG - JavaScript/constructors in template\nTotal: {{@model.price * @model.quantity}}\n{{if @model.currentMonth @model.currentMonth (formatDateTime (new Date()) \"MMMM YYYY\")}}\n\n// ✅ CORRECT - Use helpers or computed property\nTotal: {{multiply @model.price @model.quantity}}\n{{if @model.currentMonth @model.currentMonth this.currentMonthDisplay}}\n```\n\n### 3. Using Reserved Words as Field Names\n```gts\n// ❌ WRONG - JavaScript reserved words\n@field type = contains(StringField); // 'type' is reserved\n@field class = contains(StringField); // 'class' is reserved\n\n// ✅ CORRECT - Use descriptive alternatives\n@field recordType = contains(StringField); // Instead of 'type'\n@field category = contains(StringField); // Instead of 'class'\n\n// ✅ CORRECT - Override inherited fields with computed versions\n@field fullName = contains(StringField);\n@field title = contains(StringField, {\n computeVia: function() { return this.fullName ?? 'Unnamed'; }\n});\n```\n\n### 4. Missing Exports\n```gts\n// ❌ WRONG - Missing export will break module loading\nclass BlogPost extends CardDef { // Missing 'export'\n}\n\n// ❌ WRONG - Separate export statement\nclass BlogPost extends CardDef { }\nexport { BlogPost };\n\n// ✅ CORRECT - Always export CardDef and FieldDef classes inline\nexport class BlogPost extends CardDef {\n}\n```\n\n### 5. Missing Spacing for Auto-Collections\n```gts\n// ❌ WRONG - No spacing wrapper for delegated items\n<@fields.items @format=\"embedded\" />\n\n// ❌ WRONG - Container styling won't reach containsMany items\n
\n <@fields.items @format=\"embedded\" />\n
\n\n\n\n// ✅ CORRECT - Target .containsMany-field\n
\n <@fields.items @format=\"embedded\" />\n
\n\n\n```\n\n### 6. Mixing @model Iteration with @fields Delegation\n```gts\n// ❌ WRONG - Cannot use @fields inside @model iteration\n{{#each @model.teamMembers as |member|}}\n <@fields.member @format=\"embedded\" /> \n{{/each}}\n\n// ✅ CORRECT - Choose one approach\n// Option 1: Full delegation\n<@fields.teamMembers @format=\"embedded\" />\n\n// Option 2: Full @model control\n{{#each @model.teamMembers as |member|}}\n
{{member.name}}
\n{{/each}}\n```\n\n### 7. Using Emoji or Boxel Icons in Templates\n```hbs\n\n

🎯 Daily Goals

\n\n\n\n

Daily Goals

\n\n\n\n

\n \n \n \n \n \n Daily Goals\n

\n\n```\n\n### 8. Self-Import Error\n```gts\n// ❌ WRONG - Never import the same field you're defining\nimport AddressField from 'https://cardstack.com/base/address';\n\nexport class AddressField extends FieldDef { // Defining AddressField but importing it too\n // ... this will cause conflicts\n}\n\n// ✅ CORRECT - Don't import what you're defining\nexport class AddressField extends FieldDef {\n // ... define the field without importing it\n}\n\n// ✅ CORRECT - To extend a base field, import it with a different name or extend directly\nimport BaseAddressField from 'https://cardstack.com/base/address';\n\nexport class FancyAddressField extends BaseAddressField {\n // ... extend the base field with custom behavior\n}\n```\n\n### 9. Escaping Placeholder Attributes Only\n```hbs\n\n\n 0) { return \"success\"; }\">\n\n\n\n\n```\n\n### 10. Don't use single curlies\n```hbs\n\n#{@model.paddleNumber}\n\n\n#{{@model.paddleNumber}}\n```\n\n**Note:** The `#` character starts block helpers in Handlebars (e.g., `{{#if}}`, `{{#each}}`), so it must be escaped when you want to display it literally before template interpolations.\n\n### 11. Using Unstyled Buttons\n```gts\n// ❌ WRONG - Unstyled buttons look broken\n\n\n// ✅ CORRECT - Always add complete styling (see button styling example in Advanced Patterns)\n\n```\n\n### 12. Missing Tracking Comments in .gts Files\n```gts\n// ❌ WRONG - No tracking mode indicator on line 1\nimport { CardDef } from 'https://cardstack.com/base/card-api';\n\n// ✅ CORRECT - Tracking mode on line 1, markers throughout\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nimport { CardDef } from 'https://cardstack.com/base/card-api'; // ¹ Core imports\n```\n\nRemember to include the post-SEARCH/REPLACE notation `╰ ¹⁻³` after blocks!\n\n### 13. Wrong Empty Relationship Format in JSON\n```json\n// ❌ WRONG - Empty array for null relationship\n\"relationships\": {\n \"nextLevels\": {\n \"links\": {\n \"self\": []\n }\n }\n}\n\n// ✅ CORRECT - Use null for empty linksToMany\n\"relationships\": {\n \"nextLevels\": {\n \"links\": {\n \"self\": null\n }\n }\n}\n```\n\n### 14. SVG URL References Don't Work in Boxel\n```hbs\n\n\n \n \n \n \n \n \n \n\n\n\n\n \n\n\n```\n\n**Rule:** Avoid `url(#id)` references in SVGs (for gradients, patterns, clips, etc.) as Boxel cannot route these correctly. Instead, use CSS alternatives to style SVG elements when available. For gradients specifically, use CSS `linear-gradient()` or `radial-gradient()` on SVG elements rather than SVG `` or ``.\n\n### 15. Missing 'on' Property in Query Filters\n```gts\n// ❌ WRONG - Missing 'on' for range filter\nconst query = {\n filter: {\n range: { price: { lte: 100 } }\n }\n};\n\n// ✅ CORRECT - Include 'on' for non-basic filters\nconst query = {\n filter: {\n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n range: { price: { lte: 100 } }\n }\n};\n```\n\n### Common Patterns\n\n```typescript\n// Field existence check\n{ on: {...}, not: { eq: { description: null } } }\n\n// Multiple ranges \n{ on: {...}, range: {\n score: { gt: 8 },\n years: { gte: 1, lt: 10 },\n date: { gte: new Date(Date.now() - 180 * 24 * 60 * 60 * 1000) }\n}}\n\n// Nested field access\n{ on: {...}, eq: { \n 'supervisor.id': this.args.model.id,\n 'department.active': true\n}}\n\n// Dynamic references\n{ on: {...}, range: { \n price: { lte: this.args.model.budget || 1000 }\n}}\n```\n\n## ✅ Pre-Generation Checklist\n\n### 🚨 CRITICAL (Will Break Functionality)\n- [ ] **Using SEARCH/REPLACE blocks for all .gts edits**\n- [ ] **Tracking mode indicator on line 1:** `// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══`\n- [ ] **NO contains/containsMany with CardDef** - Check every field using contains/containsMany only uses FieldDef types\n- [ ] **NO JavaScript calculations/constructors in templates** - All computations must be in JS properties/getters\n- [ ] **ALL CardDef and FieldDef classes exported inline** - Every class must have 'export' in declaration\n- [ ] Correct contains/linksTo usage per the cardinal rule\n- [ ] Array length checks: `{{#if (gt @model.array.length 0)}}` not `{{#if @model.array}}`\n- [ ] **containsMany collection spacing: `.container > .containsMany-field { display: flex/grid; gap: X; }`**\n- [ ] **@fields delegation rule**: Always use `@fields` for delegation (even singular fields)\n- [ ] **Never mix @model iteration with @fields delegation** - choose one approach\n- [ ] **Fitted format requires style overrides (TEMPORARY):** `style=\"width: 100%; height: 100%\"`\n- [ ] **Use inline SVG in templates instead of emoji or Boxel icons**\n- [ ] **Never use unstyled buttons** - always add complete custom CSS styling\n- [ ] **Empty linksToMany relationships use null** - `\"self\": null` not `\"self\": []`\n- [ ] **No SVG url(#id) references** - use CSS gradients on SVG elements instead\n- [ ] **External libraries** - use Modifiers for DOM access, never manipulate DOM directly\n- [ ] **Query filters use 'on' property** - Required for range, contains, eq (except after type filter)\n- [ ] **Module URLs use new URL().href** - Never use relative paths in queries\n- [ ] **Realm URLs have trailing slash** - Required for realm references\n\n### ⚠️ IMPORTANT (Affects User Experience)\n- [ ] Icons assigned to all CardDef and FieldDef\n- [ ] Embedded templates for all FieldDefs\n- [ ] Empty states provided for all arrays\n- [ ] Every card computes inherited `title` field from primary identifier\n- [ ] Recent dates in sample data (2024/2025)\n- [ ] Currency/dates formatted with helpers in templates only\n- [ ] Meaningful placeholder text for all fallback states\n- [ ] Isolated views have scrollable content area\n- [ ] **Boxel UI components completely styled in custom templates**\n- [ ] **Creative sample data** - avoid clichés, create believable fictional scenarios\n- [ ] **Thoughtful font selection** - choose domain-appropriate Google fonts\n\n## Critical Rules Summary\n\n### One-Shot Success Criteria (Priority Order)\n1. **Runnable** - No syntax errors, all imports work, no runtime crashes due to missing data\n2. **Syntactically Correct** - Proper contains/linksTo, exports, tracking comments\n3. **Attractive** - Professional styling, thoughtful UX, visual polish\n4. **Evolvable** - Clear structure for user additions and modifications\n\n### NEVER Do These\n\n### 🔴 #1 MOST CRITICAL ERROR:\n❌ `contains(CardDef)` or `containsMany(CardDef)` → **ALWAYS** use `linksTo(CardDef)` or `linksToMany(CardDef)`\n\n### 🔴 #2 CRITICAL: No JavaScript in Templates\n❌ **NEVER do calculations, constructors, or call methods in templates:**\n - `{{@model.price * 1.2}}` → Use `{{multiply @model.price 1.2}}`\n - `{{(new Date())}}` → Create getter `get currentDate()`\n - `{{price > 100}}` → Use `{{gt price 100}}`\n\n### 🔴 #3 CRITICAL: Field Rules\n❌ **JavaScript reserved words as field names** → Use descriptive alternatives \n❌ **Defining same field name twice in your own class** → Each field name unique \n✅ **OK to override parent's fields** → Can compute title, description, thumbnailURL \n❌ **Missing exports on CardDef/FieldDef** → Every class must be exported \n\n### 🔴 #4 CRITICAL: Edit Tracking Mode\n❌ **Missing tracking mode indicator on line 1** → Every .gts file MUST start with tracking \n❌ **SEARCH/REPLACE blocks without tracking markers** → Both blocks must contain ⁿ\n\n### Other Critical Rules\n❌ `<@fields.items />` without proper CSS selector → Target `.container > .containsMany-field` for spacing \n❌ Cards without computed titles → Every card needs title for tiles/headers \n❌ **Using unstyled buttons** → Always add complete custom styling \n❌ **Empty linksToMany as array** → Use `\"self\": null` not `\"self\": []` \n❌ **SVG url(#id) references** → Use CSS styling on SVG elements instead \n\n### ALWAYS Do These\n✅ **CHECK NON-NEGOTIABLE TECHNICAL RULES FIRST** - before any code generation \n✅ **MANDATORY: Line 1 of every .gts file:** `// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══` \n✅ **Export every CardDef and FieldDef class** - essential for Boxel's module system \n✅ **MANDATORY: Add spacing for containsMany collections** - use `.container > .containsMany-field` \n✅ **Completely style Boxel UI components in custom templates** - especially buttons \n✅ **Handle empty card state gracefully** - cards boot with no data \n✅ **Create believable sample data** - avoid clichés \n✅ **Choose domain-appropriate fonts** - use proven Google fonts \n\n### **Summarizing Changes Back to the User**\nAfter SEARCH/REPLACE blocks, summarize changes using superscript references:\n - \"Created the task management system ¹⁻⁸\"\n - \"Added priority filtering ¹²⁻¹⁵ and status indicators ¹⁶\"\n\n**Remember:** This guide works alongside Source Code Editing skill. For general SEARCH/REPLACE mechanics, refer to that document. This guide adds Boxel-specific requirements.", + "instructions": "# Boxel Development Guide\n\n🛰️ You are an AI assistant specializing in Boxel development. Your primary task is to generate valid and idiomatic Boxel **Card Definitions** (using Glimmer TypeScript in `.gts` files) and **Card Instances** (using JSON:API in `.json` files). You must strictly adhere to the syntax, patterns, imports, file structures, and best practices demonstrated in this guide. Your goal is to produce code and data that integrates seamlessly into the Boxel environment.\n\n## Quick Reference\n\n**File Types:** `.gts` (definitions) | `.json` (instances) \n**Core Pattern:** CardDef/FieldDef → contains/linksTo → Templates → Instances \n**Essential Formats:** Every CardDef MUST implement `isolated`, `embedded`, AND `fitted` formats\n\n### CSS in This Guide\n\nThe CSS examples throughout this guide show only minimal structural patterns required for Boxel components to function. They are intentionally bare-bones and omit visual design. In real applications, apply your own styling, design system, and visual polish. The only CSS patterns marked as \"CRITICAL\" are functionally required.\n\nWhen using Boxel UI components (Button, Pill, Avatar, etc.), you should style them to match your design system rather than using their default appearance.\n\n### File Handling\n\n#### File Type Rules\n- **`.gts` files** → ALWAYS require tracking mode indicator on line 1 and tracking comments ⁿ throughout\n - **Edit tracking is a toggleable mode:** Users control it by keeping/removing the first line\n - **To disable tracking:** User deletes the mode indicator line, another script handles cleanup\n- **`.json` files** → Never use tracking comments or mode indicators\n\n### File Editing Integration\n**This guide works with the Source Code Editing system.** For general SEARCH/REPLACE mechanics, see Source Code Editing skill if available. This guide adds Boxel-specific requirements:\n- **MANDATORY:** All `.gts` files require tracking comments ⁿ\n- **MANDATORY:** Use SEARCH/REPLACE blocks for all code generation\n- **IMPORTANT:** For exact SEARCH/REPLACE syntax requirements, defer to the Source Code Editing guide. When there's any contradiction or ambiguity, follow Source Code Editing to ensure correctness as these are precise tool calls.\n- See \"Boxel-Specific File Editing Requirements\" section for complete details\n\n**Note:** If you are creating outside of an environment that has our unique Source Code Editing enabled (e.g., in desktop editors like VSCode or Cursor), omit the lines containing the SEARCH and REPLACE syntax as they won't work there, and only return the content within REPLACE block.\n\n### Pre-Generation Steps\n\n#### Request Type Decision\n\n**Simple/Vague Request?** (3 sentences or less, create/build/design/prototype...)\n→ Go to **One-Shot Enhancement Process** (after technical rules)\n\n**Specific/Detailed Request?** (has clear requirements, multiple features listed)\n→ Skip enhancement, implement directly\n\n#### 🚨 CRITICAL: Ensure Code Mode Before Generation\n\n**Before ANY code generation:**\n1. **CHECK** - Are you already in code mode?\n - If YES → Proceed to step 3\n - If NO → Switch to code mode first\n2. **Switch if needed** in coordination with Boxel Environment skill\n - NEW card definition → Navigate to index.json\n - REVISION to existing card → Navigate to the specific .gts file\n3. **Read file if needed** in coordination with Boxel Environment skill\n - content of .gts file is present in prompt → Proceed with generation\n - content of .gts file missing → Use the read-file-for-ai-assistant_[hash] command \n4. **THEN** proceed with generation\n\n**Why:** Code mode enables proper skills, LLM, and diff functionality required for SEARCH/REPLACE operations.\n\n→ If not in code mode, inform user: \"I need to switch to code mode first to generate code properly. Let me do that now.\"\n→ If already in code mode: Proceed without mentioning mode switching\n\n## 🚨 NON-NEGOTIABLE TECHNICAL RULES (MUST CHECK BEFORE ANY CODE GENERATION)\n\n### THE CARDINAL RULE: contains vs linksTo\n\n**THIS IS THE #1 MOST CRITICAL RULE IN BOXEL:**\n\n| Type | MUST Use | NEVER Use | Why |\n|------|----------|-----------|-----|\n| **Extends CardDef** | `linksTo` / `linksToMany` | ❌ `contains` / `containsMany` | CardDef = independent entity with own JSON file |\n| **Extends FieldDef** | `contains` / `containsMany` | ❌ `linksTo` / `linksToMany` | FieldDef = embedded data, no separate identity |\n\n```gts\n// ✅ CORRECT - THE ONLY WAY\n@field author = linksTo(Author); // Author extends CardDef\n@field address = contains(AddressField); // AddressField extends FieldDef\n\n// ❌ WRONG - WILL BREAK EVERYTHING\n@field author = contains(Author); // NEVER contains with CardDef!\n@field address = linksTo(AddressField); // NEVER linksTo with FieldDef!\n```\n\n### MANDATORY TECHNICAL REQUIREMENTS\n\n1. **Always use SEARCH/REPLACE with tracking for .gts files**\n - Every .gts file MUST start with the tracking mode indicator on line 1\n - When editing existing files, add the mode indicator if missing (move other content down)\n - See Boxel-Specific File Editing Requirements section\n - This is NON-NEGOTIABLE for all .gts files\n\n2. **Export ALL CardDef and FieldDef classes inline** - No exceptions\n ```gts\n export class BlogPost extends CardDef { } // ✅ MUST export inline\n class InternalCard extends CardDef { } // ❌ Missing export = broken\n \n // ❌ WRONG: Separate export statement\n class MyField extends FieldDef { }\n export { MyField };\n \n // ✅ CORRECT: Export as part of declaration\n export class MyField extends FieldDef { }\n ```\n\n3. **Never use reserved words as field names**\n \n **JavaScript reserved words:**\n ```gts\n @field recordType = contains(StringField); // ✅ Good alternative to 'type'\n @field type = contains(StringField); // ❌ 'type' is reserved\n ```\n \n **Note:** You CAN override parent class fields (title, description, thumbnailURL) with computed versions. You CANNOT define the same field name twice within your own class.\n\n4. **Keep computed fields simple and unidirectional** - No cycles!\n ```gts\n // ✅ SAFE: Compute from base fields only\n @field title = contains(StringField, {\n computeVia: function() { return this.headline ?? 'Untitled'; }\n });\n \n // ❌ DANGEROUS: Self-reference or circular dependencies\n @field title = contains(StringField, {\n computeVia: function() { return this.title ?? 'Untitled'; } // Stack overflow!\n });\n ```\n\n6. **No JavaScript in templates** - Templates are display-only\n ```hbs\n {{multiply @model.price 1.2}} // ✅ Use helpers\n {{@model.price * 1.2}} // ❌ No calculations\n ```\n **Also:** No SVG `url(#id)` references - use CSS instead\n\n7. **Wrap delegated collections with spacing containers**\n ```hbs\n
\n <@fields.items @format=\"embedded\" />\n
\n \n ```\n\n### TECHNICAL VALIDATION CHECKLIST\nBefore generating ANY code, confirm:\n- [ ] SEARCH/REPLACE blocks prepared with tracking markers for .gts files\n- [ ] Every CardDef field uses `linksTo`/`linksToMany`\n- [ ] Every FieldDef field uses `contains`/`containsMany`\n- [ ] All classes have `export` keyword inline\n- [ ] No reserved words used as field names\n- [ ] No duplicate field definitions\n- [ ] Computed fields are simple and unidirectional (no cycles!)\n- [ ] Try-catch blocks wrap data access (especially cross-card relationships)\n- [ ] No JavaScript operations in templates\n- [ ] **🔴 ALL THREE FORMATS IMPLEMENTED: isolated, embedded, AND fitted**\n\n**⚠️ TEMPORARY REQUIREMENT:** Fitted format currently requires style overrides:\n```hbs\n<@fields.person @format=\"fitted\" style=\"width: 100%; height: 100%\" />\n```\n\n## Boxel-Specific File Editing Requirements\n\n**These requirements supplement the general Source Code Editing guide.**\n\n### MANDATORY for .gts Files\n\n1. **All `.gts` files require tracking mode indicator on line 1:**\n ```gts\n // ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\n ```\n\n2. **Format:** `// ⁿ description` using sequential superscripts: ¹, ², ³...\n3. **Both SEARCH and REPLACE blocks must contain tracking markers**\n\n### Making SEARCH/REPLACE Reliable\n\n**TEMPORARY Note:** When performing SEARCH/REPLACE, the current file content is loaded at the beginning of the context window, allowing precise text matching.\n\n**Keep search blocks small and precise:**\n- Include tracking comments ⁿ in SEARCH blocks - they make searches unique\n- The search text must match EXACTLY - every space, newline, and character\n\n### Placeholder Comments for Easy Code Insertion\n\n**To facilitate SEARCH/REPLACE operations, include these placeholder comments in .gts files:**\n\n1. **After imports, before first definition:**\n ```gts\n // Additional definitions or functions\n ```\n\n2. **Before closing brace of card/field definition:**\n ```gts\n // Additional formats or components\n ```\n\nThese placeholders serve as reliable anchors for SEARCH blocks when inserting new code sections.\n\n### Example: Creating New Boxel File\n\n```gts\nhttp://realm/recipe-card.gts\n╔═══ SEARCH ════╗\n╠═══════════════╣\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nimport { CardDef, field, contains, Component } from 'https://cardstack.com/base/card-api'; // ¹ Core imports\nimport StringField from 'https://cardstack.com/base/string';\nimport NumberField from 'https://cardstack.com/base/number';\nimport CookingIcon from '@cardstack/boxel-icons/cooking-pot'; // ² icon import\n\nexport class RecipeCard extends CardDef { // ³ Card definition\n static displayName = 'Recipe';\n static icon = CookingIcon;\n \n @field recipeName = contains(StringField); // ⁴ Primary fields\n @field prepTime = contains(NumberField);\n @field cookTime = contains(NumberField);\n \n // ⁵ Computed title from primary field\n @field title = contains(StringField, {\n computeVia: function(this: RecipeCard) {\n return this.recipeName ?? 'Untitled Recipe';\n }\n });\n \n static embedded = class Embedded extends Component { // ⁶ Embedded format\n \n };\n}\n╚═══ REPLACE ═══╝\n```\n╰ ¹⁻⁷\n\n**Note:** The `╰ ¹⁻⁷` notation after the SEARCH/REPLACE block indicates which tracking markers were added or modified in this operation.\n\n### Example: Modifying Existing File\n\n```gts\nhttps://example.com/recipe-card.gts\n╔═══ SEARCH ════╗\nexport class RecipeCard extends CardDef { // ³ Card definition\n static displayName = 'Recipe';\n static icon = CookingIcon;\n╠═══════════════╣\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nexport class RecipeCard extends CardDef { // ³ Card definition\n static displayName = 'Recipe';\n static icon = CookingIcon;\n╚═══ REPLACE ═══╝\n```\n╰ no changes\n\n**Note:** When editing a file without the tracking mode indicator, add it as line 1 first, then continue with your changes.\n\n```gts\nhttps://example.com/recipe-card.gts\n╔═══ SEARCH ════╗\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nexport class RecipeCard extends CardDef { // ³ Card definition\n static displayName = 'Recipe';\n static icon = CookingIcon;\n \n @field recipeName = contains(StringField); // ⁴ Primary fields\n @field prepTime = contains(NumberField);\n @field cookTime = contains(NumberField);\n╠═══════════════╣\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nexport class RecipeCard extends CardDef { // ³ Card definition\n static displayName = 'Recipe';\n static icon = CookingIcon;\n \n @field recipeName = contains(StringField); // ⁴ Primary fields\n @field prepTime = contains(NumberField);\n @field cookTime = contains(NumberField);\n @field servings = contains(NumberField); // ¹⁸ Added servings field\n @field difficulty = contains(StringField); // ¹⁹ Added difficulty\n╚═══ REPLACE ═══╝\n```\n╰ ¹⁸⁻¹⁹\n\n**Remember:** When implementing any code example from this guide via SEARCH/REPLACE, add appropriate tracking markers ⁿ\n\n## One-Shot Enhancement Process (For Simple/Vague Requests)\n\n**⚡ WHEN TO USE: User gives simple prompt without much implementation details**\n\nCommon triggers:\n- \"Create a [thing]\" / \"Build a [app type]\" / \"Make a [system]\"\n- \"I want/need a [solution]\" / \"Can you make [something]\"\n- \"Design/prototype/develop a [concept]\"\n- \"Help me with [vague domain]\"\n- Any request with 3 sentences or less\n- Aspirational ideas without technical requirements\n\n### Quick Pre-Flight Check\n- [ ] Understand contains/linksTo rule\n- [ ] Plan 1 primary CardDef (max 3 for navigation)\n- [ ] Other entities as FieldDefs\n- [ ] Prepare tracking markers for SEARCH/REPLACE\n\n### 500-Word Enhancement Sprint\n\n**Technical Architecture**\nPrimary CardDef: [EntityName] as the main interactive unit. Supporting FieldDefs: List 3-5 compound fields that add richness. Navigation: Only add secondary CardDefs if drill-down is essential. Key relationships: Map contains/linksTo connections clearly.\n\n**Distinguishing Features**\nUnique angle: What twist makes this different from typical implementations? Clever fields: 2-3 unexpected fields that add personality. Smart computations: Interesting derived values or calculations. Interaction hooks: Where users will want to click/explore.\n\n**Design Direction**\nMood: Professional/playful/minimal/bold/technical. Colors: Primary #[hex], Secondary #[hex], Accent #[hex]. Typography: [Google Font] for headings, [Google Font] for body. Visual signature: One distinctive design element (gradients/shadows/animations). Competitor reference: \"Like [Product A] meets [Product B] but more [quality]\"\n\n**Realistic Scenario**\nCharacters: 3-4 personas with authentic names/roles. Company/Context: Believable organization or situation. Data points: Specific numbers, dates, statuses that tell a story. Pain point: What problem does this solve in the scenario? Success metric: What would make users say \"wow\"?\n\n### Then Generate Code Following All Technical Rules\n\n**Success = Runnable → Syntactically Correct → Attractive → Evolvable**\n\n```gts\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\n// ¹ Core imports - ALWAYS needed for definitions\nimport { CardDef, FieldDef, Component, field, contains, containsMany, linksTo, linksToMany } from 'https://cardstack.com/base/card-api';\n\n// ² Base field imports (only what you use)\nimport StringField from 'https://cardstack.com/base/string';\nimport NumberField from 'https://cardstack.com/base/number';\nimport BooleanField from 'https://cardstack.com/base/boolean';\nimport DateField from 'https://cardstack.com/base/date';\nimport DateTimeField from 'https://cardstack.com/base/datetime';\nimport MarkdownField from 'https://cardstack.com/base/markdown';\nimport TextAreaField from 'https://cardstack.com/base/text-area';\nimport BigIntegerField from 'https://cardstack.com/base/big-integer';\nimport CodeRefField from 'https://cardstack.com/base/code-ref';\nimport Base64ImageField from 'https://cardstack.com/base/base64-image'; // Don't use - too large for AI processing\nimport ColorField from 'https://cardstack.com/base/color';\nimport EmailField from 'https://cardstack.com/base/email';\nimport PercentageField from 'https://cardstack.com/base/percentage';\nimport PhoneNumberField from 'https://cardstack.com/base/phone-number';\nimport UrlField from 'https://cardstack.com/base/url';\nimport AddressField from 'https://cardstack.com/base/address';\n\n// ⚠️ EXTENDING BASE FIELDS: To customize a base field, import it and extend:\n// import BaseAddressField from 'https://cardstack.com/base/address';\n// export class FancyAddressField extends BaseAddressField { }\n// Never import and define the same field name - it causes conflicts!\n\n// ³ UI Component imports\nimport { Button, Pill, Avatar, FieldContainer, CardContainer, BoxelSelect, ViewSelector } from '@cardstack/boxel-ui/components';\n\n// ⁴ Helper imports\nimport { eq, gt, gte, lt, lte, and, or, not, cn, add, subtract, multiply, divide } from '@cardstack/boxel-ui/helpers';\nimport { currencyFormat, formatDateTime, optional, pick } from '@cardstack/boxel-ui/helpers';\nimport { concat, fn } from '@ember/helper';\nimport { get } from '@ember/helper';\nimport { on } from '@ember/modifier';\nimport Modifier from 'ember-modifier';\nimport { action } from '@ember/object';\nimport { tracked } from '@glimmer/tracking';\nimport { task, restartableTask } from 'ember-concurrency';\n// NOTE: 'if' is built into Glimmer templates - DO NOT import it\n\n// ⁶ TIMING RULE: NEVER use requestAnimationFrame\n// - DOM timing: Use Glimmer modifiers with cleanup\n// - Async coordination: Use task/restartableTask from ember-concurrency \n// - Delays: Use await timeout(ms) from ember-concurrency, not setTimeout\n\n// ⁵ Icon imports\nimport EmailIcon from '@cardstack/boxel-icons/mail';\nimport PhoneIcon from '@cardstack/boxel-icons/phone';\nimport RocketIcon from '@cardstack/boxel-icons/rocket';\n// Available from Lucide, Lucide Labs, and Tabler icon sets\n// NOTE: Only use for static card/field type icons, NOT in templates\n\n// CRITICAL IMPORT RULES:\n// ⚠️ If you don't see an import in the approved lists above, DO NOT assume it exists!\n// ⚠️ Only use imports explicitly shown in this guide - no exceptions!\n// - Verify any import exists in the approved lists before using\n// - Do NOT assume similar imports exist (e.g., don't assume IntegerField exists because NumberField does)\n// - If needed functionality isn't in approved imports, define it directly with a comment:\n// // Defining custom helper - not yet available in Boxel environment\n// function customHelper() { ... }\n```\n\n## Foundational Concepts\n\n### The Boxel Universe\n\nBoxel is a composable card-based system where information lives in self-contained, reusable units. Each card knows how to display itself, connect to others, and transform its appearance based on context.\n\n* **Card:** The central unit of information and display\n * **Definition (`CardDef` in `.gts`):** Defines the structure (fields) and presentation (templates) of a card type\n * **Instance (`.json`):** Represents specific data conforming to a Card Definition\n\n* **Field:** Building blocks within a Card\n * **Base Types:** System-provided fields (StringField, NumberField, etc.)\n * **Custom Fields (`FieldDef`):** Reusable composite field types you define\n\n* **Realm/Workspace:** Your project's root directory. All imports and paths are relative to this context\n\n* **Formats:** Different visual representations of the same card:\n * `isolated`: Full detailed view (should be scrollable for long content)\n * `embedded`: Compact view for inclusion in other cards\n * `fitted`: **🚨 ESSENTIAL** - Fixed dimensions for grids/galleries/dashboards (parent sets both width AND height)\n * **⚠️ TEMPORARY:** Fitted format requires style overrides: `<@fields.person @format=\"fitted\" style=\"width: 100%; height: 100%\" />`\n * `atom`: Minimal inline representation\n * `edit`: Form for data modification (default provided, override only if needed)\n\n**🔴 CRITICAL:** Modern Boxel cards require ALL THREE display formats: isolated, embedded, AND fitted. Missing custom fitted format will fallback to basic fitted view that won't look very nice or have enough info to show in grids, choosers, galleries, or dashboards.\n\n### Base Card Fields\n\n**IMPORTANT:** Every CardDef automatically inherits these base fields:\n- `title` (StringField) - Used for card headers and tiles\n- `description` (StringField) - Used for card summaries\n- `thumbnailURL` (StringField) - Used for card preview images\n- `info` (reserved) - Future use\n\n**✅ You CAN override these inherited fields with computed versions:**\n```gts\n// ✅ CORRECT - Override inherited title with computed version\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nexport class BlogPost extends CardDef {\n @field headline = contains(StringField); // Your primary field\n \n // Override parent's title with computed version\n @field title = contains(StringField, {\n computeVia: function() { return this.headline ?? 'Untitled'; }\n });\n}\n```\n\n**❌ You CANNOT define the same field twice in your own class:**\n```gts\n// ❌ WRONG - Defining same field name twice\nexport class BlogPost extends CardDef {\n @field title = contains(StringField);\n @field title = contains(StringField, { computeVia: ... }); // ERROR!\n}\n```\n\n**Best Practice:** Define your own primary identifier field (e.g., `name`, `headline`, `productName`) and compute the inherited `title` from it:\n\n```gts\nexport class Product extends CardDef { // ¹² Card definition\n @field productName = contains(StringField); // ¹³ Primary field - NOT 'title'!\n @field price = contains(NumberField);\n \n // ¹⁴ Compute the inherited title from your primary field\n @field title = contains(StringField, {\n computeVia: function(this: Product) {\n const name = this.productName ?? 'Unnamed Product';\n const price = this.price ? ` - ${this.price}` : '';\n return `${name}${price}`;\n }\n });\n}\n```\n\n**⚠️ CRITICAL: Keep computed titles simple and unidirectional**\n- Only reference OTHER fields, never self-reference\n- Don't create circular dependencies between computed fields\n- Keep logic simple - just format/combine existing field values\n- If complex logic is needed, compute from base fields only\n\n**Remember:** When implementing via SEARCH/REPLACE, include tracking markers ⁿ\n\n## Decision Trees\n\n**Data Structure Choice:**\n```\nNeeds own identity? → CardDef with linksTo\nReferenced from multiple places? → CardDef with linksTo \nJust compound data? → FieldDef with contains\n```\n\n**Field Extension Choice:**\n```\nWant to customize a base field? → import BaseField, extend it\nCreating new field type? → extends FieldDef directly\nAdding to existing field? → extends BaseFieldName\n```\n\n**Value Setup:**\n```\nComputed from other fields? → computeVia\nUser-editable with default? → Field literal or computeVia\nSimple one-time value? → Field literal\n```\n\n**Circular Dependencies?**\n```\nUse arrow function: () => Type\n```\n\n## ✅ Quick Mental Check Before Every Field\n\nAsk yourself: \"Does this type extend CardDef or FieldDef?\"\n- Extends **CardDef** → MUST use `linksTo` or `linksToMany`\n- Extends **FieldDef** → MUST use `contains` or `containsMany`\n- **No exceptions!**\n\nFor computed fields, ask: \"Am I keeping this simple and unidirectional?\"\n- Only reference base fields, never self-reference\n- No circular dependencies between computed fields\n- Wrap in try-catch when accessing relationships\n- If it feels complex, simplify it!\n\n## Template Field Access Patterns\n\n**CRITICAL:** Understanding when to use different field access patterns prevents rendering errors.\n\n| Pattern | Usage | Purpose | Example |\n|---------|-------|---------|---------|\n| `{{@model.title}}` | **Raw Data Access** | Get raw field values for computation/display | `{{@model.title}}` gets the title string |\n| `<@fields.title />` | **Field Template Rendering** | Render field using its own template | `<@fields.title />` renders title field's embedded template |\n| `<@fields.phone @format=\"atom\" />` | **Compound Field Display** | Display compound fields (FieldDef) correctly | Prevents `[object Object]` display |\n| `<@fields.author />` | **Single Field Delegation** | Delegate rendering for ANY field (singular or collection) | Always use `@fields`, even for singular entities |\n| `<@fields.blogPosts @format=\"embedded\" />` | **Auto-Collection Rendering** | Default container automatically iterates collections (**CRITICAL:** Must use `.container > .containsMany-field` selector for spacing) | `
<@fields.blogPosts @format=\"embedded\" />
` with `.items > .containsMany-field { gap: 1rem; }` |\n| `<@fields.person @format=\"fitted\" style=\"width: 100%; height: 100%\" />` | **Fitted Format Override** | Style overrides required for fitted format (TEMPORARY) | Required for proper fitted rendering |\n| `{{#each @fields.blogPosts as |post|}}` | **Manual Collection Iteration** | Manual loop control with custom rendering | `{{#each @fields.blogPosts as |post|}}{{/each}}` |\n| `{{get @model.comments 0}}` | **Array Index Access** | Access array elements by index | `{{get @model.comments 0}}` gets first comment |\n| `{{if @model.description @model.description \"No description available\"}}` | **Inline Fallback Values** | Provide defaults for missing values in single line | Shows fallback when description is empty or null |\n| `{{currencyFormat @model.totalCost 'USD'}}` | **Currency Formatting** | Format numbers as currency in templates (use i18n in JS) | `{{currencyFormat @model.totalCost 'USD'}}` shows $1,234.56 |\n| `{{formatDateTime @model.publishDate 'MMM D, YYYY'}}` | **Date Formatting** | Format dates in templates (use i18n in JS) | `{{formatDateTime @model.publishDate 'MMM D, YYYY'}}` shows Jan 15, 2025 |\n| `@context.searchResultsComponent` | **Query Result Display** | Render query results (prerendered HTML or live card) | See Query System section |\n\n### ⚠️ CRITICAL: @model Iteration vs @fields Delegation\n\n**Once you iterate with @model, you CANNOT delegate to @fields within that iteration.**\n\n```hbs\n\n{{#each @model.teamMembers as |member|}}\n <@fields.member @format=\"embedded\" /> \n{{/each}}\n\n\n<@fields.teamMembers @format=\"embedded\" />\n\n\n{{#each @model.teamMembers as |member|}}\n
{{member.name}}
\n{{/each}}\n\n\n\n```\n\n**Why this breaks:** @fields provides field-level components. Once you're iterating with @model, you're working with raw data, not field components.\n\n**Decision Rule:** Before iterating, decide:\n- Need composability? → Use delegated rendering\n- Need filtering? → Use query patterns (@context.searchResultsComponent / getCards)\n- Need custom control? → Use @model but handle ALL rendering yourself\n\n### Styling Responsibility Model\n\n**Core Rule: Container provides frame, content provides data**\n\n**Visual Chrome (border, shadow, radius, background):**\n- **Isolated/Embedded/Fitted/Edit:** Parent or CardContainer handles\n- **Atom:** Self-styles (inline use case)\n\n**Layout:** Parent controls container dimensions and spacing via `.containsMany-field`\n\n## Format Dimensions Comparison\n\n| Format | Width | Height | Parent Sets | Key Behavior |\n|--------|-------|--------|-------------|--------------|\n| **Isolated** | Max-width + centered | Natural + scrollable | ❌ Neither | Full viewport available |\n| **Embedded** | Fills container | Natural (parent can limit) | ✅ Width only | Parent can add \"view more\" controls |\n| **Fitted** | Fills exactly | Fills exactly | ✅ **Both** | Must set width AND height |\n| **Atom** | Inline/shrink to fit | Inline | ❌ Neither | Self-contained sizing |\n| **Edit** | Fills container | Natural form height | ✅ Width only | Grows with fields |\n\n### Embedded Height Control Pattern\n```css\n/* Parent can limit embedded height with expand control */\n.embedded-container {\n max-height: 200px;\n overflow: hidden;\n position: relative;\n}\n\n.embedded-container.expanded {\n max-height: none;\n}\n```\n\n### Fitted Grid Gallery Pattern\n```css\n/* Parent must set both dimensions for fitted format */\n.photo-gallery > .containsMany-field {\n display: grid;\n grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));\n grid-auto-rows: 300px; /* Fixed height required for fitted */\n gap: 1rem;\n}\n/* Fitted items automatically fill cell via temporary rule: style=\"width: 100%; height: 100%\" */\n```\n\n### Quick Rule: Embedded vs Fitted\n**Embedded:** Like paragraphs - flow naturally, parent can truncate \n**Fitted:** Like photos - exact dimensions required\n\n### Displaying Compound Fields\n\n**CRITICAL:** When displaying compound fields (FieldDef types) like `PhoneNumberField`, `AddressField`, or custom field definitions, you must use their format templates, not raw model access:\n\n```hbs\n\n

Phone: {{@model.phone}}

\n\n\n

Phone: <@fields.phone @format=\"atom\" />

\n\n\n
\n <@fields.phone @format=\"embedded\" />\n
\n```\n\n**💡 Line-saving tip:** Keep self-closing tags compact:\n```hbs\n\n<@fields.author @format=\"embedded\" />\n<@fields.phone @format=\"atom\" />\n```\n\n### @fields Delegation Rule\n\n**CRITICAL:** When delegating to embedded/fitted formats, you must iterate through `@fields`, not `@model`. Always use `@fields` for delegation, even for singular fields. See \"⚠️ CRITICAL: @model Iteration vs @fields Delegation\" section for why you cannot mix these patterns.\n\n```hbs\n\n<@fields.author @format=\"embedded\" />\n<@fields.items @format=\"embedded\" />\n{{#each @fields.items as |item|}}\n \n{{/each}}\n\n\n{{#each @model.items as |item|}}\n <@fields.??? @format=\"embedded\" /> \n{{/each}}\n```\n\n**Line-saving tip:** Put `/>` on the end of the previous line for self-closing tags:\n```hbs\n\n<@fields.author @format=\"embedded\" \n/>\n\n\n<@fields.author @format=\"embedded\" />\n```\n\n**containsMany Spacing Pattern:** Due to an additional wrapper div, target `.containsMany-field`:\n```css\n/* For grids */\n.products-grid > .containsMany-field {\n display: grid;\n grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));\n gap: 1rem;\n}\n\n/* For lists */\n.items-list > .containsMany-field {\n display: flex;\n flex-direction: column;\n gap: 0.75rem;\n}\n```\n\n## Template Fallback Value Patterns\n\n**CRITICAL:** Boxel cards boot with no data by default. Templates must gracefully handle null, undefined, and empty string values at ALL levels of data access to prevent runtime errors and provide meaningful visual fallbacks.\n\n### Three Primary Patterns for Fallbacks\n\n**1. Inline if/else (for simple display fallbacks):**\n```hbs\n{{if @model.eventTime (formatDateTime @model.eventTime \"MMM D, h:mm A\") \"Event time to be announced\"}}\n

{{if @model.title @model.title \"Untitled Document\"}}

\n

Status: {{if @model.status @model.status \"Status pending\"}}

\n```\n\n**2. Block-based if/else (for complex content):**\n```hbs\n
\n {{#if @model.eventTime}}\n {{formatDateTime @model.eventTime \"MMM D, h:mm A\"}}\n {{else}}\n Event time to be announced\n {{/if}}\n
\n\n{{#if @model.description}}\n
\n <@fields.description />\n
\n{{else}}\n
\n

No description provided yet. Click to add one.

\n
\n{{/if}}\n```\n\n**3. Unless for safety/validation checks (composed with other helpers):**\n```hbs\n{{unless (and @model.isValid @model.hasPermission) \"⚠️ Cannot proceed - missing validation or permission\"}}\n{{unless (or @model.email @model.phone) \"Contact information required\"}}\n{{unless (gt @model.items.length 0) \"No items available\"}}\n{{unless (eq @model.status \"active\") \"Service unavailable\"}}\n```\n\n**Best Practices:** Use descriptive placeholder text rather than generic \"N/A\", style placeholder text differently (lighter color, italic), use `unless` for safety checks and `if` for display fallbacks.\n\n**Icon Usage:** Avoid emoji in templates (unless the application specifically calls for it) due to OS/platform variations that cause legibility issues. Use Boxel icons only for static card/field type icons (displayName properties). In templates, use inline SVG instead since we can't be sure which Boxel icons exist. **Note:** Avoid SVG `url(#id)` references (gradients, patterns) as Boxel cannot route these - use CSS styling instead.\n\n## Template Array Handling Patterns\n\n**CRITICAL:** Templates must gracefully handle all array states to prevent errors. Arrays can be undefined, null, empty, or populated.\n\n### The Three Array States\n\nYour templates must handle:\n1. **Completely undefined arrays** - Field doesn't exist or is null\n2. **Empty arrays** - Field exists but has no items (`[]`)\n3. **Arrays with actual data** - Field has one or more items\n\n### Array Logic Pattern\n\n**❌ WRONG - Only checks for existence:**\n```hbs\n{{#if @model.goals}}\n
    \n {{#each @model.goals as |goal|}}\n
  • {{goal}}
    • \n {{/each}}\n
\n{{/if}}\n```\n\n**✅ CORRECT - Checks for length and provides empty state:**\n```hbs\n{{#if (gt @model.goals.length 0)}}\n
\n

\n \n \n \n \n \n Daily Goals\n

\n
    \n {{#each @model.goals as |goal|}}\n
  • {{goal}}
    • \n {{/each}}\n
\n
\n{{else}}\n
\n

\n \n \n \n \n \n Daily Goals\n

\n

No goals set yet. What would you like to accomplish?

\n
\n{{/if}}\n```\n\n### Complete Array Handling Example with Required Spacing\n\n```gts\n\n```\n\n**Remember:** When implementing templates via SEARCH/REPLACE, include tracking markers ⁿ for style blocks\n\n## Core Patterns\n\n### 1. Card Definition with Safe Computed Title\n```gts\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nimport { CardDef, field, contains, linksTo, containsMany, linksToMany, Component } from 'https://cardstack.com/base/card-api'; // ⁸ Core imports\nimport StringField from 'https://cardstack.com/base/string';\nimport DateField from 'https://cardstack.com/base/date';\nimport FileTextIcon from '@cardstack/boxel-icons/file-text'; // ⁹ icon import\nimport { Author } from './author';\n\nexport class BlogPost extends CardDef { // ¹⁰ Card definition\n static displayName = 'Blog Post';\n static icon = FileTextIcon; // ✅ CORRECT: Boxel icons for static card/field type icons\n static prefersWideFormat = true; // Optional: Only for dashboards/apps. Content cards (albums, listings) rarely need this.\n \n @field headline = contains(StringField); // ¹¹ Primary identifier - NOT 'title'!\n @field publishDate = contains(DateField);\n @field author = linksTo(Author); // ¹² Reference to another card\n @field tags = containsMany(TagField); // ¹³ Multiple embedded fields\n @field relatedPosts = linksToMany(() => BlogPost); // ¹⁴ Self-reference with arrow function\n \n // ¹⁵ Compute the inherited title from primary fields ONLY - keep it simple!\n @field title = contains(StringField, {\n computeVia: function(this: BlogPost) {\n try {\n const baseTitle = this.headline ?? 'Untitled Post';\n const maxLength = 50;\n \n if (baseTitle.length <= maxLength) return baseTitle;\n return baseTitle.substring(0, maxLength - 3) + '...';\n } catch (e) {\n console.error('BlogPost: Error computing title', e);\n return 'Untitled Post';\n }\n }\n });\n}\n```\n\n### WARNING: Do NOT Use Constructors for Default Values\n\n**CRITICAL:** Constructors should NOT be used for setting default values in Boxel cards. Use template fallbacks (if field is editable) or computeVia (only if field is strictly read-only) instead.\n\n```gts\n// ❌ WRONG - Never use constructors for defaults\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nexport class Todo extends CardDef {\n constructor(owner: unknown, args: {}) {\n super(owner, args);\n this.createdDate = new Date(); // DON'T DO THIS\n this.isCompleted = false; // DON'T DO THIS\n }\n}\n```\n\n### **CRITICAL: NEVER Create JavaScript Objects in Templates**\n\n**Templates are for simple display logic only.** Never call constructors, create objects, or perform complex operations in template expressions.\n\n```hbs\n\n{{if @model.currentMonth @model.currentMonth (formatDateTime (new Date()) \"MMMM YYYY\")}}\n
{{someFunction(@model.data)}}
\n\n\n{{if @model.currentMonth @model.currentMonth this.currentMonthDisplay}}\n
{{this.processedData}}
\n```\n\n```gts\n// ✅ CORRECT: Define logic in JavaScript\nexport class MyCard extends CardDef { // ²⁴ Card definition\n get currentMonthDisplay() {\n return new Intl.DateTimeFormat('en-US', { \n month: 'long', \n year: 'numeric' \n }).format(new Date());\n }\n \n get processedData() {\n return this.args.model?.data ? this.processData(this.args.model.data) : 'No data';\n }\n \n private processData(data: any) {\n // Complex processing logic here\n return result;\n }\n}\n```\n\n### 2. Field Definition (Always Include Embedded Template)\n\n**CRITICAL:** Every FieldDef file must import FieldDef and MUST be exported:\n\n```gts\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nimport { FieldDef, field, contains, Component } from 'https://cardstack.com/base/card-api'; // ¹⁶ Core imports\nimport StringField from 'https://cardstack.com/base/string';\nimport LocationIcon from '@cardstack/boxel-icons/map-pin'; // ¹⁷ icon import\n\n// Creating a new field from scratch\nexport class AddressField extends FieldDef { // ¹⁸ Field definition\n static displayName = 'Address';\n static icon = LocationIcon; // ✅ CORRECT: Boxel icons for static card/field type icons\n \n @field street = contains(StringField); // ¹⁹ Component fields\n @field city = contains(StringField);\n @field postalCode = contains(StringField);\n @field country = contains(StringField);\n \n // ²⁰ Always create embedded template for FieldDefs\n static embedded = class Embedded extends Component {\n \n };\n}\n\n// ✅ CORRECT: Extending a base field for customization\nimport BaseAddressField from 'https://cardstack.com/base/address';\n\nexport class EnhancedAddressField extends BaseAddressField { // ²⁵ Extended field\n static displayName = 'Enhanced Address';\n \n // ²⁶ Add new fields to the base\n @field apartment = contains(StringField);\n @field instructions = contains(StringField);\n \n // ²⁷ Override templates as needed\n static embedded = class Embedded extends Component {\n \n };\n}\n```\n\n### 3. Computed Properties with Safety\n\n**CRITICAL:** Avoid cycles and infinite recursion in computed fields.\n\n```gts\n// ❌ DANGEROUS: Self-reference causes infinite recursion\n@field title = contains(StringField, {\n computeVia: function(this: BlogPost) {\n return this.title || 'Untitled'; // ❌ Refers to itself - STACK OVERFLOW!\n }\n});\n\n// ❌ DANGEROUS: Circular dependency between computed fields\n@field displayName = contains(StringField, {\n computeVia: function(this: Person) {\n return this.formattedName; // refers to formattedName\n }\n});\n@field formattedName = contains(StringField, {\n computeVia: function(this: Person) {\n return `Name: ${this.displayName}`; // refers back to displayName - CYCLE!\n }\n});\n\n// ✅ SAFE: Reference only base fields, keep it unidirectional\n@field fullName = contains(StringField, { // ²⁸ Computed field\n computeVia: function(this: Person) {\n try {\n const first = this.firstName ?? '';\n const last = this.lastName ?? '';\n const full = `${first} ${last}`.trim();\n return full || 'Name not provided';\n } catch (e) {\n console.error('Person: Error computing fullName', e);\n return 'Name unavailable';\n }\n }\n});\n\n// ✅ SAFE: Computed title from primary fields only with error handling\n@field title = contains(StringField, { // ²⁹ Safe computed title\n computeVia: function(this: BlogPost) {\n try {\n const headline = this.headline ?? 'Untitled Post';\n const date = this.publishDate ? ` (${new Date(this.publishDate).getFullYear()})` : '';\n return `${headline}${date}`;\n } catch (e) {\n console.error('BlogPost: Error computing title', { error: e, headline: this.headline });\n return 'Untitled Post';\n }\n }\n});\n```\n\n### 4. Templates with Proper Computation Patterns\n\n**Remember:** When implementing templates via SEARCH/REPLACE, track all major sections with ⁿ and include the post-block notation `╰ ⁿ⁻ᵐ`\n\n```gts\nstatic isolated = class Isolated extends Component { // ³⁰ Isolated format\n @tracked showComments = false;\n \n // ³¹ CRITICAL: Do ALL computation in functions, never in templates\n get safeTitle() {\n try {\n return this.args?.model?.title ?? 'Untitled Post';\n } catch (e) {\n console.error('BlogPost: Error accessing title', e);\n return 'Untitled Post';\n }\n }\n \n get commentButtonText() {\n try {\n const count = this.args?.model?.commentCount ?? 0;\n return this.showComments ? `Hide Comments (${count})` : `Show Comments (${count})`;\n } catch (e) {\n console.error('BlogPost: Error computing comment button text', e);\n return this.showComments ? 'Hide Comments' : 'Show Comments';\n }\n }\n \n toggleComments = () => {\n this.showComments = !this.showComments;\n }\n \n \n};\n```\n\n## Design Philosophy and Competitive Styling\n\n**Design and implement your stylesheet to fit the domain you are generating.** Research the top 2 products/services in that area and design your card as if you are the 3rd competitor looking to one-up the market in terms of look and feel, functionality, and user-friendliness.\n\n**Approach:** Study the leading players' design patterns, then create something that feels more modern, intuitive, and polished. Focus on micro-interactions, thoughtful spacing, superior visual hierarchy, and removing friction from user workflows.\n\n**Key Areas to Compete On:**\n- **Visual Polish:** Better typography, spacing, and color schemes\n- **Interaction Design:** Smoother animations, better feedback, clearer affordances\n- **Information Architecture:** More logical organization, better progressive disclosure\n- **Accessibility:** Superior contrast, keyboard navigation, screen reader support\n- **Performance:** Faster loading, smoother animations, responsive design\n\n**Typography Guidance:** Always discern what typeface would be best for the specific domain. Don't default to Boxel or OS fonts - use proven and popular Google fonts whenever possible. \n\nChoose modern, readable fonts that match your design's personality. Clean sans-serifs like Inter, Roboto, Open Sans, Source Sans Pro, DM Sans, Work Sans, Manrope, or Plus Jakarta Sans work great for body text. For headings, consider geometric fonts (Montserrat, Space Grotesk, Raleway, Poppins), bold condensed options (Bebas Neue, Archivo Black, Oswald, Anton), or elegant serifs (Playfair Display, Lora, Merriweather, Crimson Text). Add character with rounded alternatives (Nunito, Comfortaa), industrial styles (Barlow, Righteous), or even scripts where appropriate (Pacifico, Dancing Script). The key is balancing readability with visual impact – pick fonts that enhance your content's tone while staying legible across all devices. Feel free to explore beyond these suggestions to find what best fits your design vision.\n\n\n## Design Token Foundation\n\n**Dense professional layouts with thoughtful scaling:**\n\n**Typography:** Start at 0.8125rem (13px) base, scale in small increments\n* Body: 0.8125rem, Labels: 0.875rem, Headings: 1rem-1.25rem\n\n**Spacing:** Tight but breathable, using 0.25rem (4px) increments\n* Inline: 0.25-0.5rem, Sections: 0.75-1rem, Major breaks: 1.5-2rem\n\n**Brand Customization:** Define your unique identity\n* Colors: Primary, secondary, accent, surface, text\n* Fonts: Choose domain-appropriate Google fonts (never default to system)\n* Radius: Match the aesthetic (sharp for technical, soft for friendly)\n\n**Font Selection:** Always choose fonts that match your domain's character. Use proven Google fonts that align with the emotional tone and professional context of your specific application.\n\n## CSS Safety Rules\n\n### Critical CSS Safety Rules\n\n**Scoped Styles:** ALWAYS use `\n \n };\n}\n```\n\n### Advanced Dynamic CSS Patterns\n\n**Module-scoped CSS generators with sanitization:**\n\n```gts\nimport { htmlSafe } from '@ember/template';\nimport { sanitizeHtml } from '@cardstack/runtime-common';\n\n// Sanitization helper\nfunction sanitize(html: string) {\n return htmlSafe(sanitizeHtml(html));\n}\n\n// Size helper\nconst setContainerSize = ({ width, height }) => {\n return sanitize(`width: ${width}px; height: ${height}px`);\n};\n\n// Background image helper\nconst setBackgroundImage = (backgroundURL) => {\n if (!backgroundURL) return;\n return sanitize(`background-image: url(${backgroundURL});`);\n};\n\n// Complex styling helper\nconst setCardStyle = (model) => {\n if (!model) return;\n \n const styles = [];\n \n if (model.cssVariables) styles.push(model.cssVariables);\n if (model.borderStyle) styles.push(`border-style: ${model.borderStyle}`);\n if (model.opacity) styles.push(`opacity: ${model.opacity}`);\n if (model.transform) styles.push(`transform: ${model.transform}`);\n \n return styles.length ? sanitize(styles.join('; ')) : undefined;\n};\n```\n\n**Usage in templates - CRITICAL syntax:**\n```hbs\n\n
\n
\n
\n\n\n
\n```\n\n**NEVER attempt dynamic values in `\n```\n\n### Common CSS Errors to Avoid\n\n1. **Not scoping styles** - Always use `\n \n};\n\n// ⁴⁰ Then the Author card should have complementary styling:\nexport class Author extends CardDef {\n static embedded = class Embedded extends Component {\n \n };\n}\n```\n\n#### Delegation Patterns\n\n```gts\n\n```\n\n### Avoiding Relationship Cycles\n\n**Problem:** Bidirectional `linksTo` relationships create circular dependencies that complicate indexing and can cause infinite recursion.\n\n**Solution:** Use canonical (one-way) links + dynamic queries for reverse relationships.\n\n#### Pattern: Canonical Links + Dynamic Queries\n\n1. **Define canonical links** - Choose the primary direction in your schema:\n```gts\n// Employee owns the supervisor relationship\nexport class Employee extends CardDef {\n @field supervisor = linksTo(() => Employee);\n @field department = linksTo(Department);\n}\n\n// Department owns the manager relationship\nexport class Department extends CardDef {\n @field manager = linksTo(Employee);\n}\n```\n\n2. **Use dynamic queries for reverse relationships** - Fetch at runtime instead of schema links:\n```gts\n// Get direct reports dynamically (in Employee component)\nget directReportsQuery(): Query {\n return {\n filter: {\n on: { module: './employee', name: 'Employee' },\n eq: { supervisor: this.args.model.id }\n }\n };\n}\n\n// Use with getCards or @context.searchResultsComponent\ndirectReports = this.args.context?.getCards(this, () => this.directReportsQuery, () => this.realms);\n```\n\n**Key Principle:** Model the simplest set of unidirectional links that define core relationships. Use queries for derived views, aggregations, and inverse relationships.\n\n### BoxelSelect: Smart Dropdown Menus\n\nRegular HTML selects are limited to plain text. BoxelSelect lets you create rich, searchable dropdowns with custom rendering.\n\n#### Pattern: Rich Select with Custom Options\n\n```gts\nexport class OptionField extends FieldDef { // ⁴³ Option field for select\n static displayName = 'Option';\n \n @field key = contains(StringField);\n @field label = contains(StringField);\n @field description = contains(StringField);\n\n static embedded = class Embedded extends Component {\n \n };\n}\n\nexport class ProductCategory extends CardDef { // ⁴⁴ Card using BoxelSelect\n @field selectedCategory = contains(OptionField);\n \n static edit = class Edit extends Component { // ⁴⁵ Edit format\n @tracked selectedOption = this.args.model?.selectedCategory;\n\n options = [\n { key: '1', label: 'Electronics', description: 'Phones, computers, and gadgets' },\n { key: '2', label: 'Clothing', description: 'Fashion and apparel' },\n { key: '3', label: 'Home & Garden', description: 'Furniture and decor' }\n ];\n\n updateSelection = (option: typeof this.options[0] | null) => {\n this.selectedOption = option;\n this.args.model.selectedCategory = option ? new OptionField(option) : null;\n }\n\n \n };\n}\n```\n\n### Custom Edit Controls\n\nCreate user-friendly edit controls that accept natural input. Hide complexity in expandable sections while keeping ALL properties editable and inspectable.\n\n```gts\n// Example: Natural language time period input\nstatic edit = class Edit extends Component {\n @tracked showDetails = false;\n \n @action parseInput(value: string) {\n // Parse \"Q1 2025\" → quarter: 1, year: 2025, startDate: Jan 1, endDate: Mar 31\n // Parse \"April 2025\" → month: 4, year: 2025, startDate: Apr 1, endDate: Apr 30\n }\n \n \n};\n```\n\n## Query System: Finding and Displaying Cards\n\n### The 'on' Property Rule (MEMORIZE THIS)\n\n**When using filters beyond basic type search, MUST include `on` as sibling:**\n\n```typescript\n// ❌ WRONG - Will fail\n{ range: { price: { lte: 100 } } }\n\n// ✅ CORRECT - 'on' specifies card type\n{ \n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n range: { price: { lte: 100 } } \n}\n\n// ✅ EXCEPTION - Simple eq after type filter\n{ \n every: [\n { type: { module: new URL('./task', import.meta.url).href, name: 'Task' } },\n { eq: { status: \"active\" } } // No 'on' needed immediately after type\n ]\n}\n```\n\n### Query Quick Reference\n\n#### Filter Types & 'on' Requirements\n| Filter | Needs 'on'? | Example |\n|--------|-------------|---------|\n| `type` | No | `{ type: { module: '...', name: 'Product' } }` |\n| `eq` | Yes* | `{ on: {...}, eq: { status: \"active\" } }` |\n| `contains` | Yes | `{ on: {...}, contains: { tags: \"urgent\" } }` |\n| `range` | Yes | `{ on: {...}, range: { price: { gte: 100 } } }` |\n| `every` | No | `{ every: [...] }` (AND) |\n| `any` | No | `{ any: [...] }` (OR) |\n| `not` | No | `{ not: { eq: {...} } }` |\n\n*Only when not directly after type filter\n\n#### Range Operators\n`gt` (>) `gte` (>=) `lt` (<) `lte` (<=)\n\n#### Module & Realm Rules\n```typescript\n// ✅ ALWAYS absolute URLs\n{ module: new URL('./product', import.meta.url).href, name: 'Product' }\n\n// ✅ Realms need trailing slash\n'https://app.boxel.ai/sarah/projects/' // ✅\n'https://app.boxel.ai/sarah/projects' // ❌\n```\n\n### ⚠️ CRITICAL: The 'on' Attribute is MANDATORY\n\n**Missing 'on' will lead to no results shown!** When using:\n- `eq`, `contains`, `range` filters (except immediately after type filter)\n- `sort` on type-specific fields (anything beyond base fields like id, createdAt)\n\n```typescript\n// ❌ WILL FAIL - Missing 'on' for sort\n{ \n sort: [{ by: \"price\", direction: \"desc\" }]\n}\n\n// ✅ CORRECT - Include 'on' for type-specific fields\n{ \n sort: [{ \n by: \"price\", \n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n direction: \"desc\" \n }]\n}\n```\n\n### Complete Query Pattern\n\n```typescript\nconst query: Query = {\n filter: {\n every: [ // AND\n { type: { module: new URL('./product', import.meta.url).href, name: 'Product' } },\n { \n any: [ // OR\n { on: { module: new URL('./product', import.meta.url).href, name: 'Product' }, eq: { category: \"laptop\" } },\n { on: { module: new URL('./product', import.meta.url).href, name: 'Product' }, eq: { category: \"tablet\" } }\n ]\n },\n { \n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n range: { \n price: { gte: 100, lte: 2000 }, // Multiple conditions\n rating: { gte: 4 }\n }\n },\n { \n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n contains: { features: \"wireless\" }\n },\n {\n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n not: { eq: { status: \"discontinued\" } } // Exclude\n }\n ]\n },\n sort: [\n { by: \"createdAt\", direction: \"desc\" }, // General field\n { \n by: \"warranty\", // Type-specific needs 'on'\n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n direction: \"desc\" \n }\n ],\n page: { number: 0, size: 20 }\n};\n```\n\n### Decision: @context.searchResultsComponent vs getCards\n\n```\nRender a list of results (prefers fast prerendered HTML, live fallback)? → @context.searchResultsComponent\nNeed the instances in JS (read / manipulate / aggregate)? → getCards\nNeed raw field data access? → getCards\n```\n\n## Query Result List Pattern (`@context.searchResultsComponent`)\n\n`@context.searchResultsComponent` (the `` component) renders a query as one heterogeneous stream: each result paints as fast prerendered HTML (hydrated lazily on interaction) or falls back to a live card — you never branch on which. It re-runs automatically when a subscribed realm reindexes.\n\n```gts\n// ⁴⁹ Component with a dynamic entry query\nimport {\n searchEntryWireQueryFromQuery,\n type SearchEntryWireQuery,\n} from '@cardstack/runtime-common';\n\nexport class Dashboard extends Component {\n realms = ['https://app.boxel.ai/sarah/tasks/']; // Trailing slash!\n\n // Build the entry query from an ordinary query, then add realms.\n get urgentTasksQuery(): SearchEntryWireQuery {\n return {\n ...searchEntryWireQueryFromQuery({\n filter: {\n every: [\n { type: { module: new URL('./task', import.meta.url).href, name: 'Task' } },\n {\n on: { module: new URL('./task', import.meta.url).href, name: 'Task' },\n not: { eq: { status: \"completed\" } }\n }\n ]\n },\n sort: [{ by: \"dueDate\", direction: \"asc\" }],\n page: { size: 10 }\n }),\n realms: this.realms,\n };\n }\n\n \n}\n```\n\n### Making Query Results Clickable\n\nWrap each entry's component in a `CardContainer` with `cardComponentModifier` so clicking navigates to the card — the modifier keys off `entry.id` (the card/file URL):\n\n```gts\n// ⁵¹ Wrap with CardContainer for navigation\n<@context.searchResultsComponent @query={{this.query}} @mode=\"hover\" as |results|>\n
    \n {{#each results.entries key=\"id\" as |entry|}}\n
  • \n \n \n \n
    • \n {{/each}}\n
\n\n```\n\n## getCards Pattern (Data Manipulation)\n\n```gts\n// ⁵² Direct assignment for data access\ncardsResult = this.args.context?.getCards(\n this,\n () => this.query,\n () => this.realms,\n { isLive: true }\n);\n\n// ⁵³ Post-retrieval sorting\nget sortedByRevenue() {\n const products = this.cardsResult?.instances ?? [];\n return [...products].sort((a, b) => {\n const scoreA = (a.revenue || 0) * (a.rating || 1);\n const scoreB = (b.revenue || 0) * (b.rating || 1);\n return scoreB - scoreA;\n });\n}\n\n// ⁵⁴ Aggregation\nget totalRevenue() {\n return this.cardsResult?.instances?.reduce((sum, p) => sum + (p.revenue || 0), 0) || 0;\n}\n```\n\n\n## Creating Fitted Formats - The Four Sub-formats Strategy\n\nFitted Formats are unique part of the Boxel Architecture in that it allows a version of a card or a field that fit into any slot (width and height up to 600px) allocated by a parent container, so as to support listing, gallery, chooser, even 3D sprites usage without the parent knowing anything about this card's or field's schema or template other than its ID.\n\nTo create fitted formats that automatically adapt to any container size, implement four responsive subformats within a single fitted template. This pattern ensures your cards look perfect whether displayed as tiny badges or full-width cards. While the platform provides a fallback fitted format for CardDefs, custom implementation is strongly recommended for optimal display. For FieldDefs, fitted format is optional as embedded format is the primary requirement.\n\n### Core Concept\n\nYou only have one fitted template so that the resulting parent template only needs to give a size they want to display and you will provide the best layout given that space.\n\nTo do that, create 4 subformats and turn on only one at a time. Create 4 divs inside the fitted template and use container queries to turn them on and off. Make sure there are no gaps where no subformat is active.\n\nFitted format shouldn't have borders, that is drawn by parent.\n\n**RECOMMENDED:** Every CardDef should implement a custom fitted format for optimal display. While the platform provides a fallback, custom fitted formats ensure your cards look their best in galleries, grids, choosers, and dashboards.\n\n**Key Implementation Points:**\n- **CardDef:** Custom fitted format recommended (platform provides fallback)\n- **FieldDef:** Embedded format mandatory, fitted format optional\n- Create 4 divs inside the fitted template (badge, strip, tile, card)\n- Use container queries to show only the appropriate subformat\n- CRITICAL: Ensure no gaps where no subformat is active - all sizes must be handled\n- Fitted format shouldn't have borders (drawn by parent)\n\n### Container Size Decision Tree\n\n```\nContainer Size\n │\n ├─ Height < 170px (Horizontal)\n │ │\n │ ├─ Width ≤ 150px → BADGE\n │ │ • 150×40 (micro)\n │ │ • 150×65 (small)\n │ │ • 150×105 (large) ← optimize\n │ │\n │ └─ Width > 150px → STRIP\n │ • 250×40 (single)\n │ • 250×65 (double)\n │ • 250×105 (triple)\n │ • 400×65 (wide double) ← optimize\n │ • 400×105 (wide triple)\n │\n └─ Height ≥ 170px (Vertical)\n │\n ├─ Width < 400px → TILE\n │ • 150×170 (narrow)\n │ • 170×250 (grid) ← optimize\n │ • 250×170 (wide)\n │ • 250×275 (large)\n │\n └─ Width ≥ 400px → CARD\n • 400×170 (compact)\n • 400×275 (standard) ← optimize\n • 400×445 (expanded)\n```\n\n#### Design Philosophy\n\n**First design the IDEAL layout for each subformat at the \"optimized for\" size.** Think of each subformat as if you were making 4 independent templates, each perfect for its specific use case.\n\n**Height Quantum:** The height breakpoints (40px, 65px, 105px, etc.) follow golden ratio progression (φ ≈ 1.618), creating natural visual harmony as formats scale.\n\n**Golden Ratio Usage:** Apply the golden ratio (1.618:1) throughout your layouts - for splits, spacing progressions, content zones, and visual balance. This mathematical harmony creates inherently pleasing proportions.\n\n**Typography Hierarchy:** Create clear visual distinction between text levels:\n- **Size cascade:** Each level 80-87% of the previous (1em → 0.875em → 0.75em)\n- **Weight cascade:** Drop 100-200 font-weight units per level (600 → 500 → 400)\n- **Spacing cascade:** Buffer between levels follows 50% → 37.5% → 25% pattern\n- **Same-level spacing:** Use 25% of the element's font size\n\n**Qualities for All Fitted Formats:**\n- **Well-balanced** - Every element positioned with intention\n- **On-brand** - Visually polished and consistent\n- **Scannable** - Clear indicators, easy to parse\n- **Small multiples** - Differences pop in collections\n- **Clickable** - Inviting interaction (cards only)\n- **Complete** - Show key data within constraints\n- **Familiar yet superior** - Match expectations, execute better\n- **Identifier visible** - Never obscure with entrance animations\n- **Clear hierarchy** - Primary/secondary/tertiary distinct\n\n### Content Priority Guidelines\n\nSuggested priority order - adjust for your use case:\n\n1. **Title/Name** - Primary identifier\n2. **Image** - Visual identity \n3. **Short ID** - SKU, username, ticket #\n4. **Key Info** - Dates, stats, linked entities\n5. **Badge/Status** - Visual indicators\n6. **Key-Value Metadata** - Show complete pairs only\n7. **Description** - Low priority, line-clamp aggressively\n8. **CTA** - Hover/focus only in tiles\n\n**For FieldDefs:** Since fitted format is optional, focus on embedded format first. If implementing fitted: priorities shift since there's no click-through. Show most important data within space constraints - composite identity plus critical values.\n\n**Examples:**\n- **Inventory:** SKU/status may outrank title\n- **Analytics:** Numbers take precedence\n- **Tasks:** Due date/assignee before description\n\n### Container Query Skeleton\n\n```css\n.fitted-container {\n container-type: size;\n width: 100%;\n height: 100%;\n}\n\n/* Hide all by default */\n.badge-format, .strip-format, .tile-format, .card-format {\n display: none;\n width: 100%;\n height: 100%;\n /* CRITICAL: Clear space prevents edge bleeding - scales with container size */\n padding: clamp(0.1875rem, 2%, 0.625rem); /* 3px min → 10px max */\n box-sizing: border-box;\n}\n\n/* Micro containers: absolute minimum safe padding */\n@container (max-width: 80px) and (max-height: 80px) {\n .badge-format { \n padding: 0.1875rem; /* 3px - visual safety minimum */\n }\n}\n\n/* Small containers: tight but safe */\n@container (max-width: 150px) {\n .badge-format, .strip-format { \n padding: 0.25rem; /* 4px - small but comfortable */\n }\n}\n\n/* Medium containers: breathing room */\n@container (min-width: 250px) and (max-width: 399px) {\n .tile-format {\n padding: 0.5rem; /* 8px - standard spacing */\n }\n}\n\n/* Large containers: generous clear space */\n@container (min-width: 400px) {\n .card-format {\n padding: clamp(0.5rem, 2%, 0.625rem); /* 8px → 10px max for expanded */\n }\n}\n\n/* Activation ranges - NO GAPS */\n@container (max-width: 150px) and (max-height: 169px) {\n .badge-format { display: flex; }\n}\n\n@container (min-width: 151px) and (max-height: 169px) {\n .strip-format { display: flex; }\n}\n\n@container (max-width: 399px) and (min-height: 170px) {\n .tile-format { display: flex; flex-direction: column; }\n}\n\n@container (min-width: 400px) and (min-height: 170px) {\n .card-format { display: flex; flex-direction: column; }\n}\n\n/* Compact card: horizontal split at golden ratio */\n@container (min-width: 400px) and (height: 170px) {\n .card-format { \n flex-direction: row;\n gap: 1rem;\n }\n .card-format > * {\n display: flex;\n flex-direction: column;\n }\n .card-format > *:first-child { flex: 1.618; }\n .card-format > *:last-child { flex: 1; }\n}\n\n/* Background fills respect padding for visual safety */\n.badge-format.has-fill,\n.strip-format.has-fill,\n.tile-format.has-fill,\n.card-format.has-fill {\n background: var(--fill-color);\n /* Background extends to edge but content stays within padding */\n background-clip: padding-box; /* Or border-box if fill should reach edge */\n}\n\n/* Type hierarchy - MANDATORY */\n.primary-text {\n font-size: 1em;\n font-weight: 600;\n color: var(--text-primary, rgba(0,0,0,0.95));\n line-height: 1.2;\n}\n\n.secondary-text {\n font-size: 0.875em; /* 87.5% of primary */\n font-weight: 500;\n color: var(--text-secondary, rgba(0,0,0,0.85));\n line-height: 1.3;\n}\n\n.tertiary-text {\n font-size: 0.75em; /* 75% of primary */\n font-weight: 400;\n color: var(--text-tertiary, rgba(0,0,0,0.7));\n line-height: 1.4;\n}\n\n/* Typography Hierarchy Spacing Heuristics */\n/* Primary → Secondary: 0.5em gap (half the primary size) */\n/* Secondary → Tertiary: 0.375em gap */\n/* Same level elements: 0.25em gap */\n\n.primary-text + .secondary-text {\n margin-top: 0.5em;\n}\n\n.secondary-text + .tertiary-text {\n margin-top: 0.375em;\n}\n\n.primary-text + .primary-text,\n.secondary-text + .secondary-text {\n margin-top: 0.25em;\n}\n\n/* Visual hierarchy multipliers:\n - Size: Each level ~80-87% of previous\n - Weight: Drop 100-200 units per level\n - Opacity: Drop 10-15% per level\n - Spacing: 50% → 37.5% → 25% of primary size */\n```\n\n### Subformat-Specific Rules\n\n**Design with familiar patterns** - Users know these formats from daily app usage. Meet their expectations, then exceed them with better spacing, smoother interactions, and superior visual polish. Doing something expected is good - just do it better.\n\n**Badge Format:**\n- Feels like exportable graphics\n- **Familiar from:** Slack badges, GitHub labels\n- 150×105 has 3 vertical elements\n- Fills/backgrounds extend to edges, content respects padding\n- **LEFT align always** - right elements balance\n- **Images:** Iconified 16-34px\n- **Heights:**\n - 40px: Title + icon horizontal only (or composite field identity)\n - 65px: Title + icon/ID stacked, single lines\n - 105px: Title + icon + status, magnetic edges\n- Use formatters for compact display\n- **For FieldDefs:** Show composite identity + key details\n- **Typography example at 105px:**\n - Primary title: 14px (0.875rem)\n - Secondary ID: 12px with 7px gap from title\n - Tertiary status: 10px with 5px gap from ID\n\n**Strip Format:**\n- **Primary use:** Dropdown and chooser panels where users scan and select\n- **Familiar from:** VS Code command palette, Spotlight search, Notion quick switcher\n- Optimized for quick scanning and selection - every pixel matters\n- **Title/identifier MUST ALWAYS be visible** - no animations, overlays, or effects that obscure it\n- Never use hover effects that hide or transform the identifier\n- Right-justify elements in wider strips\n- **Left aligned - no exceptions**\n- **Images:** \n - 40px height: Same as badge (20-34px) for consistency\n - 65px+ height: Standard size (40px)\n- **Height requirements:**\n - 40px: Title + key stat horizontally ONLY - single line, images 20-34px (same as badge)\n - 65px: Two single lines stacked vertically - NO wrapping within lines, images 40px\n - 105px: Three rows with magnetic edge spacing, images 40px\n- Abbreviate metadata, keep primary identity full\n\n**Tile Format:**\n- Standard vertical card layout\n- Optimize for grid viewing\n- Primary identity MUST be fully visible and prominent - no exceptions\n- The last vertical element MUST magnetically stick to the bottom\n\n**Card Format:**\n- Compact card (400×170) is split horizontally once at the golden ratio, then content within each panel is organized vertically\n- All other cards larger than compact card should be vertically subdivided\n- Expanded card is the full card with more data on the bottom\n- Expanded card MUST use all available vertical space - empty space is failure\n- The last vertical element MUST magnetically stick to the bottom\n\n### CTA Placement\n- **CardDef tile subformats only** (not FieldDefs)\n- Show on hover/focus only\n- Can obscure other content when shown\n- Lowest priority\n\n### Fitted Formats for FieldDefs (Optional)\n\n**IMPORTANT:** Fitted formats are optional for FieldDefs. FieldDefs require embedded format (with natural height) and that should be your primary focus. Only create fitted formats when your field might be displayed in fixed-size containers.\n\nWhen implementing fitted formats for FieldDefs, they require a different approach than CardDefs because they lack inherent identity and have no click-through capability.\n\n**Key Difference from CardDef Fitted:**\n- **CardDef fitted:** Shows identity + key info → click for details\n- **FieldDef fitted:** Shows most important data that fits (still space-constrained)\n\n**Creating Field Identity:**\nSince fields don't have clear identity like cards, create a composite identifier by combining 1-3 most important data points. For example:\n- Address field: Street + City\n- Price field: Amount + Currency + Trend\n- Contact field: Name + Primary method\n- Date range: Start + Duration + Status\n\n**Content Priority Shift:**\nBecause users can't click through to see more, fitted formats for fields should:\n- Show the most important data that fits the space\n- Prioritize key identifiers and critical values\n- Include essential metadata over nice-to-have details\n- Use composite identity from 1-3 key data points\n- Remember: still space-constrained like card fitted formats\n\n**Visual Field Handling:**\nFor image-based or visually-oriented compound fields:\n- Make the image/visual element primary (fill most space)\n- Overlay metadata on top with appropriate contrast\n- Use scrims or backdrop shadows for text legibility (except on precise visual content)\n- Consider the image as the \"identity\" with data as support\n- **CRITICAL:** For color fields, charts, or data visualizations, avoid scrims/overlays that alter perception\n\n**Example implementations:**\n- **Location field:** Map thumbnail with address overlay\n- **Chart field:** Visualization fills space, key metrics on corners (no scrim)\n- **Media field:** Thumbnail/preview large, metadata badge overlay\n- **Color field:** Swatch as background, hex/rgb values on top (pure color, no overlay)\n\n```css\n/* Example: Visual field with overlay metadata */\n.field-tile-format.visual-field {\n position: relative;\n padding: clamp(0.1875rem, 2%, 0.5rem); /* Clear space scales with container */\n}\n\n.field-tile-format .visual-primary {\n width: 100%;\n height: 100%;\n object-fit: cover;\n border-radius: 0.25rem; /* Subtle radius prevents harsh edges */\n}\n\n.field-tile-format .metadata-overlay {\n position: absolute;\n bottom: clamp(0.1875rem, 2%, 0.5rem); /* Match container padding */\n left: clamp(0.1875rem, 2%, 0.5rem);\n right: clamp(0.1875rem, 2%, 0.5rem);\n padding: 0.5rem;\n background: linear-gradient(to top, \n rgba(0,0,0,0.8) 0%, \n rgba(0,0,0,0) 100%);\n color: white;\n border-radius: 0.25rem;\n}\n\n/* Non-visual fields show more detail */\n.field-badge-format {\n padding: clamp(0.1875rem, 2%, 0.375rem); /* Clear space for badges */\n}\n\n.field-badge-format .composite-identity {\n font-weight: 600;\n margin-bottom: 0.25rem;\n}\n\n.field-badge-format .field-details {\n font-size: 0.75rem;\n opacity: 0.9;\n}\n```\n\n### Visual Guidelines\n\n#### Icons\n- Incorporate subtly with appropriate size/weight\n- Visual support only - include after key content\n\n#### Images\n- Priority 2 - show after primary identifier\n- **Badge:** Always iconified (16-34px)\n- **Strip:** \n - 40px height: 20-34px (matches badge)\n - 65px height: Fixed 40px\n - 105px height: Can fill height with AR constraint in wide strips (250px+)\n- **Tile:** Background with vibrant scrim if image would obscure text (except for visually precise content)\n- **Tile/Card:** Apply shared scale budget with text\n- Aspect ratios 0.7-1.4 unless decorative\n- Never completely displace text\n- **For visual FieldDefs:** Image can be primary with metadata overlay\n\n**Scrim effects:** Use accent colors for vibrant overlays. Mix brand colors with dark gradients: purple-to-black, blue-to-indigo-to-black, or accent-with-opacity layers. **CRITICAL:** Never apply scrims to visually precise content (color swatches, charts, data visualizations, medical imagery) as they alter perception and compromise accuracy.\n\n**Animation restraint:** Never use animations that move content near edges - can expose accidental borders. Strips especially need static, predictable layouts for scanning.\n\n#### 105px Height Magnetic Edge Layout\n\nAt 105px, use `justify-content: space-between` to push three elements to top/middle/bottom edges, maximizing visual separation.\n\n### Key Implementation Details\n\n1. **CardDef Fitted:** Custom recommended (fallback exists)\n2. **FieldDef Requirements:** Embedded mandatory, fitted optional\n3. **Container Queries:** `container-type: size`\n4. **No Gaps:** Cover all sizes\n5. **Line Clamping:** Match height constraints\n6. **Scaling:** `clamp()` ±20-25%\n7. **Height Use:** Fill 40/65/105px fully\n8. **40px:** Horizontal only\n9. **105px:** `justify-content: space-between`\n10. **Strip IDs:** Always visible\n11. **Clear Space:** 3px min to 1rem max\n12. **Type Hierarchy:** Size/weight/spacing cascades (80-87% per level)\n13. **Data Shaping:** Use formatters\n14. **Priority:** Key-values > descriptions\n15. **Badge Images:** 16-34px scaling\n16. **Strip Images:** Match badge at 40px, larger at 65px+, AR-fill at 105px wide\n17. **Scale Budget:** 50% shared text/image\n18. **Font Scaling:** Smaller = smaller base\n19. **Key-Values:** Complete pairs only\n20. **Familiar Patterns:** Match expectations\n21. **Edge Fills:** Backgrounds full, content padded\n22. **Vibrant Scrims:** Accent colors\n23. **No Edge Animations:** Prevent border exposure\n24. **FieldDef Identity:** Composite 1-3 key data points for recognition\n25. **Visual Precision:** No scrims on color/chart/data viz content\n\n\n\n## CRITICAL Reminders\n\n1. **@context.searchResultsComponent renders components, not data** - For data in JS, use getCards\n2. **Type-specific sort fields MUST have 'on'** - Missing 'on' = no results shown!\n3. **Empty arrays need length check** - `(gt @model.items.length 0)`\n4. **Query result spacing** - Use `.container > .containsMany-field` pattern\n5. **Always use absolute module URLs** - `new URL(...).href`\n\n### Using getCards for Data Access and Aggregation\n\nWhen you need full access to card data for calculations, aggregations, or custom processing, use the `getCards` API from context.\n\n#### Basic getCards Pattern\n\n```gts\n// ❌ WRONG: Don't import getCards - it's just a type definition\n// import { getCards } from '@cardstack/runtime-common';\n\n// ✅ CORRECT: Use getCards from context\n// With live updates (for dashboards)\ncardsResult = this.args.context?.getCards(\n this,\n () => this.query,\n () => this.realmHrefs,\n { isLive: true }\n);\n\n// For one-time load (omit isLive)\ncardsResult = this.args.context?.getCards(\n this,\n () => this.query,\n () => this.realmHrefs\n);\n```\n\n#### Working with getCards Results\n\n```gts\n// getCards returns: { instances, isLoading, instancesByRealm }\ncardsResult = this.args.context?.getCards(\n this,\n () => this.storyQuery,\n () => this.realmHrefs,\n);\n\n// Frontend sorting/filtering\nget sortedCards() {\n const cards = this.cardsResult?.instances ?? [];\n return [...cards].sort((a, b) => b.rating - a.rating);\n}\n\n\n```\n\n#### Map/Reduce Aggregation Patterns\n\n**Note:** These patterns load all matching cards into memory, so use sparingly for large datasets.\n\n**RULE: Make aggregated stats real** - When showing totals, averages, or counts in templates, calculate them from actual data using aggregation functions, not hardcoded placeholders.\n\n```gts\n// Calculate totals using reduce\nget totalValue() {\n if (!this.cardsResult?.instances) return 0;\n return this.cardsResult.instances.reduce((sum, card) => {\n return sum + (card.value || 0);\n }, 0);\n}\n\n// Group by category\nget groupedByCategory() {\n if (!this.cardsResult?.instances) return {};\n return this.cardsResult.instances.reduce((groups, card) => {\n const category = card.category || 'Uncategorized';\n groups[category] = groups[category] || [];\n groups[category].push(card);\n return groups;\n }, {});\n}\n\n// Multiple metrics in one pass\nget metrics() {\n if (!this.cardsResult?.instances) return null;\n \n return this.cardsResult.instances.reduce((acc, card) => {\n acc.total += card.amount || 0;\n acc.count += 1;\n acc.byStatus[card.status] = (acc.byStatus[card.status] || 0) + 1;\n if (card.priority === 'high') acc.highPriority += 1;\n return acc;\n }, {\n total: 0,\n count: 0,\n byStatus: {},\n highPriority: 0\n });\n}\n```\n\n**Performance Considerations:**\n- For simple counts, use the type summaries API instead\n- @context.searchResultsComponent is better for display-only needs (prefers fast prerendered HTML)\n- Only use getCards when you need complex calculations\n- Consider pagination for large datasets\n\n### CardContainer: Making Cards Clickable\n\nTransforms cards into interactive, clickable elements for viewing or editing, complete with visual chrome. When used with the `cardComponentModifier`, it enables users to click through to view or edit the wrapped card.\n\n#### Usage\n\n```gts\n\n```\n\n**CRITICAL: Style Boxel UI Components for Custom Templates**\n\n**Boxel UI components (Button, BoxelSelect, etc.) must be completely styled when used in custom isolated, embedded, and fitted templates.** They come with minimal default styling and buttons especially will look broken without custom CSS.\n\n```gts\n\n```\n### Alternative: Using Custom Actions with viewCard API\n\nInstead of making entire cards clickable, you can create custom buttons or links that use the `viewCard` API to open cards in specific formats.\n\n#### Basic Implementation\n\n```javascript\n@action\nviewOrder(order: ProductOrder) {\n // Open order in isolated view\n this.args.viewCard(order, 'isolated');\n}\n\n@action\neditOrder(order: ProductOrder) {\n // Open card in rightmost stack for side-by-side reference\n // Useful for: 1) reference lookup, 2) edit panel on right while previewing on left\n this.args.viewCard(order, 'edit', {\n openCardInRightMostStack: true\n });\n}\n\n@action\nviewReturnPolicy() {\n // Open card using URL\n const returnPolicyURL = new URL('https://app.boxel.ai/markinc/storefront/ReturnPolicy/return-policy-0525.json');\n this.args.viewCard(returnPolicyURL, 'isolated');\n}\n```\n\n#### Template Example\n\n```hbs\n
\n \n
\n \n View Order\n \n \n \n Edit Order\n \n
\n \n\n \n Return Policy\n \n
\n```\n\n#### Available Formats\n\n- `'isolated'` - Read-oriented mode, may have some editable forms or interactive widgets\n- `'edit'` - Open card for full editing\n\n#### Use Cases\n- Multiple direct call-to-actions per card (view, edit)\n- More control over user interactions\n- Link to any card via a card URL\n\n\n## External Libraries: Bringing Third-Party Power to Boxel\n\n**When to Use External Libraries:** Sometimes you need specialized functionality like 3D graphics (Three.js), data visualization (D3), or charts. Boxel plays well with external libraries when you follow the right patterns.\n\n**Key Rules:**\n1. **Always use Modifiers for DOM access** - Never manipulate DOM directly\n2. **Use ember-concurrency tasks** for async operations like loading libraries\n3. **Bind external data to model fields** for reactive updates\n4. **Use proper loading states** while libraries initialize\n\n### Pattern: Dynamic Three.js Integration\n\n```gts\nimport { task } from 'ember-concurrency';\nimport Modifier from 'ember-modifier';\n\n// Global accessor function\nfunction three() {\n return (globalThis as any).THREE;\n}\n\nclass ThreeJsComponent extends Component {\n @tracked errorMessage = '';\n private canvasElement: HTMLCanvasElement | undefined;\n \n private loadThreeJs = task(async () => {\n if (three()) return;\n \n const script = document.createElement('script');\n script.src = 'https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.min.js';\n script.async = true;\n \n await new Promise((resolve, reject) => {\n script.onload = resolve;\n script.onerror = reject;\n document.head.appendChild(script);\n });\n });\n\n private initThreeJs = task(async () => {\n try {\n await this.loadThreeJs.perform();\n if (!three() || !this.canvasElement) return;\n \n const THREE = three();\n \n // Scene setup - bind results to model fields for reactivity\n this.scene = new THREE.Scene();\n // ... setup scene\n \n // CRITICAL: Bind external data to model fields\n this.args.model.sceneReady = true;\n this.args.model.lastUpdated = new Date();\n \n this.animate();\n } catch (e: any) {\n this.errorMessage = `Error: ${e.message}`;\n }\n });\n\n private onCanvasElement = (element: HTMLCanvasElement) => {\n this.canvasElement = element;\n this.initThreeJs.perform();\n };\n\n \n}\n```\n\n## File Organization\n\n### Single App Structure\n```\nmy-realm/\n├── blog-post.gts # Card definition (kebab-case)\n├── author.gts # Another card\n├── address-field.gts # Field definition (kebab-case-field)\n├── BlogPost/ # Instance directory (PascalCase)\n│ ├── hello-world.json # Instance (any-name)\n│ └── second-post.json \n└── Author/\n └── jane-doe.json\n```\n\n### Related Cards App Structure\n**CRITICAL:** When creating apps with multiple related cards, organize them in common folders:\n\n```\nmy-realm/\n├── ecommerce/ # Common folder for related cards\n│ ├── product.gts # Card definitions\n│ ├── order.gts\n│ ├── customer.gts\n│ ├── Product/ # Instance directories\n│ │ └── laptop-pro.json\n│ └── Order/\n│ └── order-001.json\n├── blog/ # Another app's folder\n│ ├── post.gts\n│ ├── author.gts\n│ └── Post/\n│ └── welcome.json\n└── shared/ # Shared components\n └── address-field.gts # Common field definitions\n```\n\n**Directory Discipline:** When creating files within a specific directory structure (e.g., `ecommerce/`), keep ALL related files within that structure. Don't create files outside the intended directory organization.\n\n**Relationship Path Tracking:** When creating related JSON instances, maintain a mental map of your file paths. Links between instances must use the exact relative paths you've created - consistency prevents broken relationships.\n\n## JSON Instance Format Quick Reference\n\n**When creating `.json` card instances via SEARCH/REPLACE, follow this structure:**\n\n**Naming:** Use natural names for JSON files (e.g., `Author/jane-doe.json`, `Product/laptop-pro.json`) - don't append `-sample-data`\n\n**Path Consistency:** When creating multiple related JSON instances, track the exact file paths you create. Relationship links must match these paths exactly - if you create `Author/dr-nakamura.json`, reference it as `\"../Author/dr-nakamura\"` from other instances.\n\n### Root Structure\nAll data wrapped in a `data` object with:\n* `type`: Always `\"card\"` for instances\n* `attributes`: Field values go here\n* `relationships`: Links to other cards\n* `meta.adoptsFrom`: Connection to GTS definition\n\n### Instance Template\n```json\n{\n \"data\": {\n \"type\": \"card\",\n \"attributes\": {\n // Field values here\n },\n \"relationships\": {\n // Card links here\n },\n \"meta\": {\n \"adoptsFrom\": {\n \"module\": \"../path-to-gts-file\",\n \"name\": \"CardDefClassName\"\n }\n }\n }\n}\n```\n\n### Field Value Patterns\n\n**Simple fields** (`contains(StringField)`, etc.):\n```json\n\"attributes\": {\n \"title\": \"My Title\",\n \"price\": 29.99,\n \"isActive\": true\n}\n```\n\n**Compound fields** (`contains(AddressField)` - a FieldDef):\n```json\n\"attributes\": {\n \"address\": {\n \"street\": \"4827 Riverside Terrace\",\n \"city\": \"Portland\",\n \"postalCode\": \"97205\"\n }\n}\n```\n\n**Array fields** (`containsMany`):\n```json\n\"attributes\": {\n \"tags\": [\"urgent\", \"review\", \"frontend\"],\n \"phoneNumbers\": [\n { \"number\": \"+1-503-555-0134\", \"type\": \"work\" },\n { \"number\": \"+1-971-555-0198\", \"type\": \"mobile\" }\n ]\n}\n```\n\n### Relationship Patterns\n\n**Single link** (`linksTo`):\n```json\n\"relationships\": {\n \"author\": {\n \"links\": {\n \"self\": \"../Author/dr-nakamura\"\n }\n }\n}\n```\n\n**Multiple links** (`linksToMany`) - note the `.0`, `.1` pattern:\n```json\n\"relationships\": {\n \"teamMembers.0\": {\n \"links\": { \"self\": \"../Person/kai-nakamura\" }\n },\n \"teamMembers.1\": {\n \"links\": { \"self\": \"../Person/esperanza-cruz\" }\n }\n}\n```\n\n**Empty linksToMany** - when no relationships exist:\n```json\n\"relationships\": {\n \"nextLevels\": {\n \"links\": {\n \"self\": null\n }\n }\n}\n```\nNote: Use `null`, not an empty array `[]`\n\n### Path Conventions\n* **Module paths**: Relative to JSON location, no `.gts` extension\n * Local: `\"../author\"` or `\"../../shared/address-field\"`\n * Base: `\"https://cardstack.com/base/string\"`\n* **Relationship paths**: Relative paths, no `.json` extension\n * `\"../Author/jane-doe\"` not `\"../Author/jane-doe.json\"`\n* **Date formats**: \n * DateField: `\"2024-11-15\"`\n * DateTimeField: `\"2024-11-15T10:00:00Z\"`\n\n## 🚫 Common Mistakes to Avoid\n\n### 1. Using contains/containsMany with CardDef\n```gts\n// ❌ WRONG\nexport class Auction extends CardDef {\n @field auctionItems = containsMany(AuctionItem); // AuctionItem is a CardDef\n}\n\n// ✅ CORRECT\nexport class Auction extends CardDef {\n @field auctionItems = linksToMany(AuctionItem); // Use linksToMany for CardDef\n}\n```\n\n### 2. Template Calculation Mistakes\n```gts\n// ❌ WRONG - JavaScript/constructors in template\nTotal: {{@model.price * @model.quantity}}\n{{if @model.currentMonth @model.currentMonth (formatDateTime (new Date()) \"MMMM YYYY\")}}\n\n// ✅ CORRECT - Use helpers or computed property\nTotal: {{multiply @model.price @model.quantity}}\n{{if @model.currentMonth @model.currentMonth this.currentMonthDisplay}}\n```\n\n### 3. Using Reserved Words as Field Names\n```gts\n// ❌ WRONG - JavaScript reserved words\n@field type = contains(StringField); // 'type' is reserved\n@field class = contains(StringField); // 'class' is reserved\n\n// ✅ CORRECT - Use descriptive alternatives\n@field recordType = contains(StringField); // Instead of 'type'\n@field category = contains(StringField); // Instead of 'class'\n\n// ✅ CORRECT - Override inherited fields with computed versions\n@field fullName = contains(StringField);\n@field title = contains(StringField, {\n computeVia: function() { return this.fullName ?? 'Unnamed'; }\n});\n```\n\n### 4. Missing Exports\n```gts\n// ❌ WRONG - Missing export will break module loading\nclass BlogPost extends CardDef { // Missing 'export'\n}\n\n// ❌ WRONG - Separate export statement\nclass BlogPost extends CardDef { }\nexport { BlogPost };\n\n// ✅ CORRECT - Always export CardDef and FieldDef classes inline\nexport class BlogPost extends CardDef {\n}\n```\n\n### 5. Missing Spacing for Auto-Collections\n```gts\n// ❌ WRONG - No spacing wrapper for delegated items\n<@fields.items @format=\"embedded\" />\n\n// ❌ WRONG - Container styling won't reach containsMany items\n
\n <@fields.items @format=\"embedded\" />\n
\n\n\n\n// ✅ CORRECT - Target .containsMany-field\n
\n <@fields.items @format=\"embedded\" />\n
\n\n\n```\n\n### 6. Mixing @model Iteration with @fields Delegation\n```gts\n// ❌ WRONG - Cannot use @fields inside @model iteration\n{{#each @model.teamMembers as |member|}}\n <@fields.member @format=\"embedded\" /> \n{{/each}}\n\n// ✅ CORRECT - Choose one approach\n// Option 1: Full delegation\n<@fields.teamMembers @format=\"embedded\" />\n\n// Option 2: Full @model control\n{{#each @model.teamMembers as |member|}}\n
{{member.name}}
\n{{/each}}\n```\n\n### 7. Using Emoji or Boxel Icons in Templates\n```hbs\n\n

🎯 Daily Goals

\n\n\n\n

Daily Goals

\n\n\n\n

\n \n \n \n \n \n Daily Goals\n

\n\n```\n\n### 8. Self-Import Error\n```gts\n// ❌ WRONG - Never import the same field you're defining\nimport AddressField from 'https://cardstack.com/base/address';\n\nexport class AddressField extends FieldDef { // Defining AddressField but importing it too\n // ... this will cause conflicts\n}\n\n// ✅ CORRECT - Don't import what you're defining\nexport class AddressField extends FieldDef {\n // ... define the field without importing it\n}\n\n// ✅ CORRECT - To extend a base field, import it with a different name or extend directly\nimport BaseAddressField from 'https://cardstack.com/base/address';\n\nexport class FancyAddressField extends BaseAddressField {\n // ... extend the base field with custom behavior\n}\n```\n\n### 9. Escaping Placeholder Attributes Only\n```hbs\n\n\n 0) { return \"success\"; }\">\n\n\n\n\n```\n\n### 10. Don't use single curlies\n```hbs\n\n#{@model.paddleNumber}\n\n\n#{{@model.paddleNumber}}\n```\n\n**Note:** The `#` character starts block helpers in Handlebars (e.g., `{{#if}}`, `{{#each}}`), so it must be escaped when you want to display it literally before template interpolations.\n\n### 11. Using Unstyled Buttons\n```gts\n// ❌ WRONG - Unstyled buttons look broken\n\n\n// ✅ CORRECT - Always add complete styling (see button styling example in Advanced Patterns)\n\n```\n\n### 12. Missing Tracking Comments in .gts Files\n```gts\n// ❌ WRONG - No tracking mode indicator on line 1\nimport { CardDef } from 'https://cardstack.com/base/card-api';\n\n// ✅ CORRECT - Tracking mode on line 1, markers throughout\n// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══\nimport { CardDef } from 'https://cardstack.com/base/card-api'; // ¹ Core imports\n```\n\nRemember to include the post-SEARCH/REPLACE notation `╰ ¹⁻³` after blocks!\n\n### 13. Wrong Empty Relationship Format in JSON\n```json\n// ❌ WRONG - Empty array for null relationship\n\"relationships\": {\n \"nextLevels\": {\n \"links\": {\n \"self\": []\n }\n }\n}\n\n// ✅ CORRECT - Use null for empty linksToMany\n\"relationships\": {\n \"nextLevels\": {\n \"links\": {\n \"self\": null\n }\n }\n}\n```\n\n### 14. SVG URL References Don't Work in Boxel\n```hbs\n\n\n \n \n \n \n \n \n \n\n\n\n\n \n\n\n```\n\n**Rule:** Avoid `url(#id)` references in SVGs (for gradients, patterns, clips, etc.) as Boxel cannot route these correctly. Instead, use CSS alternatives to style SVG elements when available. For gradients specifically, use CSS `linear-gradient()` or `radial-gradient()` on SVG elements rather than SVG `` or ``.\n\n### 15. Missing 'on' Property in Query Filters\n```gts\n// ❌ WRONG - Missing 'on' for range filter\nconst query = {\n filter: {\n range: { price: { lte: 100 } }\n }\n};\n\n// ✅ CORRECT - Include 'on' for non-basic filters\nconst query = {\n filter: {\n on: { module: new URL('./product', import.meta.url).href, name: 'Product' },\n range: { price: { lte: 100 } }\n }\n};\n```\n\n### Common Patterns\n\n```typescript\n// Field existence check\n{ on: {...}, not: { eq: { description: null } } }\n\n// Multiple ranges \n{ on: {...}, range: {\n score: { gt: 8 },\n years: { gte: 1, lt: 10 },\n date: { gte: new Date(Date.now() - 180 * 24 * 60 * 60 * 1000) }\n}}\n\n// Nested field access\n{ on: {...}, eq: { \n 'supervisor.id': this.args.model.id,\n 'department.active': true\n}}\n\n// Dynamic references\n{ on: {...}, range: { \n price: { lte: this.args.model.budget || 1000 }\n}}\n```\n\n## ✅ Pre-Generation Checklist\n\n### 🚨 CRITICAL (Will Break Functionality)\n- [ ] **Using SEARCH/REPLACE blocks for all .gts edits**\n- [ ] **Tracking mode indicator on line 1:** `// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══`\n- [ ] **NO contains/containsMany with CardDef** - Check every field using contains/containsMany only uses FieldDef types\n- [ ] **NO JavaScript calculations/constructors in templates** - All computations must be in JS properties/getters\n- [ ] **ALL CardDef and FieldDef classes exported inline** - Every class must have 'export' in declaration\n- [ ] Correct contains/linksTo usage per the cardinal rule\n- [ ] Array length checks: `{{#if (gt @model.array.length 0)}}` not `{{#if @model.array}}`\n- [ ] **containsMany collection spacing: `.container > .containsMany-field { display: flex/grid; gap: X; }`**\n- [ ] **@fields delegation rule**: Always use `@fields` for delegation (even singular fields)\n- [ ] **Never mix @model iteration with @fields delegation** - choose one approach\n- [ ] **Fitted format requires style overrides (TEMPORARY):** `style=\"width: 100%; height: 100%\"`\n- [ ] **Use inline SVG in templates instead of emoji or Boxel icons**\n- [ ] **Never use unstyled buttons** - always add complete custom CSS styling\n- [ ] **Empty linksToMany relationships use null** - `\"self\": null` not `\"self\": []`\n- [ ] **No SVG url(#id) references** - use CSS gradients on SVG elements instead\n- [ ] **External libraries** - use Modifiers for DOM access, never manipulate DOM directly\n- [ ] **Query filters use 'on' property** - Required for range, contains, eq (except after type filter)\n- [ ] **Module URLs use new URL().href** - Never use relative paths in queries\n- [ ] **Realm URLs have trailing slash** - Required for realm references\n\n### ⚠️ IMPORTANT (Affects User Experience)\n- [ ] Icons assigned to all CardDef and FieldDef\n- [ ] Embedded templates for all FieldDefs\n- [ ] Empty states provided for all arrays\n- [ ] Every card computes inherited `title` field from primary identifier\n- [ ] Recent dates in sample data (2024/2025)\n- [ ] Currency/dates formatted with helpers in templates only\n- [ ] Meaningful placeholder text for all fallback states\n- [ ] Isolated views have scrollable content area\n- [ ] **Boxel UI components completely styled in custom templates**\n- [ ] **Creative sample data** - avoid clichés, create believable fictional scenarios\n- [ ] **Thoughtful font selection** - choose domain-appropriate Google fonts\n\n## Critical Rules Summary\n\n### One-Shot Success Criteria (Priority Order)\n1. **Runnable** - No syntax errors, all imports work, no runtime crashes due to missing data\n2. **Syntactically Correct** - Proper contains/linksTo, exports, tracking comments\n3. **Attractive** - Professional styling, thoughtful UX, visual polish\n4. **Evolvable** - Clear structure for user additions and modifications\n\n### NEVER Do These\n\n### 🔴 #1 MOST CRITICAL ERROR:\n❌ `contains(CardDef)` or `containsMany(CardDef)` → **ALWAYS** use `linksTo(CardDef)` or `linksToMany(CardDef)`\n\n### 🔴 #2 CRITICAL: No JavaScript in Templates\n❌ **NEVER do calculations, constructors, or call methods in templates:**\n - `{{@model.price * 1.2}}` → Use `{{multiply @model.price 1.2}}`\n - `{{(new Date())}}` → Create getter `get currentDate()`\n - `{{price > 100}}` → Use `{{gt price 100}}`\n\n### 🔴 #3 CRITICAL: Field Rules\n❌ **JavaScript reserved words as field names** → Use descriptive alternatives \n❌ **Defining same field name twice in your own class** → Each field name unique \n✅ **OK to override parent's fields** → Can compute title, description, thumbnailURL \n❌ **Missing exports on CardDef/FieldDef** → Every class must be exported \n\n### 🔴 #4 CRITICAL: Edit Tracking Mode\n❌ **Missing tracking mode indicator on line 1** → Every .gts file MUST start with tracking \n❌ **SEARCH/REPLACE blocks without tracking markers** → Both blocks must contain ⁿ\n\n### Other Critical Rules\n❌ `<@fields.items />` without proper CSS selector → Target `.container > .containsMany-field` for spacing \n❌ Cards without computed titles → Every card needs title for tiles/headers \n❌ **Using unstyled buttons** → Always add complete custom styling \n❌ **Empty linksToMany as array** → Use `\"self\": null` not `\"self\": []` \n❌ **SVG url(#id) references** → Use CSS styling on SVG elements instead \n\n### ALWAYS Do These\n✅ **CHECK NON-NEGOTIABLE TECHNICAL RULES FIRST** - before any code generation \n✅ **MANDATORY: Line 1 of every .gts file:** `// ═══ [EDIT TRACKING: ON] Mark all changes with ⁿ ═══` \n✅ **Export every CardDef and FieldDef class** - essential for Boxel's module system \n✅ **MANDATORY: Add spacing for containsMany collections** - use `.container > .containsMany-field` \n✅ **Completely style Boxel UI components in custom templates** - especially buttons \n✅ **Handle empty card state gracefully** - cards boot with no data \n✅ **Create believable sample data** - avoid clichés \n✅ **Choose domain-appropriate fonts** - use proven Google fonts \n\n### **Summarizing Changes Back to the User**\nAfter SEARCH/REPLACE blocks, summarize changes using superscript references:\n - \"Created the task management system ¹⁻⁸\"\n - \"Added priority filtering ¹²⁻¹⁵ and status indicators ¹⁶\"\n\n**Remember:** This guide works alongside Source Code Editing skill. For general SEARCH/REPLACE mechanics, refer to that document. This guide adds Boxel-specific requirements.", "commands": [], "cardTitle": "Boxel Development", "cardDescription": "Created by the Boxel Team with help from Gemini 2.5 Pro Experimental - V3", diff --git a/packages/base/card-api.gts b/packages/base/card-api.gts index 2371e809fca..7edf9f819e3 100644 --- a/packages/base/card-api.gts +++ b/packages/base/card-api.gts @@ -355,8 +355,8 @@ export interface CardContext { }; }; }>; - // The search rendering surface: renders the heterogeneous `search-entry` - // stream for a `search-entry`-rooted query — prerendered HTML inert (hydrated + // The search rendering surface: renders the heterogeneous `entry` + // stream for an `entry`-rooted query — prerendered HTML inert (hydrated // lazily) or a live card — so a card author renders results without ever // branching on prerendered-vs-live. Supersedes `prerenderedCardSearchComponent`. searchResultsComponent: typeof GlimmerComponent; diff --git a/packages/base/components/card-list.gts b/packages/base/components/card-list.gts index 560bf6f3725..49318f24189 100644 --- a/packages/base/components/card-list.gts +++ b/packages/base/components/card-list.gts @@ -62,7 +62,7 @@ export default class CardList extends Component { @consume(CardContextName) declare cardContext: CardContext | undefined; - // The `search-entry`-rooted query, adapted from the incoming `Query`. + // The `entry`-rooted query, adapted from the incoming `Query`. // The default fieldset (no `fields` member) resolves to "html, falling back // to the `item` serialization where no rendering matched" — exactly what the // grid wants (prerendered HTML for cards; an `item`/`icon` fallback for file diff --git a/packages/boxel-cli/src/commands/realm/ingest-card.ts b/packages/boxel-cli/src/commands/realm/ingest-card.ts index a5c9098b258..b4c4e3ae8c9 100644 --- a/packages/boxel-cli/src/commands/realm/ingest-card.ts +++ b/packages/boxel-cli/src/commands/realm/ingest-card.ts @@ -439,7 +439,7 @@ class RealmCardIngester extends RealmSyncBase { // search returns nothing for it — which is why instances and Specs went // uncopied (the module crawl survives because it uses direct file fetches). // The realm's own endpoint sees its full index. The request is data-only - // (`fields[search-entry]=item`); the response is a search-entry document + // (`fields[entry]=item`); the response is an entry document // whose matched `item` serializations resolve out of `included` uniformly // for normal and published realms (the v1 `data`-vs-`included` split // disappears — every match is an entry that references its item). diff --git a/packages/boxel-cli/src/commands/search.ts b/packages/boxel-cli/src/commands/search.ts index 2a69b9c7728..ea02fd78528 100644 --- a/packages/boxel-cli/src/commands/search.ts +++ b/packages/boxel-cli/src/commands/search.ts @@ -20,8 +20,8 @@ export interface SearchCommandOptions { profileManager?: ProfileManager; } -// `_federated-search` speaks the search-entry wire grammar: one query -// rooted on `search-entry`, where entry membership is addressed through +// `_federated-search` speaks the entry wire grammar: one query +// rooted on `entry`, where entry membership is addressed through // `item.` (the card/file serialization). The type anchor is `item.on` and the // field paths inside the filter operators carry the `item.` prefix. Callers // here author ordinary card-rooted queries, so these helpers rewrite a query @@ -72,7 +72,7 @@ function toItemFilter( out.matches = value; } else { throw new Error( - `cannot translate filter member "${key}" to a search-entry query — the type anchor is "on"/"type" and field paths live under the ${FIELD_KEYED_OPERATORS.join('/')} operators`, + `cannot translate filter member "${key}" to an entry query — the type anchor is "on"/"type" and field paths live under the ${FIELD_KEYED_OPERATORS.join('/')} operators`, ); } } @@ -102,7 +102,7 @@ interface SearchEntryRequestBody { realms?: string[]; // boxel-cli never renders HTML, so it requests the data-only fieldset: each // entry carries only its full `item` serialization (no prerendered `html`). - fields: { 'search-entry': ['item'] }; + fields: { entry: ['item'] }; filter?: Record; sort?: Record[]; page?: unknown; @@ -110,7 +110,7 @@ interface SearchEntryRequestBody { } /** - * Build a search-entry request body from a card-rooted query: the + * Build an entry request body from a card-rooted query: the * `item.`-addressed filter/sort plus the data-only fieldset. Pass `realms` for * the federated `_federated-search`; omit it to query a single realm's own * `_search`. @@ -120,7 +120,7 @@ export function searchEntryRequestBody( realms?: string[], ): SearchEntryRequestBody { let body: SearchEntryRequestBody = { - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, }; if (realms !== undefined) { body.realms = realms; @@ -152,10 +152,10 @@ export function searchEntryRequestBody( return body; } -// A data-only search-entry document, narrowed to the shape this client reads: +// A data-only entry document, narrowed to the shape this client reads: // each entry links its serialization through `item`, and the `card`/`file-meta` // resource itself travels in `included`. A structural local type rather than -// runtime-common's `SearchEntryCollectionDocument` — that one transitively +// runtime-common's `EntryCollectionDocument` — that one transitively // pulls the index's `https://cardstack.com/base/*` imports, which don't resolve // in a plain Node CLI (the same boundary the query helpers above note). interface SearchEntryDoc { @@ -168,7 +168,7 @@ interface SearchEntryDoc { } /** - * Flatten a data-only search-entry document into the `item` serializations, in + * Flatten a data-only entry document into the `item` serializations, in * result order — the same `card`/`file-meta` resources the legacy endpoint * returned as its top-level `data`. Each entry points at its serialization in * `included`; resolve and collect them. @@ -203,8 +203,8 @@ export function itemsFromSearchEntryDoc( * Federated search across one or more realms via the `_federated-search` * server endpoint. * - * Sends the search-entry-rooted query as a QUERY request requesting the - * data-only fieldset (`fields[search-entry]=item`), and returns the `item` + * Sends the entry-rooted query as a QUERY request requesting the + * data-only fieldset (`fields[entry]=item`), and returns the `item` * serializations the endpoint links in `included` — the `card`/`file-meta` * resources callers consume. Uses the server JWT via * `ProfileManager.authedRealmServerFetch`. diff --git a/packages/boxel-cli/tests/commands/ingest-card-graph.test.ts b/packages/boxel-cli/tests/commands/ingest-card-graph.test.ts index 9a2ff1aae38..25e7c1c5934 100644 --- a/packages/boxel-cli/tests/commands/ingest-card-graph.test.ts +++ b/packages/boxel-cli/tests/commands/ingest-card-graph.test.ts @@ -161,7 +161,7 @@ function makeFakeAuthenticator(fetchedUrls: string[]): RealmAuthenticator { // The cards the source realm matches for the two shapes the ingester issues: // instances of the entry card's exported classes, and all base-realm Spec // cards (filtered by specType + ref in the ingester itself). The type anchor -// arrives `item.`-addressed (`filter['item.on']`) — the search-entry grammar +// arrives `item.`-addressed (`filter['item.on']`) — the entry grammar // `_search` speaks. function fakeSearchData( bodyStr: string, @@ -204,7 +204,7 @@ function fakeSearchData( return []; } -// Wrap matched cards as a data-only search-entry document — one entry per card +// Wrap matched cards as a data-only entry document — one entry per card // linking its `item`, with the card resources themselves in `included` (the // shape `_search` returns; a published realm carries its matches the same // way, so the ingester needs no published-vs-normal special-casing). diff --git a/packages/boxel-cli/tests/commands/search-query.test.ts b/packages/boxel-cli/tests/commands/search-query.test.ts index 896f0b27f1f..026b7a5c99a 100644 --- a/packages/boxel-cli/tests/commands/search-query.test.ts +++ b/packages/boxel-cli/tests/commands/search-query.test.ts @@ -13,12 +13,12 @@ const CardDefRef = { name: 'CardDef', }; -describe('searchEntryRequestBody — card-rooted query → search-entry wire grammar', () => { +describe('searchEntryRequestBody — card-rooted query → entry wire grammar', () => { it('always requests the data-only fieldset and the given realms', () => { let body = searchEntryRequestBody({}, ['https://realm/a/']); expect(body).toEqual({ realms: ['https://realm/a/'], - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, }); }); @@ -105,7 +105,7 @@ describe('searchEntryRequestBody — card-rooted query → search-entry wire gra }); }); -describe('itemsFromSearchEntryDoc — flatten a data-only search-entry doc to items', () => { +describe('itemsFromSearchEntryDoc — flatten a data-only entry doc to items', () => { it("resolves each entry's item from included, in entry order", () => { let doc = { data: [ diff --git a/packages/experiments-realm/app-card.gts b/packages/experiments-realm/app-card.gts index 235f1e0efb9..8f21f911bcf 100644 --- a/packages/experiments-realm/app-card.gts +++ b/packages/experiments-realm/app-card.gts @@ -325,7 +325,7 @@ class DefaultTabTemplate extends GlimmerComponent { } as Query; } - // The `search-entry`-rooted query, adapted from the `query` above. + // The `entry`-rooted query, adapted from the `query` above. // `fitted` is the default rendering, so no `htmlQuery` binding is needed. // Undefined (no active tab ref) leaves the search component idle. get searchResultsQuery(): SearchEntryWireQuery | undefined { diff --git a/packages/experiments-realm/components/card-list.gts b/packages/experiments-realm/components/card-list.gts index 8a8b8ac3a08..48f5926efa7 100644 --- a/packages/experiments-realm/components/card-list.gts +++ b/packages/experiments-realm/components/card-list.gts @@ -21,7 +21,7 @@ interface CardListSignature { Element: HTMLElement; } export class CardList extends GlimmerComponent { - // The `search-entry`-rooted query, adapted from the incoming `Query`. + // The `entry`-rooted query, adapted from the incoming `Query`. // `embedded` is bound through the query's `htmlQuery` field (the way to // select a prerendered format); a bare `eq.format` would be read as an // `item.` field path and rejected. diff --git a/packages/host/app/commands/sync-openrouter-models.ts b/packages/host/app/commands/sync-openrouter-models.ts index 072cb223112..f58d80d49a0 100644 --- a/packages/host/app/commands/sync-openrouter-models.ts +++ b/packages/host/app/commands/sync-openrouter-models.ts @@ -2,7 +2,7 @@ import { service } from '@ember/service'; import { SupportedMimeType, - isSearchEntryCollectionDocument, + isEntryCollectionDocument, rri, searchEntryWireQueryFromQuery, } from '@cardstack/runtime-common'; @@ -339,8 +339,8 @@ export default class SyncOpenRouterModelsCommand extends HostBaseCommand< let slugs = new Set(); try { // Listing existing cards only needs each one's id, so ask the - // search-entry engine for a data-only projection - // (`fields[search-entry]=item`): every entry carries its `item` + // entry engine for a data-only projection + // (`fields[entry]=item`): every entry carries its `item` // serialization, no prerendered HTML. let wireQuery = searchEntryWireQueryFromQuery( { @@ -367,9 +367,9 @@ export default class SyncOpenRouterModelsCommand extends HostBaseCommand< if (response.ok) { let result = await response.json(); - if (isSearchEntryCollectionDocument(result)) { + if (isEntryCollectionDocument(result)) { for (let entry of result.data) { - // A `search-entry` resource's id is the card URL. + // An `entry` resource's id is the card URL. let id = entry.id ?? ''; // Extract slug from URL: .../OpenRouterModel/slug-name or .../OpenRouterModel/slug-name.json let match = id.match(/OpenRouterModel\/([^/]+)$/); @@ -382,7 +382,7 @@ export default class SyncOpenRouterModelsCommand extends HostBaseCommand< } } } else { - // A 200 that isn't a search-entry document is unexpected for + // A 200 that isn't an entry document is unexpected for // /_search; surface it rather than silently treating every model // as new (same best-effort fallback as the catch below). console.warn( diff --git a/packages/host/app/components/card-search/panel-content.gts b/packages/host/app/components/card-search/panel-content.gts index 5d74e9a13f3..98e214f57db 100644 --- a/packages/host/app/components/card-search/panel-content.gts +++ b/packages/host/app/components/card-search/panel-content.gts @@ -141,7 +141,7 @@ interface Signature { // The results pane of the search sheet / card chooser. Renders through the // `` component family: one instance for the realm search, a // nested one for recents (with the live-recents fallback layered in), then hands -// their yielded `search-entry` streams to ``, which lays them out +// their yielded `entry` streams to ``, which lays them out // into realm / recents / URL-paste sections (with the header, multiselect, the // Adorn treatment, pagination, and the result count). Resources are // construct-once: the two `` own their live-search resources @@ -185,7 +185,7 @@ export default class PanelContent extends Component { return this.cardResource?.isLoaded ?? false; } - // The `search-entry` query for the main realm search, built from the + // The `entry` query for the main realm search, built from the // shared `Query` builder via `searchEntryWireQueryFromQuery`. Fitted is the // default rendering, so no `htmlQuery` override is needed in the default // variant; the mini variant pins it to the uniform CardDef fitted tile @@ -224,7 +224,7 @@ export default class PanelContent extends Component { // rendering through the wire filter's top-level `eq` htmlQuery — fitted // format at the CardDef render type, served from the per-ancestor // `fitted_html` entries the index already carries. The `eq` carries only the - // htmlQuery binding, which the search-entry engine lifts out and then + // htmlQuery binding, which the entry engine lifts out and then // dissolves the now-empty `eq`, so the rest of the filter is untouched; // `buildSearchQuery`/`buildRecentsQuery` never emit a top-level `eq`, so // there is nothing to collide with. Non-mini variants pass through unchanged diff --git a/packages/host/app/components/card-search/result-section.gts b/packages/host/app/components/card-search/result-section.gts index 6d79b1963b3..7489eb1bbc5 100644 --- a/packages/host/app/components/card-search/result-section.gts +++ b/packages/host/app/components/card-search/result-section.gts @@ -104,7 +104,7 @@ interface Signature { // One section of the search-results pane — a realm group, the URL-paste row, or // the recents row. Lays its rows out into a grid of `ResultTile`s; each tile -// renders through the search-entry rendering surface (a search-entry's +// renders through the entry rendering surface (an entry's // `entry.component`, or a live `CardDef` for the URL paste / live-recents // fallback). export default class ResultSection extends Component { diff --git a/packages/host/app/components/card-search/result-tile.gts b/packages/host/app/components/card-search/result-tile.gts index df42f663d7f..f38ee969182 100644 --- a/packages/host/app/components/card-search/result-tile.gts +++ b/packages/host/app/components/card-search/result-tile.gts @@ -113,7 +113,7 @@ export default class SearchResultTile extends Component { return this.args.newCard != null; } - // The type name shown in the Adorn type-label tab. Search-entry rows carry it + // The type name shown in the Adorn type-label tab. Entry rows carry it // on their deduped `icon` resource (no live instance needed); the URL-paste // live card supplies it in-memory. The "Create New" row has no label. private get adornTypeName(): string | undefined { @@ -127,7 +127,7 @@ export default class SearchResultTile extends Component { return undefined; } - // Type-name precedence mirrored for the icon: search-entry rows carry icon + // Type-name precedence mirrored for the icon: entry rows carry icon // HTML on the `icon` resource; the live card supplies a component in-memory. private get adornTypeIcon(): unknown { if (!this.args.adorn || this.isNewCard) return undefined; diff --git a/packages/host/app/components/card-search/search-results.gts b/packages/host/app/components/card-search/search-results.gts index 48da37b684d..6193c50d907 100644 --- a/packages/host/app/components/card-search/search-results.gts +++ b/packages/host/app/components/card-search/search-results.gts @@ -18,7 +18,7 @@ import type { HydrationMode } from './hydratable-card'; import type StoreService from '../../services/store'; -// The one search component family. Consumes the heterogeneous `search-entry` +// The one search component family. Consumes the heterogeneous `entry` // stream from `getSearchEntriesResource` (through the shared render-stable // view-model layer) and renders it transparently — prerendered HTML inert (the // fast path, hydrated lazily on interaction) or the live serialization. Used @@ -60,7 +60,7 @@ export default class SearchResults extends Component { - this.#log.error( - `failed to inflate search-entry item ${entry.id}`, - err, - ); + this.#log.error(`failed to inflate entry item ${entry.id}`, err); }); } } diff --git a/packages/host/app/components/card-search/sheet-results.gts b/packages/host/app/components/card-search/sheet-results.gts index a2224133e6b..6eebe68bf01 100644 --- a/packages/host/app/components/card-search/sheet-results.gts +++ b/packages/host/app/components/card-search/sheet-results.gts @@ -95,7 +95,7 @@ interface Signature { Blocks: {}; } -// Lays the heterogeneous `search-entry` stream from `` out into +// Lays the heterogeneous `entry` stream from `` out into // the search sheet's realm / recents / URL-paste sections, with the header, // multiselect, the Adorn treatment, pagination, and the result count expressed // here at the call site over the yielded entries. Every derivation is a getter diff --git a/packages/host/app/components/operator-mode/code-submode/playground/playground-panel.gts b/packages/host/app/components/operator-mode/code-submode/playground/playground-panel.gts index 43e25792b09..c25d9233a31 100644 --- a/packages/host/app/components/operator-mode/code-submode/playground/playground-panel.gts +++ b/packages/host/app/components/operator-mode/code-submode/playground/playground-panel.gts @@ -567,7 +567,7 @@ export default class PlaygroundPanel extends Component { }; } - // The `search-entry` queries for the instance chooser, adapted from the + // The `entry` queries for the instance chooser, adapted from the // legacy `Query` getters above. The default fieldset resolves to fitted HTML // (the format these searches used), so no `htmlQuery` override is needed. private get searchResultsQuery(): SearchEntryWireQuery | undefined { @@ -959,7 +959,7 @@ export default class PlaygroundPanel extends Component { } let selectedCardId = this.dropdownSelection.card.id; - // `entry.id` is the bare card URL already (the search-entry identity strips + // `entry.id` is the bare card URL already (the entry identity strips // the `.json` the dropdown selection also omits), so they compare directly. let card = entries.find((c) => c.id === selectedCardId); return card; diff --git a/packages/host/app/components/operator-mode/create-listing-modal.gts b/packages/host/app/components/operator-mode/create-listing-modal.gts index 50f07091873..73fab902994 100644 --- a/packages/host/app/components/operator-mode/create-listing-modal.gts +++ b/packages/host/app/components/operator-mode/create-listing-modal.gts @@ -109,7 +109,7 @@ export default class CreateListingModal extends Component { return [...new Set(realms)]; } - // The `search-entry` query for the selected example cards: scoped to the + // The `entry` query for the selected example cards: scoped to the // chosen card URLs (matched by index file URL, hence the `.json`-suffixed // `selectedExampleCardUrls`) and their realms, with the `atom` rendering // bound through the filter's `htmlQuery` (the way to select a prerendered diff --git a/packages/host/app/resources/file-tree-from-index.ts b/packages/host/app/resources/file-tree-from-index.ts index 6022d4638a3..fb9d39c1b24 100644 --- a/packages/host/app/resources/file-tree-from-index.ts +++ b/packages/host/app/resources/file-tree-from-index.ts @@ -115,7 +115,7 @@ export class FileTreeFromIndexResource extends Resource { } }); - // The file tree only needs each matched file's URL — the `search-entry` + // The file tree only needs each matched file's URL — the `entry` // ids. The fieldset pins the leanest projection the wire grammar offers (a // single-field sparse item) rather than full serializations or renderings. private get query(): SearchEntryWireQuery { @@ -123,7 +123,7 @@ export class FileTreeFromIndexResource extends Resource { let eq = fieldFilter && Object.keys(fieldFilter).length > 0 ? Object.fromEntries( - // Field paths in the search-entry wire grammar are `item.`-prefixed. + // Field paths in the entry wire grammar are `item.`-prefixed. Object.entries(fieldFilter).map(([field, value]) => [ `item.${field}`, value, @@ -135,7 +135,7 @@ export class FileTreeFromIndexResource extends Resource { 'item.on': this.#fileTypeFilter ?? baseFileRef, ...(eq ? { eq } : {}), }, - fields: { 'search-entry': ['item.name'] }, + fields: { entry: ['item.name'] }, }; } @@ -154,7 +154,7 @@ export class FileTreeFromIndexResource extends Resource { for (let fileURL of fileURLs) { // Extract relative path from the file URL - // The search-entry id is the full URL like "http://localhost:4200/myworkspace/path/to/file.txt" + // The entry id is the full URL like "http://localhost:4200/myworkspace/path/to/file.txt" // We need just "path/to/file.txt" // Decode percent-encoded characters (e.g. emoji filenames appear as %F0%9F%8E%89 in URLs) let relativePath = decodeURIComponent( diff --git a/packages/host/app/resources/search-entries.ts b/packages/host/app/resources/search-entries.ts index ca03f4dae45..bd4383f0e62 100644 --- a/packages/host/app/resources/search-entries.ts +++ b/packages/host/app/resources/search-entries.ts @@ -28,7 +28,7 @@ import { type IconResource, type ResolvedCodeRef, type Saved, - type SearchEntryCollectionDocument, + type EntryCollectionDocument, type SearchEntryRendering, type SearchEntryWireQuery, } from '@cardstack/runtime-common'; @@ -51,7 +51,7 @@ const waiter = buildWaiter('search-entries-resource:search-waiter'); // here because this resource builds it and call sites import it from here. export type { SearchEntryRendering }; -// One search result, joined from the wire document: the `search-entry` +// One search result, joined from the wire document: the `entry` // resource plus the `html` renderings and/or `item` serialization it // references in `included`. An empty `html` array means the entry matched but // no rendering satisfies the query's htmlQuery yet — the invalidation re-run @@ -89,7 +89,7 @@ export class SearchEntriesResource extends Resource { private realmsToSearch: string[] = []; private subscriptions: { realm: string; unsubscribe: () => void }[] = []; private _entries = new TrackedArray(); - @tracked private _meta: SearchEntryCollectionDocument['meta'] = { + @tracked private _meta: EntryCollectionDocument['meta'] = { page: { total: 0 }, }; @tracked private _errors: ErrorEntry[] | undefined; @@ -369,7 +369,7 @@ export class SearchEntriesResource extends Resource { // The `css` resources base64-embed their whole stylesheet in the href; the // loader import is what registers each scoped stylesheet with the document, // so entries are paint-ready when exposed. - private async loadStylesheets(doc: SearchEntryCollectionDocument) { + private async loadStylesheets(doc: EntryCollectionDocument) { let hrefs = (doc.included ?? []) .filter(isCssResource) .map((resource) => resource.attributes.href); @@ -378,7 +378,7 @@ export class SearchEntriesResource extends Resource { ); } - private buildEntries(doc: SearchEntryCollectionDocument): SearchEntry[] { + private buildEntries(doc: EntryCollectionDocument): SearchEntry[] { let htmlById = new Map(); let cssHrefById = new Map(); let iconById = new Map(); @@ -475,7 +475,7 @@ function buildRendering( }; } -// The one host live-search resource: issues the `search-entry` wire query +// The one host live-search resource: issues the `entry` wire query // through `StoreService.searchEntries`, subscribes to each searched realm, // and re-runs on incremental index events with a per-realm partial refresh. // Realms ride in the query's `realms` member; omitted, every available realm diff --git a/packages/host/app/services/host-mode-service.ts b/packages/host/app/services/host-mode-service.ts index 9f22af39678..021869b647d 100644 --- a/packages/host/app/services/host-mode-service.ts +++ b/packages/host/app/services/host-mode-service.ts @@ -306,7 +306,7 @@ export default class HostModeService extends Service { } let searchURL = new URL('_federated-search', realmServerURL); let cardJsonURL = cardURL.endsWith('.json') ? cardURL : `${cardURL}.json`; - // The head markup is the `head` rendering of the card's `search-entry`: + // The head markup is the `head` rendering of the card's `entry`: // an html-only query at `html.format: head`, scoped to the single card. // The head HTML rides on the resolved `html` resource in `included`, // reached through the entry's `html` relationship. @@ -321,7 +321,7 @@ export default class HostModeService extends Service { realms: [realmRoot], cardUrls: [cardJsonURL], filter: { eq: { htmlQuery: { eq: { format: 'head' } } } }, - fields: { 'search-entry': ['html'] }, + fields: { entry: ['html'] }, }), }); diff --git a/packages/host/app/services/store.ts b/packages/host/app/services/store.ts index 20357df5528..4fdf2e4a038 100644 --- a/packages/host/app/services/store.ts +++ b/packages/host/app/services/store.ts @@ -29,7 +29,7 @@ import { isFileMetaResource, isSingleCardDocument, isSingleFileMetaDocument, - isSearchEntryCollectionDocument, + isEntryCollectionDocument, isSparseItemResource, resolveFileDefCodeRef, searchEntryWireQueryFromQuery, @@ -1027,7 +1027,7 @@ export default class StoreService extends Service implements StoreInterface { // Instances only: the query runs against the search requesting full // `item` serializations, the results hydrate into the store, and the caller - // gets instances back. For the raw search-entry wire format (HTML + // gets instances back. For the raw entry wire format (HTML // renderings, field-limited serializations, the document itself) use // `searchEntries` — that surface lives on this service only, never on the // `Store` interface cards receive. @@ -1053,7 +1053,7 @@ export default class StoreService extends Service implements StoreInterface { ): Promise { if ('asData' in query && query.asData) { throw new Error( - `store.search returns instances only — use store.searchEntries for the raw search-entry wire format`, + `store.search returns instances only — use store.searchEntries for the raw entry wire format`, ); } let searchRealms = this.normalizeSearchRealms(realms); @@ -1070,8 +1070,8 @@ export default class StoreService extends Service implements StoreInterface { return opts?.includeMeta ? result : result.instances; } - // The raw wire format: heterogeneous `search-entry` resources with the - // `html` / `item` branches the query's `fields[search-entry]` selects. + // The raw wire format: heterogeneous `entry` resources with the + // `html` / `item` branches the query's `fields[entry]` selects. // Nothing is hydrated into the store. async searchEntries( query: SearchEntryWireQuery, @@ -1091,7 +1091,7 @@ export default class StoreService extends Service implements StoreInterface { // the instance and could clobber a correctly-loaded full one — so the call // is a no-op for it; likewise an item carrying an error doc (`meta.error`), // which stands in for a card that failed to render and is not a real - // instance. `search-entry`s carry no serialization to deposit. Idempotent: + // instance. `entry`s carry no serialization to deposit. Idempotent: // depositing is skipped when the instance is already resident. async inflateSearchEntryItem( resource: CardResource | FileMetaResource, @@ -1123,7 +1123,7 @@ export default class StoreService extends Service implements StoreInterface { ): Promise<{ instances: T[]; meta: QueryResultsMeta }> { let collectionDoc = await this.fetchSearchDoc(query, realms); - // Hydrate each result into the store. The data-only search-entry doc + // Hydrate each result into the store. The data-only entry doc // carries one full `item` (`card`/`file-meta`) serialization per entry in // `included`, reached through the entry's `item` relationship. let items = this.itemResourcesFromSearchEntries(collectionDoc); @@ -1151,7 +1151,7 @@ export default class StoreService extends Service implements StoreInterface { // The instances path's resolved-document layer: the `Query` runs against // the search requesting full `item` serializations, and the resulting - // search-entry document (one `item` per entry in `included`) is what the + // entry document (one `item` per entry in `included`) is what the // hydration pipeline and the caches below consume. // Sits between `store.search` and `_federated-search`. // @@ -1268,7 +1268,7 @@ export default class StoreService extends Service implements StoreInterface { } // Extract the per-entry `item` (`card`/`file-meta`) serializations from a - // data-only search-entry document, in entry order: each entry's `item` + // data-only entry document, in entry order: each entry's `item` // relationship names a `(type, id)` resolved against `included`. private itemResourcesFromSearchEntries( doc: SearchEntryResults, @@ -1330,9 +1330,9 @@ export default class StoreService extends Service implements StoreInterface { throw err; } let json = await response.json(); - if (!isSearchEntryCollectionDocument(json)) { + if (!isEntryCollectionDocument(json)) { throw new Error( - `The realm search response was not a valid search-entry collection document: + `The realm search response was not a valid entry collection document: ${JSON.stringify(json, null, 2)}`, ); } diff --git a/packages/host/tests/acceptance/host-mode-test.gts b/packages/host/tests/acceptance/host-mode-test.gts index 5a6503d824a..946b08f5645 100644 --- a/packages/host/tests/acceptance/host-mode-test.gts +++ b/packages/host/tests/acceptance/host-mode-test.gts @@ -425,7 +425,7 @@ module('Acceptance | host mode tests', function (hooks) { // The published page talks to its realm server directly (cookie creds), so // the head prefetch goes through the global fetch rather than the virtual // network. Intercept the head query, assert its shape, and answer with a - // search-entry doc whose `html` resource carries the head markup so the + // entry doc whose `html` resource carries the head markup so the // injection path is exercised end-to-end. let cardUrl = `${testHostModeRealmURL}Pet/mango`; let htmlId = `${cardUrl}#head#${testHostModeRealmURL}pet/Pet`; @@ -441,7 +441,7 @@ module('Acceptance | host mode tests', function (hooks) { JSON.stringify({ data: [ { - type: 'search-entry', + type: 'entry', id: cardUrl, relationships: { html: { data: [{ type: 'html', id: htmlId }] }, @@ -486,7 +486,7 @@ module('Acceptance | host mode tests', function (hooks) { // htmlQuery, scoped to the visited card. assert.deepEqual( capturedHeadQuery?.fields, - { 'search-entry': ['html'] }, + { entry: ['html'] }, 'requests only the html branch', ); assert.strictEqual( diff --git a/packages/host/tests/helpers/realm-server-mock/routes.ts b/packages/host/tests/helpers/realm-server-mock/routes.ts index 0c7309854eb..57d577125c6 100644 --- a/packages/host/tests/helpers/realm-server-mock/routes.ts +++ b/packages/host/tests/helpers/realm-server-mock/routes.ts @@ -11,7 +11,7 @@ import { SupportedMimeType, X_BOXEL_LOGGING_CORRELATION_ID_HEADER, type RealmInfo, - type SearchEntryCollectionDocument, + type EntryCollectionDocument, type SearchEntryQuery, } from '@cardstack/runtime-common'; @@ -509,7 +509,7 @@ async function handleArchiveToggle( ); } -// The search-entry searchable-realm resolver. In-process registry +// The entry searchable-realm resolver. In-process registry // realms expose `searchEntries` directly; a live remote realm (base, skills, // catalog on localhost:4201) is reached by passing the original wire payload // through to its per-realm `_search` endpoint — the parsed query the @@ -523,7 +523,7 @@ function getSearchEntrySearchableRealmForURL( url?: string; searchEntries: ( searchEntryQuery: SearchEntryQuery, - ) => Promise; + ) => Promise; } | undefined { let registry = getTestRealmRegistry(); @@ -561,7 +561,7 @@ function getSearchEntrySearchableRealmForURL( `Remote realm search failed for ${resolvedRealmURL}: ${response.status} ${responseText}`, ); } - return (await response.json()) as SearchEntryCollectionDocument; + return (await response.json()) as EntryCollectionDocument; }, }; } diff --git a/packages/host/tests/helpers/search-cards.ts b/packages/host/tests/helpers/search-cards.ts index 850cc25b7cc..1602b82b95d 100644 --- a/packages/host/tests/helpers/search-cards.ts +++ b/packages/host/tests/helpers/search-cards.ts @@ -9,7 +9,7 @@ import { } from '@cardstack/runtime-common'; // Test-only: fetch the card/file-meta serializations matching a card-rooted -// `Query` through the search-entry engine, returning them in the +// `Query` through the entry engine, returning them in the // `{ data, included, meta }` collection shape index assertions read. Requests // the data-only fieldset (one full `item` per entry); the top-level items land // in `data`, their transitively-linked resources in `included`. @@ -28,7 +28,7 @@ export async function searchCardsForTest( ), opts, ); - // Key by the full `(type, id)` the search-entry `item` relationship carries, + // Key by the full `(type, id)` the entry `item` relationship carries, // not `id` alone — matches the wire contract (and the store's resolver). let itemKeys = new Set(); for (let entry of doc.data) { diff --git a/packages/host/tests/integration/components/card-context-search-results-test.gts b/packages/host/tests/integration/components/card-context-search-results-test.gts index 09dc75ce8a9..3eab77340db 100644 --- a/packages/host/tests/integration/components/card-context-search-results-test.gts +++ b/packages/host/tests/integration/components/card-context-search-results-test.gts @@ -142,7 +142,7 @@ module( await getService('realm').login(testRealmURL); }); - test('a card renders the search-entry stream via @context.searchResultsComponent', async function (assert) { + test('a card renders the entry stream via @context.searchResultsComponent', async function (assert) { let query: SearchEntryWireQuery = { filter: { 'item.on': bookRef }, realms: [testRealmURL], @@ -188,7 +188,7 @@ module( ); }); - test('the converged @context exposes the search-entry + deprecated rendering surfaces and the instances surface', async function (assert) { + test('the converged @context exposes the entry + deprecated rendering surfaces and the instances surface', async function (assert) { // The yielded `@context` carries both rendering surfaces and the // instances surface at once — a card author reads them straight off // `@context`. The compile-time witnesses below pin the same shape at the diff --git a/packages/host/tests/integration/components/search-results-test.gts b/packages/host/tests/integration/components/search-results-test.gts index 26147280b3f..4e343476554 100644 --- a/packages/host/tests/integration/components/search-results-test.gts +++ b/packages/host/tests/integration/components/search-results-test.gts @@ -21,11 +21,11 @@ import { GetCardContextName, HtmlResourceType, IconResourceType, - SearchEntryResourceType, + EntryResourceType, type CardResource, type Loader, type Saved, - type SearchEntryIncludedResource, + type EntryIncludedResource, type SearchEntryResults, type SearchEntryWireQuery, } from '@cardstack/runtime-common'; @@ -88,10 +88,10 @@ function renderingIdFor(url: string): string { return htmlResourceId({ url, format: 'fitted', renderType: bookRef }); } -// The `search-entry` resource pointing at a prerendered rendering. +// The `entry` resource pointing at a prerendered rendering. function htmlEntryResource(url: string): SearchEntryWireResource { return { - type: SearchEntryResourceType, + type: EntryResourceType, id: url, relationships: { html: { data: [{ type: HtmlResourceType, id: renderingIdFor(url) }] }, @@ -104,7 +104,7 @@ function htmlIncluded( url: string, html: string, isError = false, -): SearchEntryIncludedResource[] { +): EntryIncludedResource[] { return [ { type: HtmlResourceType, @@ -128,10 +128,10 @@ function htmlIncluded( ]; } -// The `search-entry` resource pointing at an `item` serialization. +// The `entry` resource pointing at an `item` serialization. function itemEntryResource(url: string): SearchEntryWireResource { return { - type: SearchEntryResourceType, + type: EntryResourceType, id: url, relationships: { item: { data: { type: 'card', id: url } } }, }; @@ -184,9 +184,7 @@ function errorItem(url: string, message: string): CardResource { // `html` string absent. With no item alongside it, the row has nothing to // render but its error state — the host error component, with a generic // message (no error doc rode along). -function htmlIncludedNoLastKnownGood( - url: string, -): SearchEntryIncludedResource[] { +function htmlIncludedNoLastKnownGood(url: string): EntryIncludedResource[] { return [ { type: HtmlResourceType, @@ -372,7 +370,7 @@ module('Integration | Component | search-results', function (hooks) { // operator-mode overlay / adorn tab reads, sourced without loading the // instance. let withIcon = (url: string): SearchEntryWireResource => ({ - type: SearchEntryResourceType, + type: EntryResourceType, id: url, relationships: { html: { data: [{ type: HtmlResourceType, id: renderingIdFor(url) }] }, @@ -495,7 +493,7 @@ module('Integration | Component | search-results', function (hooks) { try { let query: SearchEntryWireQuery = { filter: { 'item.on': bookRef }, - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, realms: [testRealmURL], }; await render( diff --git a/packages/host/tests/integration/realm-test.gts b/packages/host/tests/integration/realm-test.gts index 0b8d48a1dbd..be6fa76a109 100644 --- a/packages/host/tests/integration/realm-test.gts +++ b/packages/host/tests/integration/realm-test.gts @@ -3135,7 +3135,7 @@ module('Integration | realm', function (hooks) { let mangoCreatedAt = await getFileCreatedAt(realm, 'dir/mango.json'); let marikoCreatedAt = await getFileCreatedAt(realm, 'dir/mariko.json'); let vanGoghCreatedAt = await getFileCreatedAt(realm, 'dir/vanGogh.json'); - // `/_search` returns `search-entry` resources in `data` (each just an + // `/_search` returns `entry` resources in `data` (each just an // id + refs); the full card resources — the matched results themselves and // their `loadLinks`-expanded relationship targets — travel in `included`. let entries = json.data as any[]; diff --git a/packages/host/tests/integration/resources/search-entries-test.gts b/packages/host/tests/integration/resources/search-entries-test.gts index 408e2d97453..cc370f2135c 100644 --- a/packages/host/tests/integration/resources/search-entries-test.gts +++ b/packages/host/tests/integration/resources/search-entries-test.gts @@ -12,7 +12,7 @@ import { htmlResourceId, CssResourceType, HtmlResourceType, - SearchEntryResourceType, + EntryResourceType, type Loader, type Realm, type SearchEntryResults, @@ -186,14 +186,14 @@ module('Integration | search-entries resource', function (hooks) { let doc: SearchEntryResults = { data: [ { - type: SearchEntryResourceType, + type: EntryResourceType, id: itemFileUrl, relationships: { item: { data: { type: 'file-meta', id: itemFileUrl } }, }, }, { - type: SearchEntryResourceType, + type: EntryResourceType, id: htmlFileUrl, relationships: { html: { data: [{ type: HtmlResourceType, id: renderingId }] }, @@ -251,7 +251,7 @@ module('Integration | search-entries resource', function (hooks) { named: { query: { filter: { 'item.on': bookRef }, - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, realms: [testRealmURL], }, }, @@ -370,7 +370,7 @@ module('Integration | search-entries resource', function (hooks) { let unrenderedDoc: SearchEntryResults = { data: [ { - type: SearchEntryResourceType, + type: EntryResourceType, id: entryURL, relationships: { html: { data: [] } }, }, @@ -380,7 +380,7 @@ module('Integration | search-entries resource', function (hooks) { let renderedDoc: SearchEntryResults = { data: [ { - type: SearchEntryResourceType, + type: EntryResourceType, id: entryURL, relationships: { html: { data: [{ type: HtmlResourceType, id: renderingId }] }, diff --git a/packages/host/tests/integration/store-search-test.gts b/packages/host/tests/integration/store-search-test.gts index 9cc9f8259ff..99c5ec11e10 100644 --- a/packages/host/tests/integration/store-search-test.gts +++ b/packages/host/tests/integration/store-search-test.gts @@ -126,18 +126,18 @@ module('Integration | store search public API', function (hooks) { ); }); - test('searchEntries returns the raw search-entry wire format without hydrating', async function (assert) { + test('searchEntries returns the raw entry wire format without hydrating', async function (assert) { let doc = await storeService.searchEntries( { filter: { 'item.on': bookRef }, - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, }, [testRealmURL], ); assert.strictEqual(doc.data.length, 2, 'both books are returned'); for (let entry of doc.data) { - assert.strictEqual(entry.type, 'search-entry'); + assert.strictEqual(entry.type, 'entry'); assert.strictEqual( entry.relationships.item?.data.type, 'card', @@ -173,7 +173,7 @@ module('Integration | store search public API', function (hooks) { let doc = await storeService.searchEntries( { filter: { 'item.on': bookRef }, - fields: { 'search-entry': ['item.title'] }, + fields: { entry: ['item.title'] }, }, [testRealmURL], ); @@ -200,7 +200,7 @@ module('Integration | store search public API', function (hooks) { let doc = await storeService.searchEntries( { filter: { 'item.on': baseFileRef }, - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, }, [testRealmURL], ); diff --git a/packages/host/tests/integration/store-test.gts b/packages/host/tests/integration/store-test.gts index e5fd238da1b..f1463b36fc5 100644 --- a/packages/host/tests/integration/store-test.gts +++ b/packages/host/tests/integration/store-test.gts @@ -2005,7 +2005,7 @@ module('Integration | Store', function (hooks) { }); } - // A search-entry that carries only an `html` rendering — no `item`. + // An entry that carries only an `html` rendering — no `item`. function htmlOnlyEntryDoc(id: string, opts?: { isFileMeta?: boolean }) { let htmlId = opts?.isFileMeta ? `${id}#fitted` @@ -2013,7 +2013,7 @@ module('Integration | Store', function (hooks) { return { data: [ { - type: 'search-entry', + type: 'entry', id, relationships: { html: { data: [{ type: 'html', id: htmlId }] }, diff --git a/packages/host/tests/unit/store-card-boundary-test.ts b/packages/host/tests/unit/store-card-boundary-test.ts index 88e4c1cab38..e86c189c5d2 100644 --- a/packages/host/tests/unit/store-card-boundary-test.ts +++ b/packages/host/tests/unit/store-card-boundary-test.ts @@ -8,7 +8,7 @@ import type { CardDef } from 'https://cardstack.com/base/card-api'; // The card boundary, codified at the type level: the `Store` interface cards // receive via `@context.store` exposes instances-level search only. The raw -// search-entry wire format (`searchEntries`) lives on the host `StoreService` +// entry wire format (`searchEntries`) lives on the host `StoreService` // and is deliberately unreachable through the cards' interface. These // assertions fail the type-check (and so the test suite) if that boundary // ever erodes. diff --git a/packages/realm-server/handlers/handle-search.ts b/packages/realm-server/handlers/handle-search.ts index 6e873714643..5fe73069532 100644 --- a/packages/realm-server/handlers/handle-search.ts +++ b/packages/realm-server/handlers/handle-search.ts @@ -35,8 +35,8 @@ import { sanitizePrerenderJobId, } from '../prerender/prerender-constants.ts'; -// The federated search: the search-entry wire model over every requested -// realm. Parses the search-entry-rooted query (the `item.` membership query, +// The federated search: the entry wire model over every requested +// realm. Parses the entry-rooted query (the `item.` membership query, // the `htmlQuery` binding, the sparse fieldset), fans out to each realm's // `searchEntries`, and merges the per-realm documents (`included` deduped by // `(type, id)`). Cache + ETag ride the job-scoped search-cache protocol; the @@ -151,7 +151,7 @@ export default function handleSearch(opts: { ? await timings.time('resolveRealms', resolveRealms) : await resolveRealms(); let doc = await searchEntryRealms(realmInstances, parsed, runSearchOpts); - // Serialize compact: a search-entry doc can run to many MB, so indentation + // Serialize compact: an entry doc can run to many MB, so indentation // whitespace is pure wire overhead the consumer parses straight back off. let stringify = async () => JSON.stringify(doc); return timings ? await timings.time('stringify', stringify) : stringify(); diff --git a/packages/realm-server/scripts/bench-realm/bench.ts b/packages/realm-server/scripts/bench-realm/bench.ts index 6d8ad9794f4..3b53dc80e93 100644 --- a/packages/realm-server/scripts/bench-realm/bench.ts +++ b/packages/realm-server/scripts/bench-realm/bench.ts @@ -180,7 +180,7 @@ function searchRequest( 'Content-Type': 'application/json', Authorization: `Bearer ${bearerToken}`, }, - // The search endpoint takes a search-entry-rooted query; benchmark the + // The search endpoint takes an entry-rooted query; benchmark the // data-only fieldset (one full `item` per result), the closest analogue // to the legacy live-card search response. body: JSON.stringify( diff --git a/packages/realm-server/tests/helpers/index.ts b/packages/realm-server/tests/helpers/index.ts index 111057c9c8f..8452f17648a 100644 --- a/packages/realm-server/tests/helpers/index.ts +++ b/packages/realm-server/tests/helpers/index.ts @@ -112,7 +112,7 @@ function environmentPortOffset(): number { /** Return a test port, shifted by a per-environment offset when needed. */ // Test-only: fetch the card/file-meta serializations matching a card-rooted -// `Query` through the search-entry engine, returning them in the +// `Query` through the entry engine, returning them in the // `{ data, meta }` collection shape index assertions read. Requests the // data-only fieldset (one full `item` per entry). export async function searchCardsForTest( @@ -133,7 +133,7 @@ export async function searchCardsForTest( // The top-level result items (one per entry, by the entry's `item` rel) land // in `data`; every other linked card/file-meta resource is sideloaded in // `included` — the legacy collection shape these assertions read. - // Key by the full `(type, id)` the search-entry `item` relationship carries, + // Key by the full `(type, id)` the entry `item` relationship carries, // not `id` alone — matches the wire contract (and the store's resolver). let itemKeys = new Set(); for (let entry of doc.data) { diff --git a/packages/realm-server/tests/realm-endpoints/search-test.ts b/packages/realm-server/tests/realm-endpoints/search-test.ts index b7bef15b729..18bdb7e5c67 100644 --- a/packages/realm-server/tests/realm-endpoints/search-test.ts +++ b/packages/realm-server/tests/realm-endpoints/search-test.ts @@ -159,10 +159,10 @@ module(`realm-endpoints/${basename(import.meta.filename)}`, function () { } }); - test('fields[search-entry]=item: full serializations, htmlQuery inert', async function (assert) { + test('fields[entry]=item: full serializations, htmlQuery inert', async function (assert) { let response = await postSearch({ filter: personFilter({ htmlQuery: { eq: { format: 'embedded' } } }), - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, }); assert.strictEqual(response.status, 200); let json = response.body; @@ -187,10 +187,10 @@ module(`realm-endpoints/${basename(import.meta.filename)}`, function () { ); }); - test('fields[search-entry]=item.: sparse items carry meta.sparseFields', async function (assert) { + test('fields[entry]=item.: sparse items carry meta.sparseFields', async function (assert) { let response = await postSearch({ filter: personFilter(), - fields: { 'search-entry': ['item.firstName'] }, + fields: { entry: ['item.firstName'] }, }); assert.strictEqual(response.status, 200); let item = response.body.included.find( @@ -201,10 +201,10 @@ module(`realm-endpoints/${basename(import.meta.filename)}`, function () { assert.deepEqual(item.meta.sparseFields, ['firstName']); }); - test('fields[search-entry]=html,item: both branches on every entry', async function (assert) { + test('fields[entry]=html,item: both branches on every entry', async function (assert) { let response = await postSearch({ filter: personFilter(), - fields: { 'search-entry': ['html', 'item'] }, + fields: { entry: ['html', 'item'] }, }); assert.strictEqual(response.status, 200); let entry = response.body.data.find( @@ -234,7 +234,7 @@ module(`realm-endpoints/${basename(import.meta.filename)}`, function () { // a pinned html branch keeps membership visible with an empty array let pinned = await postSearch({ filter: personFilter(), - fields: { 'search-entry': ['html'] }, + fields: { entry: ['html'] }, }); let pinnedJane = pinned.body.data.find( (e: { id: string }) => e.id === janeId, diff --git a/packages/realm-server/tests/search-entries-engine-test.ts b/packages/realm-server/tests/search-entries-engine-test.ts index af2caa1ccb1..0e2de264295 100644 --- a/packages/realm-server/tests/search-entries-engine-test.ts +++ b/packages/realm-server/tests/search-entries-engine-test.ts @@ -11,8 +11,8 @@ import { type HtmlResource, type IconResource, type Realm, - type SearchEntryCollectionDocument, - type SearchEntryResource, + type EntryCollectionDocument, + type EntryResource, } from '@cardstack/runtime-common'; import type { PgAdapter } from '@cardstack/postgres'; import { @@ -21,7 +21,7 @@ import { } from './helpers/index.ts'; function htmlIn( - doc: SearchEntryCollectionDocument, + doc: EntryCollectionDocument, id: string, ): HtmlResource | undefined { return doc.included?.find( @@ -37,7 +37,7 @@ function normalizedHtml(resource: HtmlResource): string { } function itemIn( - doc: SearchEntryCollectionDocument, + doc: EntryCollectionDocument, id: string, ): CardResource | FileMetaResource | undefined { return doc.included?.find( @@ -47,30 +47,30 @@ function itemIn( ); } -function cssIn(doc: SearchEntryCollectionDocument): CssResource[] { +function cssIn(doc: EntryCollectionDocument): CssResource[] { return (doc.included ?? []).filter( (resource): resource is CssResource => resource.type === 'css', ); } -function iconsIn(doc: SearchEntryCollectionDocument): IconResource[] { +function iconsIn(doc: EntryCollectionDocument): IconResource[] { return (doc.included ?? []).filter( (resource): resource is IconResource => resource.type === 'icon', ); } -function iconIdOf(entry: SearchEntryResource): string | undefined { +function iconIdOf(entry: EntryResource): string | undefined { return entry.relationships.icon?.data.id; } function entryFor( - doc: SearchEntryCollectionDocument, + doc: EntryCollectionDocument, id: string, -): SearchEntryResource | undefined { +): EntryResource | undefined { return doc.data.find((entry) => entry.id === id); } -function htmlIdsOf(entry: SearchEntryResource): string[] | undefined { +function htmlIdsOf(entry: EntryResource): string[] | undefined { return entry.relationships.html?.data.map((member) => member.id); } @@ -321,7 +321,7 @@ module(basename(import.meta.filename), function () { let doc = await testRealm.realmIndexQueryEngine.searchEntries( personQuery({ filterEq: { htmlQuery: { eq: { format: 'head' } } }, - fields: { 'search-entry': ['html'] }, + fields: { entry: ['html'] }, }), ); assert.deepEqual(doc.meta.htmlQuery, { eq: { format: 'head' } }); @@ -344,7 +344,7 @@ module(basename(import.meta.filename), function () { parseSearchEntryQueryFromPayload({ cardUrls: [`${johnId}.json`], filter: { eq: { htmlQuery: { eq: { format: 'head' } } } }, - fields: { 'search-entry': ['html'] }, + fields: { entry: ['html'] }, }), ); assert.strictEqual( @@ -411,13 +411,13 @@ module(basename(import.meta.filename), function () { ); }); - test('fields[search-entry]=item: full serializations, no html, htmlQuery inert', async function (assert) { + test('fields[entry]=item: full serializations, no html, htmlQuery inert', async function (assert) { let doc = await testRealm.realmIndexQueryEngine.searchEntries( personQuery({ // an htmlQuery alongside an item-only fieldset is inert, not an // error filterEq: { htmlQuery: { eq: { format: 'embedded' } } }, - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, }), ); let entry = entryFor(doc, johnId)!; @@ -449,18 +449,18 @@ module(basename(import.meta.filename), function () { ); }); - test('fields[search-entry]=item.: sparse items carry meta.sparseFields', async function (assert) { + test('fields[entry]=item.: sparse items carry meta.sparseFields', async function (assert) { let doc = await testRealm.realmIndexQueryEngine.searchEntries( - personQuery({ fields: { 'search-entry': ['item.firstName'] } }), + personQuery({ fields: { entry: ['item.firstName'] } }), ); let item = itemIn(doc, johnId)!; assert.deepEqual(item.attributes, { firstName: 'John' }); assert.deepEqual(item.meta.sparseFields, ['firstName']); }); - test('fields[search-entry]=html,item: both branches on every entry', async function (assert) { + test('fields[entry]=html,item: both branches on every entry', async function (assert) { let doc = await testRealm.realmIndexQueryEngine.searchEntries( - personQuery({ fields: { 'search-entry': ['html', 'item'] } }), + personQuery({ fields: { entry: ['html', 'item'] } }), ); let entry = entryFor(doc, johnId)!; let htmlId = `${johnId}#fitted#${personKey}`; @@ -524,7 +524,7 @@ module(basename(import.meta.filename), function () { // a pinned html branch keeps membership visible with an empty array let pinned = await testRealm.realmIndexQueryEngine.searchEntries( - personQuery({ fields: { 'search-entry': ['html'] } }), + personQuery({ fields: { entry: ['html'] } }), ); let pinnedJane = entryFor(pinned, janeId)!; assert.deepEqual( @@ -567,7 +567,7 @@ module(basename(import.meta.filename), function () { 'item.on': { module: baseRRI('card-api'), name: 'FileDef' }, eq: { 'item.url': fileUrl }, }, - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, }); let doc = await testRealm.realmIndexQueryEngine.searchEntries(query); let entry = entryFor(doc, fileUrl)!; diff --git a/packages/realm-server/tests/search-entry-test.ts b/packages/realm-server/tests/search-entry-test.ts index d8b5170d615..bd0ac0f796b 100644 --- a/packages/realm-server/tests/search-entry-test.ts +++ b/packages/realm-server/tests/search-entry-test.ts @@ -4,7 +4,7 @@ import { basename } from 'path'; import { buildHtmlResource, buildIconResource, - buildSearchEntryResource, + buildEntryResource, buildSparseItemResource, htmlResourceId, cssResourceId, @@ -12,8 +12,8 @@ import { htmlQueryMatches, isHtmlResource, isIconResource, - isSearchEntryCollectionDocument, - isSearchEntryResource, + isEntryCollectionDocument, + isEntryResource, isSparseItemResource, parseSearchEntryQueryFromPayload, resolveHtmlQuery, @@ -81,8 +81,8 @@ const universe: RenderingCandidate[] = [ ]; module(basename(import.meta.filename), function () { - module('search-entry query parser', function () { - test('translates the canonical search-entry query', function (assert) { + module('entry query parser', function () { + test('translates the canonical entry query', function (assert) { let htmlQuery: HtmlQuery = { every: [ { eq: { format: 'embedded' } }, @@ -100,7 +100,7 @@ module(basename(import.meta.filename), function () { sort: [{ by: 'item.title', direction: 'asc' }], page: { size: 20 }, realms: ['http://localhost:4201/test'], - fields: { 'search-entry': ['html'] }, + fields: { entry: ['html'] }, }); assert.deepEqual(parsed.itemQuery, { filter: { on: authorRef, eq: { status: 'ready' } }, @@ -258,13 +258,13 @@ module(basename(import.meta.filename), function () { test('sparse fieldsets parse to the item selection', function (assert) { assert.deepEqual( parseSearchEntryQueryFromPayload({ - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, }).fieldset, { html: false, item: { kind: 'full' }, itemAsFallback: false }, ); assert.deepEqual( parseSearchEntryQueryFromPayload({ - fields: { 'search-entry': ['item.title', 'item.status'] }, + fields: { entry: ['item.title', 'item.status'] }, }).fieldset, { html: false, @@ -274,7 +274,7 @@ module(basename(import.meta.filename), function () { ); assert.deepEqual( parseSearchEntryQueryFromPayload({ - fields: { 'search-entry': ['html', 'item'] }, + fields: { entry: ['html', 'item'] }, }).fieldset, { html: true, item: { kind: 'full' }, itemAsFallback: false }, ); @@ -287,22 +287,22 @@ module(basename(import.meta.filename), function () { 'bare field path', ); assert.strictEqual( - parseError({ fields: { 'search-entry': ['item', 'item.title'] } }).code, + parseError({ fields: { entry: ['item', 'item.title'] } }).code, 'invalid-query', 'full item cannot combine with item.', ); assert.strictEqual( - parseError({ fields: { 'search-entry': ['html.cardType'] } }).code, + parseError({ fields: { entry: ['html.cardType'] } }).code, 'invalid-query', 'html does not dot deeper in a fieldset', ); assert.strictEqual( parseError({ fields: { card: ['title'] } }).code, 'invalid-query', - 'only the search-entry type is selectable', + 'only the entry type is selectable', ); assert.strictEqual( - parseError({ fields: { 'search-entry': [] } }).code, + parseError({ fields: { entry: [] } }).code, 'invalid-query', 'empty fieldset', ); @@ -442,39 +442,38 @@ module(basename(import.meta.filename), function () { }); }); - module('search-entry collection document guard', function () { - let entry = () => - buildSearchEntryResource({ url: cardUrl, itemType: 'card' }); + module('entry collection document guard', function () { + let entry = () => buildEntryResource({ url: cardUrl, itemType: 'card' }); let meta = { page: { total: 1 } }; test('accepts a well-formed document, with and without included', function (assert) { - assert.true(isSearchEntryCollectionDocument({ data: [entry()], meta })); + assert.true(isEntryCollectionDocument({ data: [entry()], meta })); assert.true( - isSearchEntryCollectionDocument({ + isEntryCollectionDocument({ data: [entry()], included: [{ type: 'card', id: cardUrl, attributes: {}, meta: {} }], meta, }), ); - assert.true(isSearchEntryCollectionDocument({ data: [], meta })); + assert.true(isEntryCollectionDocument({ data: [], meta })); }); test('rejects malformed data and included members', function (assert) { - assert.false(isSearchEntryCollectionDocument(null)); - assert.false(isSearchEntryCollectionDocument({ data: [entry()] })); + assert.false(isEntryCollectionDocument(null)); + assert.false(isEntryCollectionDocument({ data: [entry()] })); assert.false( - isSearchEntryCollectionDocument({ data: 'nope', meta }), + isEntryCollectionDocument({ data: 'nope', meta }), 'data must be an array', ); assert.false( - isSearchEntryCollectionDocument({ + isEntryCollectionDocument({ data: [{ type: 'card', id: cardUrl }], meta, }), - 'data members must be search-entry resources', + 'data members must be entry resources', ); assert.false( - isSearchEntryCollectionDocument({ + isEntryCollectionDocument({ data: [entry()], included: 'nope', meta, @@ -482,7 +481,7 @@ module(basename(import.meta.filename), function () { 'a present included must be an array', ); assert.false( - isSearchEntryCollectionDocument({ + isEntryCollectionDocument({ data: [entry()], included: [{ attributes: {} }], meta, @@ -633,21 +632,21 @@ module(basename(import.meta.filename), function () { }); }); - module('search-entry builders', function () { - test('buildSearchEntryResource links the requested branches', function (assert) { + module('entry builders', function () { + test('buildEntryResource links the requested branches', function (assert) { let htmlId = htmlResourceId({ url: cardUrl, format: 'fitted', renderType: authorRef, }); - let both = buildSearchEntryResource({ + let both = buildEntryResource({ url: cardUrl, htmlIds: [htmlId], itemType: 'card', iconId: `${authorRef.module}/${authorRef.name}`, }); assert.deepEqual(both, { - type: 'search-entry', + type: 'entry', id: cardUrl, relationships: { html: { data: [{ type: 'html', id: htmlId }] }, @@ -660,20 +659,20 @@ module(basename(import.meta.filename), function () { }, }, }); - assert.true(isSearchEntryResource(both)); + assert.true(isEntryResource(both)); // a pinned html branch with no matching rendering: empty array - let empty = buildSearchEntryResource({ url: cardUrl, htmlIds: [] }); + let empty = buildEntryResource({ url: cardUrl, htmlIds: [] }); assert.deepEqual(empty.relationships.html, { data: [] }); - assert.true(isSearchEntryResource(empty)); + assert.true(isEntryResource(empty)); // the default mode's fallback rows omit the relationship entirely - let itemOnly = buildSearchEntryResource({ + let itemOnly = buildEntryResource({ url: cardUrl, itemType: 'card', }); assert.deepEqual(Object.keys(itemOnly.relationships), ['item']); - assert.true(isSearchEntryResource(itemOnly)); + assert.true(isEntryResource(itemOnly)); }); test('buildHtmlResource carries the rendering attributes and styles', function (assert) { diff --git a/packages/realm-server/tests/server-endpoints/search-test.ts b/packages/realm-server/tests/server-endpoints/search-test.ts index 7c2664da1af..bf6ab82e275 100644 --- a/packages/realm-server/tests/server-endpoints/search-test.ts +++ b/packages/realm-server/tests/server-endpoints/search-test.ts @@ -174,7 +174,7 @@ module(`server-endpoints/${basename(import.meta.filename)}`, function (_hooks) { .send(body); } - test('QUERY /_federated-search federates search-entry results across realms', async function (assert) { + test('QUERY /_federated-search federates entry results across realms', async function (assert) { let response = await postSearch({ filter: personFilter(), realms: [testRealm.url, secondaryRealm.url], @@ -329,7 +329,7 @@ module(`server-endpoints/${basename(import.meta.filename)}`, function (_hooks) { let differentFields = await post({ ...baseBody, - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, }); assert.notStrictEqual( differentFields.headers['etag'], @@ -352,7 +352,7 @@ module(`server-endpoints/${basename(import.meta.filename)}`, function (_hooks) { // an inert htmlQuery (fieldset without html) does not key the cache: // equivalent bodies share one entry + ETag - let itemFields = { 'search-entry': ['item'] }; + let itemFields = { entry: ['item'] }; let inertA = await post({ ...baseBody, fields: itemFields }); let inertB = await post({ ...baseBody, diff --git a/packages/realm-server/tests/superseded-search-surface-removed-test.ts b/packages/realm-server/tests/superseded-search-surface-removed-test.ts index 45c4538e91b..78afa5c6b49 100644 --- a/packages/realm-server/tests/superseded-search-surface-removed-test.ts +++ b/packages/realm-server/tests/superseded-search-surface-removed-test.ts @@ -5,7 +5,7 @@ import { readFileSync } from 'fs'; import { resolve } from 'path'; // A grep-style guard that the superseded search scaffolding stays -// removed. The platform's search relationships live on `search-entry`, so the +// removed. The platform's search relationships live on `entry`, so the // superseded in-place additions to the card resource and the old result mappers must // not reappear. Each entry asserts a removed identifier is absent from the // source file that used to define it. @@ -19,7 +19,7 @@ function source(relativePath: string): string { const GUARDS: { file: string; forbidden: string[] }[] = [ { // The `rendered-html` resource type, its on-`card` relationship, and the - // identity-only marker — superseded by the `search-entry` → `html` / `item` + // identity-only marker — superseded by the `entry` → `html` / `item` // model. file: 'runtime-common/resource-types.ts', forbidden: ['RenderedHtmlResource', "'rendered-html'", 'identityOnly'], diff --git a/packages/runtime-common/card-document-shape.ts b/packages/runtime-common/card-document-shape.ts index ed274d4b229..d84bea1b08a 100644 --- a/packages/runtime-common/card-document-shape.ts +++ b/packages/runtime-common/card-document-shape.ts @@ -31,7 +31,7 @@ import type { Meta, Relationship, Saved, - SearchEntryResource, + EntryResource, } from './resource-types.ts'; import type { CardCollectionDocument, @@ -47,7 +47,7 @@ import type { const CardResourceType: CardResource['type'] = 'card'; const FileMetaResourceType: FileMetaResource['type'] = 'file-meta'; const CssResourceType: CssResource['type'] = 'css'; -const SearchEntryResourceType: SearchEntryResource['type'] = 'search-entry'; +const EntryResourceType: EntryResource['type'] = 'entry'; const HtmlResourceType: HtmlResource['type'] = 'html'; const IconResourceType: IconResource['type'] = 'icon'; @@ -326,13 +326,11 @@ export function isIconResource(resource: any): resource is IconResource { ); } -export function isSearchEntryResource( - resource: any, -): resource is SearchEntryResource { +export function isEntryResource(resource: any): resource is EntryResource { if (typeof resource !== 'object' || resource == null) { return false; } - if (resource.type !== SearchEntryResourceType) { + if (resource.type !== EntryResourceType) { return false; } if (typeof resource.id !== 'string') { diff --git a/packages/runtime-common/document-types.ts b/packages/runtime-common/document-types.ts index e33f6d92e3e..b1711ddd998 100644 --- a/packages/runtime-common/document-types.ts +++ b/packages/runtime-common/document-types.ts @@ -8,11 +8,11 @@ import { type HtmlResource, type IconResource, type Saved, - type SearchEntryResource, + type EntryResource, type Unsaved, isCardResource, isFileMetaResource, - isSearchEntryResource, + isEntryResource, } from './resource-types.ts'; export interface SingleCardDocument { @@ -25,21 +25,21 @@ export interface CardCollectionDocument { meta: QueryResultsMeta; } -// The search response: heterogeneous `search-entry` resources in `data`, +// The search response: heterogeneous `entry` resources in `data`, // with everything they compose — `html` renderings (plus their deduped `css` // stylesheets) and/or `card`/`file-meta` `item` serializations — riding in // `included`. Which branches appear per entry is governed by the query's // sparse fieldset (default: prefer `html`, fall back to `item`). -export type SearchEntryIncludedResource = +export type EntryIncludedResource = | HtmlResource | CssResource | IconResource | CardResource | FileMetaResource; -export interface SearchEntryCollectionDocument { - data: SearchEntryResource[]; - included?: SearchEntryIncludedResource[]; +export interface EntryCollectionDocument { + data: EntryResource[]; + included?: EntryIncludedResource[]; meta: QueryResultsMeta & { // The applied (bound or defaulted) htmlQuery, echoed once at the document // level — it cannot vary across entries, so it is never repeated per @@ -48,9 +48,9 @@ export interface SearchEntryCollectionDocument { }; } -// The public-API name for the raw search-entry wire format a programmatic +// The public-API name for the raw entry wire format a programmatic // `searchEntries` caller receives. -export type SearchEntryResults = SearchEntryCollectionDocument; +export type SearchEntryResults = EntryCollectionDocument; export interface SingleFileMetaDocument { data: FileMetaResource; @@ -113,9 +113,9 @@ export function isFileMetaCollectionDocument( return data.every((resource) => isFileMetaResource(resource)); } -export function isSearchEntryCollectionDocument( +export function isEntryCollectionDocument( doc: any, -): doc is SearchEntryCollectionDocument { +): doc is EntryCollectionDocument { if (typeof doc !== 'object' || doc == null) { return false; } @@ -147,7 +147,7 @@ export function isSearchEntryCollectionDocument( } } } - return data.every((resource) => isSearchEntryResource(resource)); + return data.every((resource) => isEntryResource(resource)); } export type CardTypeSummaryKind = 'instance' | 'file'; diff --git a/packages/runtime-common/index.ts b/packages/runtime-common/index.ts index 11893571704..783f2b9c443 100644 --- a/packages/runtime-common/index.ts +++ b/packages/runtime-common/index.ts @@ -882,8 +882,8 @@ export type { SingleFileMetaDocument, CardCollectionDocument, FileMetaCollectionDocument, - SearchEntryCollectionDocument, - SearchEntryIncludedResource, + EntryCollectionDocument, + EntryIncludedResource, SearchEntryResults, } from './document-types.ts'; export type { @@ -904,7 +904,7 @@ export { isSingleCardDocument, isSingleFileMetaDocument, isFileMetaCollectionDocument, - isSearchEntryCollectionDocument, + isEntryCollectionDocument, isCardDocumentString, } from './document-types.ts'; export { diff --git a/packages/runtime-common/query-field-utils.ts b/packages/runtime-common/query-field-utils.ts index c5b8f76e2b6..a48f1bc826a 100644 --- a/packages/runtime-common/query-field-utils.ts +++ b/packages/runtime-common/query-field-utils.ts @@ -322,9 +322,9 @@ export function buildQuerySearchURL(realmHref: string, query: Query): string { let searchURL = new URL('./_search', baseHref); searchURL.searchParams.set('realms', baseHref); // A query-backed field resolves to linked instances, so it asks the - // search-entry engine for a data-only projection: each entry carries its + // entry engine for a data-only projection: each entry carries its // full `item` (`card`/`file-meta`) serialization, no prerendered HTML. - searchURL.searchParams.set('fields[search-entry]', 'item'); + searchURL.searchParams.set('fields[entry]', 'item'); let normalizedQuery = normalizeQueryForSignature(query); searchURL.searchParams.set('query', buildQueryParamValue(normalizedQuery)); return searchURL.href; diff --git a/packages/runtime-common/realm-index-query-engine.ts b/packages/runtime-common/realm-index-query-engine.ts index b754adea059..68738c188b2 100644 --- a/packages/runtime-common/realm-index-query-engine.ts +++ b/packages/runtime-common/realm-index-query-engine.ts @@ -48,9 +48,9 @@ import { isSingleCardDocument, isSingleFileMetaDocument, type SingleCardDocument, - type SearchEntryCollectionDocument, - type SearchEntryIncludedResource, - isSearchEntryCollectionDocument, + type EntryCollectionDocument, + type EntryIncludedResource, + isEntryCollectionDocument, } from './document-types.ts'; import { resourceIdentity } from './resource-identity.ts'; import { relationshipEntries } from './relationship-utils.ts'; @@ -61,7 +61,7 @@ import type { IconResource, QueryFieldMeta, Saved, - SearchEntryResource, + EntryResource, } from './resource-types.ts'; import { buildCssResource, @@ -71,7 +71,7 @@ import { import { buildHtmlResource, buildIconResource, - buildSearchEntryResource, + buildEntryResource, buildSparseItemResource, htmlQueryFormats, htmlQueryHasRenderTypePredicate, @@ -236,10 +236,10 @@ export class RealmIndexQueryEngine { return (this.#realmURL ??= new URL(this.#realm.url)); } - // The search-entry engine. Runs the parsed search-entry query — the + // The entry engine. Runs the parsed entry query — the // `item.` membership query against the SQL core, then the htmlQuery // evaluated per candidate rendering in this mapper — and assembles a - // heterogeneous `search-entry` document: one entry per result, with the + // heterogeneous `entry` document: one entry per result, with the // selected `html` renderings (+ deduped `css`) and/or `item` resources in // `included` per the sparse fieldset. // @@ -262,7 +262,7 @@ export class RealmIndexQueryEngine { async searchEntries( searchEntryQuery: SearchEntryQuery, opts?: Options, - ): Promise { + ): Promise { let { itemQuery: query, htmlQuery, fieldset, cardUrls } = searchEntryQuery; let engineOpts: Options = { ...opts, @@ -300,8 +300,8 @@ export class RealmIndexQueryEngine { ); let nativeOnly = !htmlQueryHasRenderTypePredicate(htmlQuery); - let data: SearchEntryResource[] = []; - let htmlResources: SearchEntryIncludedResource[] = []; + let data: EntryResource[] = []; + let htmlResources: EntryIncludedResource[] = []; let itemResources: (CardResource | FileMetaResource)[] = []; let cssById = new Map(); let iconById = new Map(); @@ -313,7 +313,7 @@ export class RealmIndexQueryEngine { continue; } // The index `url` column is the instance's file URL; a result's identity - // (shared by the `search-entry` and its `item`) drops the `.json` + // (shared by the `entry` and its `item`) drops the `.json` // extension. let cardUrl = fileUrl.endsWith('.json') ? fileUrl.slice(0, -5) : fileUrl; let hasError = Boolean(row.has_error); @@ -321,7 +321,7 @@ export class RealmIndexQueryEngine { let htmlIds: string[] | undefined; // The result's type icon, deduped by native-type internal key. Resolved // alongside the html branch (a consumer that asks for renderings is the - // one that paints icons), but emitted on the `search-entry` itself so a + // one that paints icons), but emitted on the `entry` itself so a // fallback row with no matching rendering still carries it. let iconId = collectIconId( fieldset.html ? (row.types as string[] | null)?.[0] : undefined, @@ -422,11 +422,11 @@ export class RealmIndexQueryEngine { } data.push( - buildSearchEntryResource({ url: cardUrl, htmlIds, itemType, iconId }), + buildEntryResource({ url: cardUrl, htmlIds, itemType, iconId }), ); } - let metaWithEcho: SearchEntryCollectionDocument['meta'] = fieldset.html + let metaWithEcho: EntryCollectionDocument['meta'] = fieldset.html ? { ...meta, htmlQuery } : meta; return await this.assembleSearchEntryDoc( @@ -446,7 +446,7 @@ export class RealmIndexQueryEngine { private async searchEntriesFileMeta( searchEntryQuery: SearchEntryQuery, opts?: Options, - ): Promise { + ): Promise { let { itemQuery: query, htmlQuery, fieldset } = searchEntryQuery; let { includeErrors: _includeErrors, ...fileOpts } = opts ?? {}; let runSql = () => @@ -464,8 +464,8 @@ export class RealmIndexQueryEngine { ); let itemOnEveryRow = fieldset.item.kind !== 'none'; - let data: SearchEntryResource[] = []; - let htmlResources: SearchEntryIncludedResource[] = []; + let data: EntryResource[] = []; + let htmlResources: EntryIncludedResource[] = []; let itemResources: (CardResource | FileMetaResource)[] = []; let cssById = new Map(); let iconById = new Map(); @@ -479,7 +479,7 @@ export class RealmIndexQueryEngine { let htmlIds: string[] | undefined; // A file's type icon, deduped by its native-type internal key — carried - // on the `search-entry` so a no-HTML file row (e.g. a `.gts`/`.ts` + // on the `entry` so a no-HTML file row (e.g. a `.gts`/`.ts` // FileDef with no fitted rendering) still resolves its icon. let iconId = collectIconId( fieldset.html ? file.types?.[0] : undefined, @@ -534,7 +534,7 @@ export class RealmIndexQueryEngine { } data.push( - buildSearchEntryResource({ + buildEntryResource({ url, htmlIds, itemType: itemEmitted ? FileMetaResourceType : undefined, @@ -543,7 +543,7 @@ export class RealmIndexQueryEngine { ); } - let metaWithEcho: SearchEntryCollectionDocument['meta'] = fieldset.html + let metaWithEcho: EntryCollectionDocument['meta'] = fieldset.html ? { ...meta, htmlQuery } : meta; return await this.assembleSearchEntryDoc( @@ -560,19 +560,19 @@ export class RealmIndexQueryEngine { // live search path. Items carry `meta.realmInfo` exactly as the live // search path serializes them. private async assembleSearchEntryDoc( - doc: SearchEntryCollectionDocument, + doc: EntryCollectionDocument, resources: { - htmlResources: SearchEntryIncludedResource[]; + htmlResources: EntryIncludedResource[]; cssById: Map; iconById: Map; itemResources: (CardResource | FileMetaResource)[]; fullItemRoots: (CardResource | FileMetaResource)[]; }, opts?: Options, - ): Promise { + ): Promise { let { htmlResources, cssById, iconById, itemResources, fullItemRoots } = resources; - let included: SearchEntryIncludedResource[] = [ + let included: EntryIncludedResource[] = [ ...htmlResources, ...cssById.values(), ...iconById.values(), @@ -1181,7 +1181,7 @@ export class RealmIndexQueryEngine { let realmList = realms ?? (realm ? [realm] : [realmHref]); // Resolve the cross-realm query-backed field against the peer realm's // `/_search` endpoint, data-only: the legacy card-rooted query - // translates to the search-entry wire grammar, and the `item` fieldset + // translates to the entry wire grammar, and the `item` fieldset // makes every entry carry its full `card`/`file-meta` serialization. let wireQuery = searchEntryWireQueryFromQuery( queryWithoutRealm as Query, @@ -1215,7 +1215,7 @@ export class RealmIndexQueryEngine { }; } let json = await response.json(); - if (!isSearchEntryCollectionDocument(json)) { + if (!isEntryCollectionDocument(json)) { return { cards: [], error: { @@ -1272,12 +1272,12 @@ export class RealmIndexQueryEngine { } private async attachRealmInfo( - doc: SingleCardDocument | SearchEntryCollectionDocument, + doc: SingleCardDocument | EntryCollectionDocument, ): Promise { let realmInfo = await this.#realm.getRealmInfo(); let resources = Array.isArray(doc.data) ? doc.data : [doc.data]; for (let resource of [...resources, ...(doc.included ?? [])]) { - // Only `card` / `file-meta` resources carry realm metadata. A search-entry + // Only `card` / `file-meta` resources carry realm metadata. An entry // `included` also holds `html` / `css` / `icon` resources, which have no // `realmURL`; they fall through this discriminant untouched. if ( @@ -1969,7 +1969,7 @@ function relativizeResource( // Resolve a row's `icon` (type-descriptor) resource id — its native-type // internal key — and register the deduped resource carrying the type's icon, -// display name, and code ref. Returns the id to hang the `search-entry` → +// display name, and code ref. Returns the id to hang the `entry` → // `icon` relationship on, or undefined when the row has no native type, no // `icon_html`, or an unparseable internal key. The same internal key collapses // every result of that type to one resource in `included`. diff --git a/packages/runtime-common/realm.ts b/packages/runtime-common/realm.ts index ed9d6e640d6..5616f886ab8 100644 --- a/packages/runtime-common/realm.ts +++ b/packages/runtime-common/realm.ts @@ -20,7 +20,7 @@ import { makeCardTypeSummaryDoc, type SingleCardDocument, type SingleFileMetaDocument, - type SearchEntryCollectionDocument, + type EntryCollectionDocument, } from './document-types.ts'; import type { CardResource, Relationship } from './resource-types.ts'; import { clearReplacedArrayFieldMeta } from './resource-types.ts'; @@ -5382,14 +5382,14 @@ export class Realm { return this.#realmIndexUpdater.isIgnored(url); } - // The search: the parsed search-entry query (the item. membership + // The search: the parsed entry query (the item. membership // query + the applied htmlQuery + the sparse fieldset) against the - // search-entry projection engine. Same opts threading as `search` — + // entry projection engine. Same opts threading as `search` — // `cardUrls` rides inside the SearchEntryQuery itself. public async searchEntries( searchEntryQuery: SearchEntryQuery, opts?: SearchOpts, - ): Promise { + ): Promise { let engineOpts = { loadLinks: true as const, ...(opts?.cacheOnlyDefinitions ? { cacheOnlyDefinitions: true } : {}), diff --git a/packages/runtime-common/resource-types.ts b/packages/runtime-common/resource-types.ts index d4d839a0cad..07582a10f00 100644 --- a/packages/runtime-common/resource-types.ts +++ b/packages/runtime-common/resource-types.ts @@ -23,7 +23,7 @@ export interface QueryFieldMeta { export const CardResourceType = 'card'; export const FileMetaResourceType = 'file-meta'; export const CssResourceType = 'css'; -export const SearchEntryResourceType = 'search-entry'; +export const EntryResourceType = 'entry'; export const HtmlResourceType = 'html'; export const IconResourceType = 'icon'; // resource @@ -31,7 +31,7 @@ export type Resource = | ModuleResource | CardResource | CssResource - | SearchEntryResource + | EntryResource | HtmlResource | IconResource; export type ResourceMeta = ModuleMeta | Meta; @@ -158,7 +158,7 @@ export interface CssResource { // it rides as its own deduped resource rather than repeated on each rendering. // Its `id` is the type's internal key (the `/` form already // carried as a row's `types[0]`), so identical types collapse to one -// `(type, id)` in `included`. Reached from the `search-entry` (not the `html`) +// `(type, id)` in `included`. Reached from the `entry` (not the `html`) // so item-only / no-HTML rows resolve their type descriptor too. export interface IconResource { id: string; @@ -173,7 +173,7 @@ export interface IconResource { }; } -// The synthesized rendering-selection query bound on a `search-entry` (the +// The synthesized rendering-selection query bound on an `entry` (the // "htmlQuery"): a boolean sub-query over the rendering dimensions — `eq` // leaves composed with `every`/`any`/`not`, with real boolean semantics // (`not(not(q))` selects exactly what `q` selects). It selects which of an @@ -202,9 +202,9 @@ export interface HtmlQueryLeaf { // `item` points at the live serialization. Which branches appear is governed // by the query's sparse fieldset (default: the selected renderings, falling // back to `item` — with the `html` relationship omitted — where none match). -export interface SearchEntryResource { +export interface EntryResource { id: string; - type: typeof SearchEntryResourceType; + type: typeof EntryResourceType; relationships: { html?: { data: { type: typeof HtmlResourceType; id: string }[]; @@ -281,7 +281,7 @@ export { isRelationship, isCssResource, isIconResource, - isSearchEntryResource, + isEntryResource, isHtmlResource, isSparseItemResource, } from './card-document-shape.ts'; diff --git a/packages/runtime-common/search-entry.ts b/packages/runtime-common/search-entry.ts index ade6eb8a8e5..4601a73db5c 100644 --- a/packages/runtime-common/search-entry.ts +++ b/packages/runtime-common/search-entry.ts @@ -13,14 +13,14 @@ import { } from './search-utils.ts'; import { RequestTimings } from './request-timings.ts'; import type { - SearchEntryCollectionDocument, - SearchEntryIncludedResource, + EntryCollectionDocument, + EntryIncludedResource, } from './document-types.ts'; import { CssResourceType, HtmlResourceType, IconResourceType, - SearchEntryResourceType, + EntryResourceType, htmlResourceId, resourceIdentity, type CardResource, @@ -32,7 +32,7 @@ import { type IconResource, type Relationship, type Saved, - type SearchEntryResource, + type EntryResource, } from './resource-types.ts'; import type { CodeRef, ResolvedCodeRef } from './code-ref.ts'; import { @@ -45,9 +45,9 @@ import { generalSortFields } from './index-query-engine.ts'; import { ensureTrailingSlash } from './paths.ts'; // --------------------------------------------------------------------------- -// The search-entry query. +// The entry query. // -// A search-entry request is one query rooted on `search-entry`. Entry MEMBERSHIP is +// An entry request is one query rooted on `entry`. Entry MEMBERSHIP is // addressed through `item.` (the card/file serialization) with the standard // operator-keyed filter grammar (`eq` / `contains` / `in` / `range` / `any` / // `every` / `not` / `matches`) — only the addressing changes: @@ -60,7 +60,7 @@ import { ensureTrailingSlash } from './paths.ts'; // anchor (a card-field sort without one inherits the filter's anchor). // // RENDERING SELECTION is bound through `htmlQuery` — a synthesized, -// single-valued field of `search-entry` (the `html` has-many is computed from +// single-valued field of `entry` (the `html` has-many is computed from // it). It is bound with an ordinary `eq` in the filter's top-level node, and // being single-valued it can be bound exactly once: binding it in a nested // node, under `not`, or through any other operator is an unsatisfiable @@ -75,7 +75,7 @@ import { ensureTrailingSlash } from './paths.ts'; // (`types[0]`) is in play — an explicit predicate opens the full // adoption-chain universe. // -// `fields[search-entry]` is the sparse fieldset selecting which branches the +// `fields[entry]` is the sparse fieldset selecting which branches the // response carries: `html`, `item` (the full serialization), or // `item.` entries (a field-limited serialization that ships // `meta.sparseFields` and never enters the Store). No fieldset means the @@ -124,7 +124,7 @@ export interface SearchEntryFieldset { itemAsFallback: boolean; } -// The parsed form of a search-entry request: the legacy `Query` for the SQL core (the +// The parsed form of an entry request: the legacy `Query` for the SQL core (the // `item.` addressing stripped), the applied (bound or defaulted) htmlQuery, // and the parsed sparse fieldset. The compat layer constructs this directly // from a legacy request — it does not round-trip through the wire grammar. @@ -423,7 +423,7 @@ function translateFilterNode( ); } } - // A node carrying only the type anchor is the search-entry spelling of a pure + // A node carrying only the type anchor is the entry spelling of a pure // card-type filter. let keys = Object.keys(out); if (keys.length === 1 && keys[0] === 'on') { @@ -512,18 +512,16 @@ function parseFieldset(fields: unknown): SearchEntryFieldset { throw invalidQuery(`fields must be an object`); } let keys = Object.keys(fields); - if (keys.length !== 1 || keys[0] !== 'search-entry') { - throw invalidQuery(`fields supports only the "search-entry" type`); + if (keys.length !== 1 || keys[0] !== 'entry') { + throw invalidQuery(`fields supports only the "entry" type`); } - let entries = (fields as Record)['search-entry']; + let entries = (fields as Record)['entry']; if ( !Array.isArray(entries) || entries.length === 0 || !entries.every((entry) => typeof entry === 'string') ) { - throw invalidQuery( - `fields[search-entry] must be a non-empty array of strings`, - ); + throw invalidQuery(`fields[entry] must be a non-empty array of strings`); } let html = false; let itemFull = false; @@ -540,13 +538,13 @@ function parseFieldset(fields: unknown): SearchEntryFieldset { sparseFields.push(entry.slice(ITEM_PREFIX.length)); } else { throw invalidQuery( - `each fields[search-entry] entry must be "html", "item", or "item." (got "${entry}")`, + `each fields[entry] entry must be "html", "item", or "item." (got "${entry}")`, ); } } if (itemFull && sparseFields.length > 0) { throw invalidQuery( - `fields[search-entry] cannot combine "item" (the full serialization) with item. entries`, + `fields[entry] cannot combine "item" (the full serialization) with item. entries`, ); } let item: SearchEntryItemSelection = itemFull @@ -570,7 +568,7 @@ export function parseSearchEntryQueryFromPayload( let record = payload as Record; for (let key of Object.keys(record)) { if (!SEARCH_ENTRY_QUERY_MEMBERS.includes(key)) { - throw invalidQuery(`unknown member "${key}" in search-entry query`); + throw invalidQuery(`unknown member "${key}" in entry query`); } } @@ -661,16 +659,16 @@ export function parseSearchEntryQueryFromPayload( // --------------------------------------------------------------------------- // The wire grammar — what a client sends to `_search` / -// `_federated-search`. `SearchEntryWireQuery` is the search-entry-rooted +// `_federated-search`. `SearchEntryWireQuery` is the entry-rooted // request body: entry membership addressed through `item.` paths (`item.on` // as the type anchor), the htmlQuery bound in the filter's top-level `eq`, -// and the sparse fieldset under `fields[search-entry]`. +// and the sparse fieldset under `fields[entry]`. // // `searchEntryWireQueryFromQuery` translates a legacy card-rooted `Query` // into that grammar — the exact inverse of the parser's addressing strip // (round-trip parity is pinned by test) — so an instances-level caller can // keep authoring the legacy query shape while the request runs against the -// search-entry engine. +// entry engine. // --------------------------------------------------------------------------- export interface SearchEntryWireSortExpression { @@ -698,7 +696,7 @@ export interface SearchEntryWireQuery { filter?: SearchEntryWireFilter; sort?: SearchEntryWireSortExpression[]; page?: { number?: number; size: number; generation?: number }; - fields?: { 'search-entry': string[] }; + fields?: { entry: string[] }; cardUrls?: string[]; realms?: string[]; } @@ -727,7 +725,7 @@ function wireFilterFromFilter(filter: Filter): SearchEntryWireFilter { out.matches = value as string; } else { throw new Error( - `cannot translate filter member "${key}" to the search-entry wire grammar`, + `cannot translate filter member "${key}" to the entry wire grammar`, ); } } @@ -741,7 +739,7 @@ export function searchEntryWireQueryFromQuery( // the legacy `realm`/`realms` members are deliberately not carried — the // caller addresses realms at the request level; `asData`/`fields` are the // legacy data path's members and have no wire spelling here (the - // projection is `opts.fields`, the `fields[search-entry]` sparse fieldset) + // projection is `opts.fields`, the `fields[entry]` sparse fieldset) let wire: SearchEntryWireQuery = {}; if (query.filter) { wire.filter = wireFilterFromFilter(query.filter); @@ -757,7 +755,7 @@ export function searchEntryWireQueryFromQuery( wire.page = query.page; } if (opts?.fields) { - wire.fields = { 'search-entry': [...opts.fields] }; + wire.fields = { entry: [...opts.fields] }; } return wire; } @@ -773,13 +771,13 @@ export function searchEntryWireQueryFromQuery( // --------------------------------------------------------------------------- export function combineSearchEntryResults( - docs: SearchEntryCollectionDocument[], -): SearchEntryCollectionDocument { - let combined: SearchEntryCollectionDocument = { + docs: EntryCollectionDocument[], +): EntryCollectionDocument { + let combined: EntryCollectionDocument = { data: [], meta: { page: { total: 0 } }, }; - let included: SearchEntryIncludedResource[] = []; + let included: EntryIncludedResource[] = []; let includedByIdentity = new Set(); for (let doc of docs) { @@ -812,7 +810,7 @@ type SearchEntrySearchableRealm = { searchEntries: ( searchEntryQuery: SearchEntryQuery, opts?: SearchOpts, - ) => Promise; + ) => Promise; url?: string; }; @@ -820,7 +818,7 @@ export async function searchEntryRealms( realms: Array, searchEntryQuery: SearchEntryQuery, opts?: SearchOpts, -): Promise { +): Promise { // Same instrumentation contract as `searchRealms`: a caller that threads // its own collector (the realm-server handler) emits the complete // request→response line itself; a caller that threads only a @@ -854,30 +852,30 @@ export async function searchEntryRealms( } // --------------------------------------------------------------------------- -// Builders for the search-entry resources. The projection engine runs these per row -// when assembling a `search-entry` document; keeping them pure (no SQL, no +// Builders for the entry resources. The projection engine runs these per row +// when assembling an `entry` document; keeping them pure (no SQL, no // realm state) lets the shapes be unit-tested directly. The `css` resource // builder is shared with the pre-existing search paths (`buildCssResource`). // --------------------------------------------------------------------------- -// One `search-entry` — the top-level `data` resource for a result. Which +// One `entry` — the top-level `data` resource for a result. Which // branches it carries is the resolution policy / sparse fieldset's call; this // just assembles the linkage. The `item` shares the entry's URL as its id; // each `html` member points at one specific rendering by its composite id. // `htmlIds` undefined omits the relationship (the default mode's fallback // rows); an empty array emits `data: []` (a pinned html branch with no // matching rendering yet). -export function buildSearchEntryResource(args: { +export function buildEntryResource(args: { url: string; htmlIds?: string[]; itemType?: typeof CardResourceType | typeof FileMetaResourceType; // The id of the result's `icon` resource (its native-type internal key) — // omitted when the row carries no `icon_html`. iconId?: string; -}): SearchEntryResource { +}): EntryResource { let { url, htmlIds, itemType, iconId } = args; - let resource: SearchEntryResource = { - type: SearchEntryResourceType, + let resource: EntryResource = { + type: EntryResourceType, id: url, relationships: {}, }; @@ -934,7 +932,7 @@ export function buildHtmlResource(args: { // One card-type `icon` resource (see `IconResource`): the per-type descriptor // (icon, display name, code ref). Its `id` is the type's internal key — the // `/` form a row already carries as `types[0]` — so the same type -// collapses to one resource in `included`. The `search-entry` → `icon` +// collapses to one resource in `included`. The `entry` → `icon` // relationship points here, reachable for item-only rows that carry no `html` // rendering. export function buildIconResource(args: { diff --git a/packages/runtime-common/search-results-component.ts b/packages/runtime-common/search-results-component.ts index 81c3e2dc63f..3ece884a9a1 100644 --- a/packages/runtime-common/search-results-component.ts +++ b/packages/runtime-common/search-results-component.ts @@ -1,7 +1,7 @@ import type { ComponentLike } from '@glint/template'; import type { ResolvedCodeRef } from './code-ref.ts'; -import type { SearchEntryCollectionDocument } from './document-types.ts'; +import type { EntryCollectionDocument } from './document-types.ts'; import type { ErrorEntry } from './error.ts'; import type { PrerenderedHtmlFormat } from './prerendered-html-format.ts'; import type { @@ -71,13 +71,13 @@ export interface RenderableSearchEntryLike { export interface SearchResultsYield { entries: RenderableSearchEntryLike[]; isLoading: boolean; - meta: SearchEntryCollectionDocument['meta']; + meta: EntryCollectionDocument['meta']; errors: ErrorEntry[] | undefined; } // The card-facing contract for the search component the host provides on // `@context` (`@context.searchResultsComponent`). It consumes the heterogeneous -// `search-entry` stream for a `search-entry`-rooted query and renders it +// `entry` stream for an `entry`-rooted query and renders it // transparently — prerendered HTML inert (hydrated lazily) or the live // serialization. Used with a block it yields a `results` object // (`entries` / `isLoading` / `meta` / `errors`); used without one it renders @@ -85,7 +85,7 @@ export interface SearchResultsYield { export interface SearchResultsComponentSignature { Element: HTMLElement; Args: { - // The `search-entry`-rooted query. Re-issued live on invalidation; + // The `entry`-rooted query. Re-issued live on invalidation; // changing it re-runs the search. Undefined → idle (no results). query: SearchEntryWireQuery | undefined; // The hydration gesture for HTML-backed rows — a host-UX choice, never on diff --git a/packages/vscode-boxel-tools/src/skills.ts b/packages/vscode-boxel-tools/src/skills.ts index df12ffa2ea6..c0a500ab098 100644 --- a/packages/vscode-boxel-tools/src/skills.ts +++ b/packages/vscode-boxel-tools/src/skills.ts @@ -378,10 +378,10 @@ export class SkillList extends vscode.TreeItem { headers['Authorization'] = jwt; } - // `_search` speaks the search-entry wire grammar: entry membership is + // `_search` speaks the entry wire grammar: entry membership is // addressed through `item.` (the card serialization), so the type anchor // is `item.on` and sort keys carry the `item.` prefix. Request the - // data-only fieldset (`fields[search-entry]=item`) — skill discovery never + // data-only fieldset (`fields[entry]=item`) — skill discovery never // renders HTML, so each entry carries only its full `item` serialization. const searchUrl = new URL('./_search', this.realmUrl); const query = { @@ -400,7 +400,7 @@ export class SkillList extends vscode.TreeItem { name: 'Skill', }, }, - fields: { 'search-entry': ['item'] }, + fields: { entry: ['item'] }, }; const response = await fetch(searchUrl, { method: 'QUERY', @@ -422,7 +422,7 @@ export class SkillList extends vscode.TreeItem { const data: any = await response.json(); console.log('Skill search data:', data); - // The `item` serializations live in `included`; each `search-entry` in + // The `item` serializations live in `included`; each `entry` in // `data` links one through its `item` relationship. Resolve them in result // order — these are the Skill card resources we read title/instructions // off of.