- For the board placing/removing/dragging rewrite, use:
/Users/cog/mine/pentomanim/webgl/docs/board-interaction-spec.md
- This spec is authoritative for:
- behavior rules,
- clean-state implementation plan,
- acceptance criteria.
- Compile/build output must be warning-free.
- Cursor icons must follow standard platform usage (for example:
pointer,grab,grabbing,not-allowed,progress) and match the current interaction affordance. - In source files and markdown files, keep lines under 80 characters when practical.
- Exception: exceed 80 characters when wrapping would make code awkward or less readable.
- Avoid UI layout shifts ("UI dance") on all devices when dynamic messages or actions appear/disappear.
- This issue is often most visible on small screens, but the rule applies universally.
- Reserve stable space or use visibility toggles instead of mounting/unmounting controls in flow.
- Prefer modern Svelte 5 patterns, including async and remote functions support.
- Remote functions support is optional and only needed when it helps the feature at hand.
- Treat Svelte 4 syntax as legacy tech debt and migrate it on sight.
- Svelte 5 specifics:
- Use runes (
$state,$derived,$effect) instead of$:reactive labels. - Example: replace
$: ghostPlacement = ...withconst ghostPlacement = $derived(...)(or$derived.by(...)for multi-step logic). - Use
$props()instead ofexport let. - Prefer callback props over
createEventDispatcher. - Use event attributes like
onclick={...}instead ofon:click={...}. - Do not introduce new
$$propsor$$restPropsusage.
- Use runes (
- Keep app code on Svelte 5 (
svelte@^5) and compatible Vite plugin versions. - Before shipping, verify there are no Svelte 4-style patterns left in
*.sveltefiles.
- When posting comments with
gh issue comment, preserve real newlines. - Do not include literal
\nescape sequences in posted Markdown. - Prefer
--body-filewith a heredoc for multi-line comments. - Keep comments short and actionable.
- Reference commits as short SHAs (for example:
837c44f). - Reference files with repo-relative paths (for example:
webgl/tests/drag-move-piece.spec.ts), not absolute local paths.
specmeans: restate the current spec, or a sub-spec (part of the spec).incspecmeans: incremental spec.- In practice,
incspecmeans restating the current spec or sub-spec, then applying the requested incremental changes. specmdmeans: create or update a.mdfile that contains the current requested spec (or sub-spec).- An
incspecresponse must include a section namedImprecisions / Inconsistencies. - That section must explicitly list unclear, conflicting, or underspecified points that still require decisions.