glimmerjs · NullVoxPopuli · Jul 1, 2025 · Jul 1, 2025 · Jul 1, 2025 · Jul 1, 2025
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -92,7 +92,6 @@ jobs:
           pnpm test:setup
           pnpm test:node
 
-
   test-chrome:
     name: Chrome
     runs-on: ubuntu-latest
@@ -116,42 +115,6 @@ jobs:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
       - run: pnpm test
 
-  # test-browserstack:
-  #   name: Browserstack
-  #   runs-on: ubuntu-latest
-  #   needs: ['install_dependencies']
-  #   timeout-minutes: 20
-
-  #   env:
-  #     BROWSERSTACK_USERNAME: glimmervm1
-  #     BROWSERSTACK_ACCESS_KEY: 7DFjbGLxYRsXWmc8tzeh
-
-  #   steps:
-  #     - uses: actions/checkout@v3
-  #     - uses: wyvox/action-setup-pnpm@v2
-  #     - run: pnpm browserstack:connect
-  #     - run: pnpm test:browserstack
-  #     - run: pnpm browserstack:results
-  #     - run: pnpm browserstack:disconnect
-
-  # test-browserstack:
-  #   name: Browserstack
-  #   runs-on: ubuntu-latest
-  #   needs: ['install_dependencies']
-  #   timeout-minutes: 20
-
-  #   env:
-  #     BROWSERSTACK_USERNAME: glimmervm1
-  #     BROWSERSTACK_ACCESS_KEY: 7DFjbGLxYRsXWmc8tzeh
-
-  #   steps:
-  #     - uses: actions/checkout@v3
-  #     - uses: wyvox/action-setup-pnpm@v2
-  #     - run: pnpm browserstack:connect
-  #     - run: pnpm test:browserstack
-  #     - run: pnpm browserstack:results
-  #     - run: pnpm browserstack:disconnect
-
   test-types:
     name: Types
     runs-on: ubuntu-latest

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,136 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Building
+
+- `pnpm repo:prepack` - Build all packages via Turbo (recommended)
+- `pnpm clean` - Clean build artifacts
+
+### Testing
+
+- `pnpm test` - Run all tests
+- `pnpm start` - Start Vite dev server for browser testing
+- `pnpm test:node` - Run Node.js tests via Turbo
+
+To run a single test or test module, use the browser test interface with `pnpm start` and filter tests using the QUnit UI.
+
+### Linting & Type Checking
+
+- `pnpm lint:fix` - Auto-fix linting issues and format with Prettier (required before commits)
+- `pnpm test:lint` - Run ESLint
+- `pnpm lint:format` - Check Prettier formatting
+- `pnpm repo:lint:types` - Type check all packages via Turbo
+
+### CI Preparation
+
+These commands MUST be run before pushing to ensure CI passes:
+- `pnpm lint:fix` - Fix formatting and linting
+- `pnpm repo:update:conventions` - Update package conventions
+- `pnpm repo:update:metadata` - Update package metadata
+
+The CI "Verify" job will fail if these commands produce uncommitted changes.
+
+## Architecture
+
+Glimmer VM is a **compiler-based rendering engine** that compiles Handlebars templates into bytecode for efficient execution and updates.
+
+### Core Flow
+
+1. **Templates** (Handlebars) → **Compiler** → **Bytecode** (Wire Format)
+2. **Bytecode** → **Runtime VM** → **DOM Operations**
+3. **State Changes** → **Validator System** → **Targeted Updates**
+
+### Key Packages
+
+**Compilation Pipeline**:
+- `@glimmer/syntax` - Template parser and AST (uses visitor pattern for traversal)
+- `@glimmer/compiler` - Compiles templates to bytecode
+- `@glimmer/wire-format` - Bytecode format definitions
+- `@glimmer/opcode-compiler` - Bytecode generation
+
+**Runtime Engine**:
+- `@glimmer/runtime` - VM that executes bytecode
+- `@glimmer/vm` - Core VM implementation
+- `@glimmer/reference` - Reactive reference system for state tracking
+- `@glimmer/validator` - Change detection and invalidation
+
+**Extension Points**:
+- `@glimmer/manager` - Component/helper/modifier manager APIs
+- `@glimmer/interfaces` - TypeScript interfaces and contracts
+
+### Monorepo Structure
+
+- Uses pnpm workspaces with Turbo for orchestration
+- Packages in `packages/@glimmer/*` are published to npm
+- Packages in `packages/@glimmer-workspace/*` are internal tools
+- Each package has its own tsconfig with varying strictness levels
+- Node version requirement: >= 22.12.0
+
+### TypeScript Patterns
+
+- "Friend" properties use bracket notation: `object['_privateProperty']`
+- This allows cross-package internal access while maintaining type safety
+- Different packages have different strictness levels in their tsconfig
+
+### Testing Strategy
+
+- Integration tests in `@glimmer-workspace/integration-tests`
+- Unit tests colocated with packages
+- Browser tests use QUnit + Vite
+- Node tests use Vitest
+- Smoke tests verify package compatibility
+
+### Debug Infrastructure
+
+The codebase includes sophisticated debug tooling:
+- `check()` function for runtime type checking (stripped in production by babel plugin)
+- `@glimmer/debug` package for development-time debugging
+- Stack checking and validation in development builds
+
+## Common Development Tasks
+
+### Running a specific test file
+
+```bash
+# For Node tests (Vitest)
+cd packages/@glimmer/[package-name]
+pnpm test:node -- path/to/test.ts
+
+# For browser tests
+pnpm start
+# Then navigate to the browser and use the QUnit filter
+```
+
+### After making AST changes
+
+If you modify the AST structure in `@glimmer/syntax`:
+1. Run smoke tests: `cd smoke-tests/node && pnpm test:node`
+2. Update snapshots if needed: `pnpm vitest run -u`
+3. Document why changes are not breaking (visitor pattern protection)
+
+### Before pushing changes
+
+Always run these commands to avoid CI failures:
+```bash
+pnpm lint:fix
+pnpm repo:update:conventions
+pnpm repo:update:metadata
+git add -A && git commit
+```
+
+## Contribution Guidelines
+
+### Commit Messages
+
+- Write clear, concise commit messages that explain the change
+- Do not include Claude attribution or automated generation notices
+- Focus on the "why" and "what" of the change, not implementation details
+
+### Git Workflow
+
+- Squashing commits is often preferred for complex PRs
+- When rebasing, be prepared to resolve conflicts in package.json, eslint.config.js, and build configs
+- The babel debug plugin pattern requires `check()` calls to be inline (not inside if blocks) for proper type narrowing
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# Status [![Build Status](https://travis-ci.org/glimmerjs/glimmer-vm.svg?branch=main)](https://travis-ci.org/glimmerjs/glimmer-vm) [![BrowserStack Status](https://www.browserstack.com/automate/badge.svg?badge_key=cG1zSVBpNk5nTWxDcGJ0YkVkQjZsM1YrRzFvQW9GdGlhQm5WMFh1QUZXWT0tLXpXTVRWMXNMRW03MmxUZVpLUy85YkE9PQ==--b6c04579b1314f752eacc8bfff1a03574b8bdc8d%)](https://www.browserstack.com/automate/public-build/cG1zSVBpNk5nTWxDcGJ0YkVkQjZsM1YrRzFvQW9GdGlhQm5WMFh1QUZXWT0tLXpXTVRWMXNMRW03MmxUZVpLUy85YkE9PQ==--b6c04579b1314f752eacc8bfff1a03574b8bdc8d%)
+# Status [![Build Status](https://travis-ci.org/glimmerjs/glimmer-vm.svg?branch=main)](https://travis-ci.org/glimmerjs/glimmer-vm)
 
 
 Glimmer is a flexible, low-level rendering pipeline for building a "live" DOM
@@ -26,19 +26,19 @@ must build the packages first with `npm run build`).
 
 # How to Run Tests
 
-## Via Ember CLI
+## Running all tests
 
-1. Run: `ember test --server`
+1. Run `pnpm test` to run all tests.
 
-Ember CLI is a CI tool, so it will run tests as you change files.
-
-## On the console with PhantomJS
+## In a browser
 
-1. Run `npm test`.
+1. Run `pnpm start` to start the Vite dev server.
+2. Open your browser and navigate to the provided URL.
+3. Use the QUnit interface to filter and run specific tests.
 
-## In a browser
+## Node.js tests
 
-1. Run `npm start`.
+1. Run `pnpm test:node` to run Node.js tests via Turbo.
 2. Visit <http://localhost:7357/tests/>.
 
 # TypeScript Notes
@@ -90,4 +90,3 @@ private properties outside of the package.**
 
 Cross-browser testing provided by:
 
-<a href="http://browserstack.com"><img height="70" src="https://p3.zdusercontent.com/attachment/1015988/PWfFdN71Aung2evRkIVQuKJpE?token=eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0..aUrNFb8clSXsFwgw5BUTcg.IJr5piuCen7PmSSBHSrOnqM9K5YZfxX3lvbp-5LCqoKOi4CjjgdA419iqjofs0nLtm26FMURvZ8JRTuKB4iHer6lGu5f8dXHtIkYAHjP5fXDWkl044Yg2mSdrhF6uPy62GdlBYoYxwvgkNrac8nN_In8GY-qOC7bYmlZyJT7tsTZUTYbNMQiXS86YA5LgdCEWzWreMvc3C6cvZtVXIrcVgpkroIhvsTQPm4vQA-Uq6iCbTPA4oX5cpEtMtrlg4jYBnnAE4BTw5UwU_dY83ep5g.7wpc1IKv0rSRGsvqCG_q3g" alt="BrowserStack"></a>
diff --git a/bin/run-browserstack-tests.mjs b/bin/run-browserstack-tests.mjs
diff --git a/browserstack-local.pid b/browserstack-local.pid
diff --git a/browserstack.sh b/browserstack.sh
diff --git a/guides/development/build-constraints.md b/guides/development/build-constraints.md
@@ -208,9 +208,9 @@ The build system uses Turbo for orchestration with these key relationships:
 - Cache keys include TypeScript configs, source files, and lock files
 
 ### Build Commands
-- `pnpm build:control` - Build all packages using Rollup
-- `pnpm repo:prepack` - Prepare packages for publishing
+- `pnpm repo:prepack` - Build all packages via Turbo (recommended)
 - `pnpm repo:lint:types` - Type check all packages
+- `pnpm clean` - Clean build artifacts
 
 ### Package Publishing
 

diff --git a/package.json b/package.json
@@ -14,11 +14,6 @@
   "scripts": {
     "benchmark:run": "node --disable-warning=ExperimentalWarning --experimental-strip-types ./bin/setup-bench.mts",
     "benchmark:setup": "node --disable-warning=ExperimentalWarning --experimental-strip-types ./bin/bench-packages.mts",
-    "browserstack:connect": "ember browserstack:connect",
-    "browserstack:disconnect": "ember browserstack:disconnect",
-    "browserstack:results": "ember browserstack:results",
-    "build:control": "rollup -c rollup.config.mjs",
-    "build:flags": "RETAIN_FLAGS=true ember build --env production --suppress-sizes",
     "clean": "node ./bin/clean.mjs",
     "link:all": "esyes ./bin/link-all.mts",
     "lint:fix": "turbo test:lint -- --fix && prettier -w .",
@@ -36,10 +31,8 @@
     "start": "vite",
     "test": "node bin/run-tests.mjs",
     "test:babel-plugins": "yarn workspace @glimmer/vm-babel-plugins test",
-    "test:browserstack": "ember test --test-port=7774 --host 127.0.0.1 --config-file=testem-browserstack.js",
     "test:lint": "eslint . --quiet",
     "test:node": "pnpm turbo test:node",
-    "test:smoke": "SMOKE_TESTS=true ember test",
     "ts": "node --disable-warning=ExperimentalWarning --experimental-strip-types",
     "unlink:all": "esyes ./bin/unlink-all.mts"
   },
@@ -83,8 +76,6 @@
     "chalk": "^5.4.1",
     "dag-map": "^2.0.2",
     "dotenv-cli": "^7.4.4",
-    "ember-cli": "~4.12.3",
-    "ember-cli-browserstack": "^2.1.0",
     "ensure-posix-path": "^1.1.1",
     "eslint": "^9.20.1",
     "eslint-config-flat-gitignore": "^1.0.0",