scratch-blocks 2.1.4 → 2.1.6

package/AGENTS.md

@@ -9,7 +9,8 @@ Use these defaults unless the user asks otherwise:
 3. Never edit `node_modules/blockly/`; extend/override from `src/` instead.
 4. When adding runtime guards for states that should never happen, log actionable context unless the path is expected
    control flow.
-5. Run `npm run test:lint` after meaningful code changes.
+5. When fixing a bug, start by adding one or more tests to reproduce the issue, then implement the fix. Iterate until
+   all tests pass, including but not limited to the new tests.
 
 ## What this repository is
 
@@ -23,12 +24,14 @@ palette and workspace.
 ## Build and lint
 
 ```sh
-npm run build      # Compile TypeScript and bundle with webpack → dist/main.mjs
-npm run test:lint  # Run ESLint
+npm run build        # Compile TypeScript and bundle with webpack → dist/main.mjs
+npm run format       # Auto-format code
+npm run test:lint    # Check for lint and formatting issues (does not run other tests)
+npm run test         # Run unit and browser tests (but not lint)
+npm run test:unit    # Run unit tests only
+npm run test:browser # Run browser tests only
 ```
 
-There are test files under `tests/` but no `npm test` script is wired up yet.
-
 ## Repository layout
 
 ```text
@@ -89,26 +92,69 @@ When adding runtime checks for states that should never happen (including guard-
 
 ## TypeScript guidelines
 
-### When using non-null assertions (`!`)
+### Avoid `any`
+
+Do not use `any` as a type annotation. Prefer proper types, `unknown`, or a union. When calling into Blockly APIs
+that have weak types, add a local cast (`as ConcreteType`) with a comment explaining the narrowing rather than
+propagating `any` throughout the caller.
+
+### Non-null assertions (`!`)
+
+Do not use `!` unless you genuinely know — in a way the compiler cannot prove — that a value is non-null. Prefer:
+
+- A type guard with early return: `if (!x) return;`
+- Optional chaining for best-effort reads: `node?.getAttribute(...)`
+- Nullish coalescing for fallbacks: `value ?? default`
+
+If data is required (e.g., deserialized event fields), validate and fail with a logged error rather than asserting.
+
+Prefer narrowing once into a local variable over repeating `!` at each use site.
+
+#### Removing non-null assertions
+
+When replacing `!` due to linting, preserve the fail-fast behavior. If code would have crashed on
+`maybeNull.property`, replace with explicit validation that throws, not silent degradation:
+
+```js
+// ❌ BAD: Silently masks an error that would have been loud before
+const badResult = maybeElement?.property ?? fallback
+
+// ✅ GOOD: Turns a generic crash into a specific, actionable error with context
+if (!maybeElement) throw new Error('Missing required element')
+const goodResult = maybeElement.property
+```
+
+Only use graceful degradation (`if (!x) return`) when the situation genuinely warrants it (e.g., optional UI
+updates). For required data (configuration, mutations, required relationships), preserve the crash behavior with an
+explicit error.
+
+### Type assertions (`as`)
+
+Rely on TypeScript's inference and explicit annotations first. Use `as SomeType` only when necessary (e.g., narrowing
+a union inference can't resolve). Treat `as unknown as Type` as a last resort; add a comment explaining why it is
+both necessary and safe.
+
+### Nullish coalescing and optional chaining
+
+Prefer `??` over `|| default` for null/undefined fallbacks, and `?.` over `x && x.y` for optional member access.
+Both are safer (they don't coerce falsy values) and trigger lint errors if the left-hand side is provably non-null.
+
+### Promises
 
-Use sparingly and only when you genuinely know — in a way the compiler cannot prove — that a value is not null or
-undefined. Prefer type guards (`if (!x) return`), optional chaining (`?.`), or nullish coalescing (`??`) instead. The
-`!` operator silences the compiler without adding any runtime safety, so a misplaced one becomes a runtime crash.
+Do not leave promises floating. Either `await` the result, return it, or prefix with `void` to explicitly discard it.
+Unhandled promise rejections are silent failures.
 
-Before adding a new `!`, quickly check these alternatives:
+### Loop style
 
-- Can you narrow once and reuse a local (`const x = ...; if (!x) return;`)?
-- Can the type carry the uncertainty directly (`prop?: T`, `T | null`) and be assigned conditionally?
-- Can you use optional chaining for best-effort UI updates (`node?.setAttribute(...)`)?
-- If data is required (e.g., mutation XML attrs), can you validate and fail clearly instead of asserting?
+Prefer `for...of` over index-based `for` loops when the index is not needed.
 
-Prefer narrowing once and reusing a local variable over repeating assertions at each use site.
+### Unused values
 
-### When using type assertions (`as`)
+Keep `no-unused-vars` enabled. Preferred handling:
 
-Rely on TypeScript's inference and explicit type annotations first. Use `as SomeType` only when necessary (e.g., when
-narrowing a union that inference can't resolve). Treat `as unknown as Type` as a last resort, and add a comment
-explaining why it is both necessary and safe.
+- Remove dead locals/imports when possible.
+- For intentionally unused function parameters, prefix with `_` (e.g. `_event`).
+- For required locals in no-op/interface-conformance paths, use `void value` to mark the discard explicitly.
 
 ## Common patterns
 
@@ -133,8 +179,14 @@ explaining why it is both necessary and safe.
 
 ## Before submitting changes
 
-- Confirm changes are confined to requested scope.
-- Confirm no edits were made under `node_modules/blockly/`.
-- If you added runtime checks for states that should never happen (especially early-outs), confirm diagnostics were
-  added where appropriate.
-- Run `npm run test:lint`.
+Review all changes and confirm:
+
+- **Scope**: Changes are confined to the user request; nothing extra was added or modified.
+- **Correctness**: Changes make sense and edge cases were considered.
+- **Comments**: Comments are necessary, short, and clear; self-explanatory code has no comment.
+- **Simplicity**: Implementation is as simple as possible; no unnecessary code remains.
+- **`node_modules/`**: No changes within this directory. In particular, no direct edits to Blockly source files.
+- **Runtime checks**: Any new guards for states that should never happen include diagnostic logging.
+- **Build passes**: `npm run build` completes successfully.
+- **Tests pass**: `npm run test` completes with no failures.
+- **No lint errors**: `npm run test:lint` passes. Iterate with `npm run format` and/or manual changes as needed.

package/README.md

@@ -40,6 +40,46 @@ We provide [Scratch](https://scratch.mit.edu) free of charge, and want to keep i
 [donation](https://secure.donationpay.org/scratchfoundation/) to support our continued engineering, design, community,
 and resource development efforts. Donations of any size are appreciated. Thank you!
 
+## Development
+
+```bash
+npm ci
+npm run build
+```
+
+### Testing
+
+Unit tests run in jsdom and need no additional setup:
+
+```bash
+npm run test:unit
+```
+
+Browser tests run in Chromium via Playwright. Install the browser once after `npm ci`:
+
+```bash
+npx playwright install chromium
+npm run test:browser
+```
+
+To run all tests:
+
+```bash
+npm test
+```
+
+To debug a failing browser test with a visible browser window:
+
+```bash
+npm run test:browser -- --browser.headless=false
+```
+
+or, to also pause on startup and open devtools:
+
+```bash
+PWDEBUG=1 npm run test:browser
+```
+
 ## Committing
 
 This project uses [semantic release](https://github.com/semantic-release/semantic-release) to ensure version bumps