gridfinity-layout-tool

BREP generation pipeline in src/features/generation — adding/changing bin features (cutouts, handles, patterns, text), wall-pattern border clipping, overhang/inner dims, shapeCache keys, dual-kernel draft-vs-export parity, generation.worker.ts / WASM kernel lifecycle, brepjs bumps. Symptoms — jagged wall edges, stale preview after param edit, draft missing a feature, non-manifold export, "Cannot pass deleted object", timeouts after generator changes.

Zustand stores (src/core/store/) and the CQRS v2 pipeline (src/core/cqrs/) — adding a command/event end-to-end with defineCommand and its hand-maintained registries, undo capture and batch(), event versioning/migrations, persistence (localStorage/IndexedDB/useAutoSave), the init-time-literal store rule (#1466), useShallow. Symptoms: "No handler registered for command type", undo toast shows generic "Undid: Action", Ctrl+Z not reverting, "Maximum update depth exceeded", "Missing migration".

Write and run tests — Vitest three-project routing (unit/dom/generators), src/test/ utilities (resetAllStores, createTestLayout, expectOk), real-WASM geometry scenario tests and triangleCount snapshot updates, __kernel-tests__ profile config, Playwright e2e/smoke/visual, benchmarks. Load for "document is not defined", "Cannot pass deleted object", tests passing alone but failing in the full run, flaky e2e, coverage-threshold failures, or updating scenario snapshots.

PostHog event conventions (trackEvent, snake_case names, #1466 import-cycle rule), ML telemetry pipeline (/api/ml-telemetry, label hashing), labs feature flags (FEATURE_FLAGS, useFeatureFlag, graduate/remove), and shared-hook traps (stale closures, cross-tab sync, auto-save races). Load when adding/renaming analytics events, adding or removing a labs flag, debugging "event never appears", "flag toggle does nothing", or "blank page in production build".

OAuth sign-in (api/auth/: login, callback, me, logout, Arctic providers) and per-user cloud sync (api/sync/: layouts, designs, manifest, export, account; src/core/sync/ engine). Use when debugging sync 401/403/409/410/413, forced sign-out, LWW conflicts, tombstone resurrection, manifest 304/If-Modified-Since staleness, index↔blob drift (pnpm sync-admin), GOOGLE_/GITHUB_CLIENT_ID / OAUTH_REDIRECT_BASE_URL env, or the __Host-gflt_session cookie.

Custom bin editor (src/features/bin-designer/) — compartment grid model and the normalizeIdsWithRemap parallel-array rule, epoch-based worker regeneration via pushHistoryEntry, label tabs/compartmentTexts, wall cutouts/handles, and the client/server validation mirror in api/lib/designerValidation.ts. Load when adding a BinParams field, editing merge/split/setCompartmentGrid, labels land on the wrong compartment, cloud sync returns 400 INVALID_PARAMS, or the 3D preview stops updating.

SEO/content pages: adding a landing page end-to-end (content/*.md → scripts/build-content.ts → public/<slug>/index.html), the "⚠ ... chars" SERP title/description warnings, sitemap.xml + hreflang, regenerating OG cards and screenshots (pnpm run gen:seo-images, gen:example-thumbnails), /designer + /baseplate static heads (scripts/build-route-entries.ts), editing index.html meta/JSON-LD, and the phone-scan handoff endpoint api/scan-session.ts ("scan" PR scope).

Cross-cutting debugging method for any bug report or regression — git archaeology on fix commits, reproduce-first, fixing every layer — plus an index of the trap classes that recur in git history. Load when a symptom has no obvious owning subsystem, when a fix "works" but you cannot explain why, or for symptoms like silent bounding-box fallbacks, preview-vs-export divergence, half-grid crashes, wedged workers, "undefined (reading dispatch)", or a slicer rejecting a 3MF.

Anatomy of a src/features/ slice and the UI layer rules — adding a new slice, module boundaries (check-module-boundaries.sh, eslint boundaries), design-system-only primitives (check-design-system-usage.sh), lazyWithRetry, and the three responsive shell trees in App.tsx. Load when creating a feature/panel/modal, when a commit is blocked by VIOLATION/design-system/component-structure checks, or when a feature works on desktop but is missing on mobile/tablet.

Validate and debug bin/baseplate geometry changes — failing binGenerator.scenario tests, triangleCount snapshot churn, NaN/0-triangle/degenerate meshes, non-manifold or non-watertight exports, preview differs from exported STL/3MF, worker generation timeout or wedged worker, half-grid (x.5) crashes, __kernel-tests__ that never run, BREPJS_KERNEL kernel selection.

2D layout canvas — pointer interactions (draw/drag/resize/stagingDrag/paint in useInteraction.ts and src/shared/hooks/interactions/), __staging__ stash semantics, layer view modes, half-grid 0.5 snapping, collision/blocked zones, canPlaceBin validation. Load for symptoms like offset drag ghosts, mirrored Y placement, phantom collisions, bins drifting in the stash, laggy drag previews, or half-grid toggle failing.

Adding/renaming/removing translation keys in src/i18n/locales/en.ts and the 9 locale JSONs, fixing the four i18n check failures ("i18n key mismatch detected", "Untranslated values detected", "interpolation mismatch detected", "Unused i18n keys detected"), the missing en.json TS2307 error, the values allowlist, plurals without ICU, and adding a new locale.

3MF/STL/STEP file export, slicer compatibility (BambuStudio/OrcaSlicer rejects 3MF, wrong/missing AMS colors, paint_color, project_settings.config), print-bed fitting and printBedSize, print-list bin splitting, baseplate split planner tongue budget, whole-layout ZIP export. Load when touching threemfExporter.ts, stlExporter.ts, splitPlanner.ts, src/features/print-export/, or src/shell/layoutExport/, or when an exported file misbehaves in a slicer.

Every commit gate and its legitimate unblock — .husky/pre-commit scripts, .claude/hooks PreToolUse blockers, custom ESLint rules (no-init-time-imported-call, React.lazy ban, GRID_SIZE arithmetic ban), pnpm quality, size-limit budgets. Load when a `git commit` is blocked ("switch on X missing cases", "without justification", "VIOLATION features/A → features/B", "must be in a named folder"), when pnpm run size fails, or before pushing.

PR-to-production pipeline — failed CI checks (Build, Unit Tests Complete, Quality, PWA Smoke Test, Conventional Commit), bundle-size (size-limit) failures, PR title rules, release-please version bumps, stuck "chore(main): release" PRs, Vercel deploy/skip logic, production rollback, "Production smoke failed" issues, editing .github/workflows/*.

Cloud share API (api/share.ts, api/share/[id].ts, api/lib/*) and Liveblocks collab (api/liveblocks-auth.ts, src/liveblocks.config.ts, src/shell/Collab/). Use when changing share validation/rate limits/content filter, adding an /api endpoint, debugging 429/503/409/CONTENT_BLOCKED, "Missing user ID" Liveblocks auth failures, read-only collab rooms, stale shared layouts, TOKEN_SALT/REDIS_URL env issues, or presence fields.

The 3D render systems (layout IsometricPreview vs worker-mesh bin-designer/baseplate previews), view store, camera, disposal/memory rules. Load when touching IsometricPreview.tsx, Scene.tsx, BinMesh.tsx, PreviewCanvas.tsx, useBinGeometry.ts, view.ts, or debugging z-fighting/flicker, GPU memory growth, a preview frozen until you orbit, wrong scene scale (42x off), theme-wrong scene colors, or bins replaying drop animations on every edit.