Boxel UI build & test-app refactor

.claude/skills/pr-screenshots/SKILL.md

@@ -23,6 +23,7 @@ Visual changes benefit enormously from a screenshot — reviewers react to the a
    ```
    ![preview](https://raw.githubusercontent.com/<owner>/<repo>/<commit-sha>/.pr-images/<slug>/<name>.png)
    ```
+
 5. **Followup commit** `git rm`s the image and pushes. GitHub still serves the blob from the named commit, so the SHA-pinned reference keeps working.
 
 ## Critical gotcha: pin to the commit SHA, never the branch

.github/workflows/build-host.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Restore boxel-icons build cache
         id: icons-cache
         uses: ./.github/actions/restore-icons-cache
-      - name: Build boxel-icons and boxel-ui
+      - name: Build boxel-icons
         run: mise run build:ui
         env:
           SKIP_ICONS_BUILD: ${{ steps.icons-cache.outputs.cache-hit }}

.github/workflows/ci-lint.yaml

@@ -51,16 +51,7 @@ jobs:
       - name: Lint Boxel UI
         if: ${{ !cancelled() }}
         run: pnpm run lint
-        working-directory: packages/boxel-ui/addon
-      - name: Build Boxel UI
-        # To faciliate linting of projects that depend on Boxel UI
-        if: ${{ !cancelled() }}
-        run: pnpm run build
-        working-directory: packages/boxel-ui/addon
-      - name: Lint Boxel UI Test App
-        if: ${{ !cancelled() }}
-        run: pnpm run lint
-        working-directory: packages/boxel-ui/test-app
+        working-directory: packages/boxel-ui
       - name: Lint Host
         if: ${{ !cancelled() }}
         run: pnpm run lint

.github/workflows/ci.yaml

@@ -323,13 +323,13 @@ jobs:
       - name: Restore boxel-icons build cache
         id: icons-cache
         uses: ./.github/actions/restore-icons-cache
-      - name: Build boxel-icons and boxel-ui
+      - name: Build boxel-icons
         run: mise run build:ui
         env:
           SKIP_ICONS_BUILD: ${{ steps.icons-cache.outputs.cache-hit }}
       - name: Run test suite
         run: pnpm test
-        working-directory: packages/boxel-ui/test-app
+        working-directory: packages/boxel-ui
 
   boxel-ui-raw-icon-changes-only:
     name: Boxel UI ensure raw icon changes only
@@ -344,7 +344,7 @@ jobs:
       - uses: ./.github/actions/init
       - name: Rebuild boxel-ui icons
         run: pnpm rebuild:icons
-        working-directory: packages/boxel-ui/addon
+        working-directory: packages/boxel-ui
       - name: Fail if generated icons have been changed without underlying raw icon changing
         run: git diff --exit-code
 
@@ -837,9 +837,6 @@ jobs:
       - name: Build Boxel Icons
         run: pnpm run build
         working-directory: packages/boxel-icons
-      - name: Build Boxel UI
-        run: pnpm run build
-        working-directory: packages/boxel-ui/addon
       - name: Build host dist
         run: pnpm build
         working-directory: packages/host

.github/workflows/deploy-ui.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Restore boxel-icons build cache
         id: icons-cache
         uses: ./.github/actions/restore-icons-cache
-      - name: Build boxel-icons and boxel-ui
+      - name: Build boxel-icons
         run: mise run build:ui
         env:
           SKIP_ICONS_BUILD: ${{ steps.icons-cache.outputs.cache-hit }}

.github/workflows/manual-deploy.yml

@@ -364,8 +364,7 @@ jobs:
 
   deploy-worker:
     name: Deploy worker
-    needs:
-      [build-worker, deploy-host, migrate-db, deploy-prerender-manager]
+    needs: [build-worker, deploy-host, migrate-db, deploy-prerender-manager]
     uses: cardstack/gh-actions/.github/workflows/ecs-deploy.yml@main
     secrets: inherit
     with:
@@ -388,8 +387,7 @@ jobs:
 
   deploy-realm-server:
     name: Deploy realm server
-    needs:
-      [post-deploy-worker, build-realm-server, deploy-host, migrate-db]
+    needs: [post-deploy-worker, build-realm-server, deploy-host, migrate-db]
     uses: cardstack/gh-actions/.github/workflows/ecs-deploy.yml@main
     secrets: inherit
     with:

.github/workflows/test-web-assets.yaml

@@ -75,7 +75,6 @@ jobs:
           key: ${{ steps.keys.outputs.cache_key }}
           path: |
             packages/boxel-icons/dist
-            packages/boxel-ui/addon/dist
             packages/host/dist
             .ci/test-web-assets/manifest.json
 
@@ -133,7 +132,6 @@ jobs:
           key: ${{ steps.keys.outputs.cache_key }}
           path: |
             packages/boxel-icons/dist
-            packages/boxel-ui/addon/dist
             packages/host/dist
             .ci/test-web-assets/manifest.json
 
@@ -143,7 +141,6 @@ jobs:
           name: ${{ steps.keys.outputs.artifact_name }}
           path: |
             packages/boxel-icons/dist
-            packages/boxel-ui/addon/dist
             packages/host/dist
             .ci/test-web-assets/manifest.json
           retention-days: 7

AGENTS.md

@@ -52,13 +52,12 @@
 
 - No tests
 
-### packages/boxel-ui/addon, packages/boxel-ui/test-app
+### packages/boxel-ui
 
-- Addon functionality is tested via sibling test-app directory
-- `cd packages/boxel-ui/addon && pnpm start` to start a process that will watch files and automatically rebuild the addon
-- `cd packages/boxel-ui/test-app && pnpm start` to start a process that will watch files and automatically rebuild the test-app
+- Addon functionality with in-package test suite
+- `cd packages/boxel-ui && pnpm start` to start development server
 - Run all tests
-  `cd packages/boxel-ui/test-app && ember test --path dist`
+  `cd packages/boxel-ui && ember test --path dist`
 - To run a subset of the tests:
   `ember test --path dist --filter "some text that appears in module name or test name"`  
   Note that the filter is matched against the module name and test name, not the file name! Try to avoid using pipe characters in the filter, since they can confuse auto-approval tool use filters set up by the user.
@@ -92,7 +91,7 @@
 #### CSS Guidance
 
 - Use scalable units such as rem
-- Use CSS variables from packages/boxel-ui/addon/src/styles/variables.css
+- Use CSS variables from packages/boxel-ui/src/styles/variables.css
 
 #### Iterating on host tests with the Chrome MCP server
 

QUICKSTART.md

@@ -27,29 +27,21 @@ To build the entire repository and run the application, follow these steps:
    pnpm install
    ```
 
-4. Build the boxel-ui addon:
-
-   ```zsh
-   cd ./packages/boxel-ui/addon
-   pnpm rebuild:icons
-   pnpm build
-   ```
-
-5. Build the boxel-icons:
+4. Build the boxel-icons:
 
    ```zsh
    cd ./packages/boxel-icons
    pnpm build
    ```
 
-6. Build the host:
+5. Build the host:
 
    ```zsh
    cd ./packages/host
    pnpm start
    ```
 
-7. Run the realm server:
+6. Run the realm server:
 
    ```zsh
    cd ./packages/realm-server
@@ -66,14 +58,14 @@ To build the entire repository and run the application, follow these steps:
    })
    ```
 
-8. Register ALL:
+7. Register ALL:
 
    ```zsh
    cd ./packages/matrix
    pnpm register-all
    ```
 
-9. Verify registration:
+8. Verify registration:
 
    ```zsh
    cd ./packages/matrix
@@ -82,20 +74,20 @@ To build the entire repository and run the application, follow these steps:
 
    Visit http://localhost:8080. Type in Username = "admin", Password: "password" Homeserver URL: http://localhost:8008
 
-10. Host App
-    - Visit https://localhost:4200/
-    - Enter the registration flow and create a Boxel Account
-    - When prompted for an authentication token, type in "dev-token"
+9. Host App
+   - Visit https://localhost:4200/
+   - Enter the registration flow and create a Boxel Account
+   - When prompted for an authentication token, type in "dev-token"
 
-11. Validate email for login
+10. Validate email for login
     - Visit SMTP UI at http://localhost:5001/
     - Validate email
     - Go back to Host https://localhost:4200/ and login
 
-12. Perform "Setup up Secure Payment Method" flow
+11. Perform "Setup up Secure Payment Method" flow
     - More detailed steps can be found in our [README](README.md) Payment Setup section
 
-13. Run ai bot (Optional):
+12. Run ai bot (Optional):
 
     ```zsh
     cd ./packages/ai-bot

README.md

@@ -18,9 +18,7 @@ For a quickstart, see [here](./QUICKSTART.md)
 
 `packages/realm-server` is a node app that serves the realm as an HTTP server, as well as, it can also host the runtime application for its own realm.
 
-`packages/boxel-ui/addon` is the UI components Ember addon
-
-`packages/boxel-ui/test-app` is the test suite and component explorer for boxel-ui, deployed at [boxel-ui.stack.cards](https://boxel-ui.stack.cards)
+`packages/boxel-ui` is the UI components Ember addon. The package also includes a test suite and component explorer, deployed at [boxel-ui.stack.cards](https://boxel-ui.stack.cards)
 
 `packages/matrix` is the docker container for running the matrix server: synapse, as well as tests that involve running a matrix client.
 
@@ -109,9 +107,8 @@ Make sure that you have created a matrix user for the base and experiments realm
 
 In order to run the ember-cli hosted app:
 
-1. `pnpm build` in the boxel-ui/addon workspace to build the boxel-ui addon.
-2. `pnpm start` in the host/ workspace to serve the ember app.
-3. `mise run dev` from the repo root to serve the base and experiments realms -- this will also allow you to switch between the app and the tests without having to restart servers). This expects the Ember application to be running at `https://localhost:4200`, if you’re running it elsewhere you can specify it with `HOST_URL=http://localhost:5200 mise run dev`.
+1. `pnpm start` in the host/ workspace to serve the ember app.
+2. `mise run dev` from the repo root to serve the base and experiments realms -- this will also allow you to switch between the app and the tests without having to restart servers). This expects the Ember application to be running at `https://localhost:4200`, if you’re running it elsewhere you can specify it with `HOST_URL=http://localhost:5200 mise run dev`.
 
 Alternatively, you can run everything with a single command from the repo root:
 

docs/spec.md

@@ -8,8 +8,8 @@ At its core, a Spec links to an exported definition in modules via **Code Ref**
 
 ```typescript
 {
-  module: string;  // Path to the module file (e.g., './my-component.gts')
-  name: string;    // Export name (e.g., 'MyComponent')
+  module: string; // Path to the module file (e.g., './my-component.gts')
+  name: string; // Export name (e.g., 'MyComponent')
 }
 ```
 
@@ -18,21 +18,21 @@ When a module is edited (for example, if a definition is renamed), the spec migh
 ## Why We Need Specs
 
 - **Search for instance creation** - Enable discovery and instantiation of available components. Code refs are not searchable unless wrapped inside a card instance (a spec) which is then indexed and can benefit from all search capabilities. This makes field definitions searchable as well.
-- **Packaging of listings** - Code packaging in bundles occurs via linksToMany specs. The installation process looks for modules and code refs to copy during installation. 
+- **Packaging of listings** - Code packaging in bundles occurs via linksToMany specs. The installation process looks for modules and code refs to copy during installation.
 - **Link to examples** - Provide interactive demonstrations and usage patterns
 - **Documentation for code** - Maintain up-to-date, validated documentation connected to implementation
 
 ## Different Spec Types
 
-Code categorization is endless, so we focus on a subset of exported code that interests us within the Boxel ecosystem. 
+Code categorization is endless, so we focus on a subset of exported code that interests us within the Boxel ecosystem.
 
 The Boxel ecosystem supports five distinct spec types:
 
-- **`card`** 
-- **`field`** 
-- **`component`** 
-- **`app`** 
-- **`command`** 
+- **`card`**
+- **`field`**
+- **`component`**
+- **`app`**
+- **`command`**
 
 Each spec type has specific characteristics and use cases:
 
@@ -41,12 +41,14 @@ Each spec type has specific characteristics and use cases:
 **Purpose**: Document card definitions - the ultimate sharing unit of the Boxel ecosystem.
 
 **Characteristics**:
+
 - Can have multiple view templates (isolated, fitted, embedded, edit)
 - Often contain fields and computed properties
 - May extend other cards through inheritance
-- Support `linkedExamples` 
+- Support `linkedExamples`
 
 **Example Use Cases**:
+
 - `Author` - Author profile card with bio and social links
 - `Contact` - Contact information card for CRM systems
 - `BlogPost` - Blog post card with content and metadata
@@ -57,12 +59,14 @@ Each spec type has specific characteristics and use cases:
 **Purpose**: Document field definitions used within cards.
 
 **Characteristics**:
+
 - Only support `containedExamples` (embedded within the spec)
 - May be primitive (string, number, boolean) or composite
-- TBD: display of primitive contained examples 
+- TBD: display of primitive contained examples
 - May extend other fields through inheritance
 
 **Example Use Cases**:
+
 - `SocialMediaLink` - Composite field for social platform data
 - `MaybeBase64Field` - String field with base64 encoding capabilities
 - `TextAreaField` - Multi-line text input field
@@ -73,12 +77,14 @@ Each spec type has specific characteristics and use cases:
 **Purpose**: Document reusable UI components that don't represent data, so AI agents and developers can discover them by searching the catalog instead of needing a per-component skill.
 
 **Characteristics**:
+
 - Only when it extends Glimmer Component
 - Potentially includes reactive data loading resources from ember-resources
 - API documentation, an example, and CSS variables live in the `readMe` markdown field
 - `cardDescription` is the keyword-rich one-liner the agent matches against — keep it concrete (e.g. "Form text input with validation states") rather than abstract
 
 **Example Use Cases**:
+
 - `CardsGrid` - Responsive grid layout component for card collections
 - `FilterDropdown` - Multi-select dropdown component for filtering
 - `Pill` - Badge component for displaying tags and statuses
@@ -150,12 +156,14 @@ the deployed commit.
 **Purpose**: Document application-level cards that serve as entry points, typically when other cards are queried within them.
 
 **Characteristics**:
-- Extends AppCard which displays in a wide view 
-- Often contain more than one query 
-- Often use navigation components like tabs or sidebars 
-- Support `linkedExamples` 
+
+- Extends AppCard which displays in a wide view
+- Often contain more than one query
+- Often use navigation components like tabs or sidebars
+- Support `linkedExamples`
 
 **Example Use Cases**:
+
 - `BlogApp` - Blog content management system
 - `PreschoolCRMApp` - Customer relationship management for preschools
 - `SprintPlanner` - Sprint planning applications
@@ -165,11 +173,13 @@ the deployed commit.
 **Purpose**: Document executable commands within the system.
 
 **Characteristics**:
-- Represent actions within a command palette 
+
+- Represent actions within a command palette
 - Imperative code that doesn't depend on data loading in a component
-- Have access to host code via boxel-host commands 
+- Have access to host code via boxel-host commands
 
 **Example Use Cases**:
+
 - `GenerateReadmeSpecCommand` - Generate documentation for spec cards
 - `SearchCardsByQueryCommand` - Advanced card search with filtering
 - `PatchCardInstanceCommand` - Update card instance data

mise-tasks/build/ui

@@ -1,5 +1,5 @@
 #!/bin/sh
-#MISE description="Build boxel-icons and boxel-ui (in dependency order)"
+#MISE description="Build boxel-icons (in dependency order)"
 
 set -eu
 
@@ -9,4 +9,3 @@ else
   pnpm --dir packages/boxel-icons build
 fi
 
-pnpm --dir packages/boxel-ui/addon build

mise-tasks/build/worktree-types

@@ -6,7 +6,4 @@ set -eu
 echo "Building @cardstack/boxel-icons..."
 pnpm --dir packages/boxel-icons build
 
-echo "Building @cardstack/boxel-ui type declarations..."
-pnpm --dir packages/boxel-ui/addon build:types
-
 echo "Done — worktree type declarations are ready for pnpm lint"