Introduce test/ directory for manual UX test cases

AGENTS.md

@@ -26,6 +26,7 @@
 | [apps](./apps)         | -                                            | -                                            | micro sites for Grida                         |
 | [library](./library)   | [`library/README.md`](./library/README.md)   | -                                            | hosted library workers                        |
 | [jobs](./jobs)         | [`jobs/README.md`](./jobs/README.md)         | -                                            | hosted jobs                                   |
+| [test](./test)         | [`test/README.md`](./test/README.md)         | [`test/AGENTS.md`](./test/AGENTS.md)         | manual test cases & UX behavior specs         |
 | [.legacy](./.legacy)   | -                                            | -                                            | will be removed (fully ignore this directory) |
 
 ## Languages, Frameworks, Tools, Infrastructures
@@ -102,7 +103,7 @@
     - `(auth)` contains the auth specific flow routes. do not modify.
     - `(insiders)` contains the insiders, local-only routes. e.g. Grida does not allow email signups, the insiders locally can.
     - `(library)` contains the Grida Library (open assets) specific pages.
     - `(preview)` contains the embed-purpose slave preview pages, maily used by the playground.
     - `(site)` similar to `(www)`, but contains pages that are not seo-purpose.
     - `(tenant)` contains the tenant-site rendered pages.
     - `(tools)` contains the standalone tools and editor pages, like playground, etc.
@@ -171,6 +172,8 @@
 
 We use turborepo (except few isolated packages).
 
+**Manual test cases** for UX behaviors that are impractical to automate live in [`test/`](./test). When fixing a UX bug or implementing interaction-heavy features, check for relevant TCs there and add new ones when appropriate (see [`test/AGENTS.md`](./test/AGENTS.md)).
+
 To run test, build, and dev, use below commands.
 
 ```sh

editor/AGENTS.md

@@ -3,6 +3,7 @@
 This package is the Next.js app that powers **`grida.co`** and tenant domains (e.g. `xyz.grida.site`, custom domains).
 
 - This doc is a curated “where to change what” map. It’s intentionally **not** exhaustive.
+- When fixing UX bugs or changing interaction behavior in `grida-canvas*`, check [`../test/`](../test/) for related manual test cases and add new ones when appropriate.
 
 ## Key rules (things that bite later)
 

editor/grida-canvas-react/viewport/ui/surface-text-editor.tsx

@@ -313,8 +313,7 @@ function WasmTextEditorRelay({ node_id }: { node_id: string }) {
       // Undo/redo: try the WASM session first (word-grouped, IME-aware).
       // When the session has nothing left, fall through to document-level
       // undo/redo so the user can undo their way out of content edit mode
-      // (see ASSERTIONS.md: "Editor History System Takes Precedence in
-      // Content Edit Mode").
+      // (see test/canvas-input-history-undo-cem.md).
       if (mod && (e.key === "z" || e.key === "Z")) {
         e.preventDefault();
         e.stopPropagation();

test/AGENTS.md

@@ -0,0 +1,34 @@
+# `test`
+
+Manual test cases and UX behavior specifications that are impractical to automate.
+
+## When to add a new TC
+
+- You fixed a UX bug that required human interaction to verify — document it here so it doesn't regress silently.
+- You implemented a UX behavior with subtle invariants (z-order, modifier keys, pointer events) that would be fragile or verbose as code tests.
+- You discovered an edge case during development that only manifests through real user interaction.
+
+Do **not** add entries for pure logic, math, or data transformations — those belong in co-located `__tests__/` or `*.test.ts` files.
+
+## How to add
+
+1. Copy `_template.md` and rename: `{module}-{area}-{short-description}.md`
+2. Assign a unique ID: `TC-{MODULE}-{AREA}-{NNN}` (increment NNN within the module+area)
+3. Fill in all frontmatter fields — `status` starts as `untested`
+4. Write the `## Behavior` section as natural-language prose (design rationale, not just steps)
+5. Write `## Steps` with enough detail for someone unfamiliar to verify
+
+## How to reference from code
+
+When code implements behavior documented here, add a comment pointing to the file:
+
+```ts
+// (see test/canvas-input-history-undo-cem.md)
+```
+
+## Rules
+
+- **One behavior per file.** If a TC covers two independent behaviors, split it.
+- **Never delete a TC** — set `status: deprecated` instead (preserves history).
+- **When automating**: write the code test, add its path to `covered_by`, set `status: deprecated` once fully covered.
+- **Keep prose stable.** Frontmatter fields change freely, but avoid rewriting `## Behavior` unless the actual behavior changed — git blame on that section is the audit trail.

test/README.md

@@ -0,0 +1,43 @@
+# Evals — Test Case Registry
+
+This directory contains structured test case (TC) specifications for behaviors that are difficult or impractical to cover with automated tests. These are primarily UX interactions requiring human judgment, visual verification, or complex multi-step browser interaction.
+
+## Purpose
+
+- **Regression tracking**: Document behaviors that have broken before and need manual verification after refactors.
+- **Feature specification**: Record intended behavior and design decisions as verifiable descriptions.
+- **Future test specs**: Natural-language descriptions that can guide manual QA or future automation efforts.
+
+## What does NOT belong here
+
+Core math, algorithmic, or low-level features should be covered by formal unit/integration tests co-located with their source code (`__tests__/`, `*.test.ts`, `cargo test`). Only add entries here when automated testing is impractical or would bloat the test suite unnecessarily.
+
+## File naming
+
+```
+{module}-{area}-{short-description}.md
+```
+
+Examples: `canvas-resize-vector-aspect-ratio.md`, `forms-validation-conditional-fields.md`
+
+## Frontmatter
+
+Every file uses YAML frontmatter for machine-parseable metadata. See `_template.md` for the full schema.
+
+Key fields:
+
+| Field        | Description                                                    |
+| ------------ | -------------------------------------------------------------- |
+| `id`         | Stable unique ID: `TC-{MODULE}-{AREA}-{NNN}`                  |
+| `module`     | Top-level module: `canvas`, `forms`, `database`, `editor`, ... |
+| `area`       | Sub-domain within the module                                   |
+| `status`     | `untested` · `verified` · `regression` · `deprecated`         |
+| `severity`   | `low` · `medium` · `high` · `critical`                        |
+| `automatable`| Whether this can eventually become a code test                 |
+| `covered_by` | Paths to test files if partially automated                     |
+
+## Workflow
+
+1. **Adding a new TC**: Copy `_template.md`, rename following the naming convention, fill in frontmatter and body.
+2. **After a refactor**: Filter by module/area, manually verify TCs marked `verified` or `regression`.
+3. **Promoting to code**: When a TC becomes automatable, write the test, add its path to `covered_by`, and set `status: deprecated` once fully covered.

test/_template.md

@@ -0,0 +1,27 @@
+---
+id: TC-MODULE-AREA-NNN
+title: Short descriptive title
+module: canvas
+area: resize
+tags: []
+status: untested
+severity: medium
+date: YYYY-MM-DD
+updated: YYYY-MM-DD
+automatable: false
+covered_by: []
+---
+
+## Behavior
+
+Describe the expected behavior in natural language. Focus on *what* should happen and *why* — design rationale, invariants, and edge cases.
+
+## Steps
+
+1. Set up the initial state
+2. Perform the action
+3. Expected: describe the observable outcome
+
+## Notes
+
+Optional: history, related issues, links to code, edge cases discovered during testing.