Boardweaver authoring reference. Sections are ordered for first-pass reading.
The current framework: game rules in /src/game.ts, the board as a React client you write.
React frontends
Framework v2 overview: the two files a v2 game ships, how writing /src/frontend.tsx upgrades a game to v2, the no-props default-export component contract, and the runtime surface that is deliberately unavailable (fetch/window/localStorage). Read first.
The match API
boardweaver/react reference: useMatch (state, click, pending, failures, online), the click lifecycle and onResult, and the derived hooks (useGameState, useSelf, usePlayers, useScores, useButtons, useAvailableActions, useImage, useGameTheme, useViewport, useColorMode).
Accessible UI primitives
boardweaver/ui: the bundled Radix primitives (Dialog, AlertDialog, Tooltip, HoverCard, Popover, ContextMenu, DropdownMenu, VisuallyHidden and 25 more), how they map onto upstream Radix docs, and why to use them instead of hand-rolling menus, dialogs and tooltips.
Animation
boardweaver/motion: the bundled Motion (framer-motion) surface — layoutId for a piece moving between spaces, AnimatePresence for pieces entering and leaving after an array splice, animating opponent moves via useLastChange, and the reduced-motion floor.
Client state and undo
Everything the platform deliberately does NOT own: selection, hover, tentative arrangements, and undo/redo — built with React state plus boardweaver/immer. Covers the arrange-then-commit undo pattern, guarding stored ids, and the memoization contract.
The game source file
/src/game.ts: the required exports, the gameConfig object (spaces/pieces/pieceDefs/scoreLabels), where source files live, and the split between the rules and the client. Read alongside react-frontend.
Game logic hooks
Signatures and contracts for gameConfig, applyActions, getAvailableActions (and its intent taxonomy), getPlayerScores, isGameOver, getButtons, preGameInitialization — plus the Action union, the legacy getSelectableItems, and why these must stay pure (the client replays them locally).
Pieces, spaces, and state buckets
PieceDef and SpaceDef subclasses: kind, dimensions, the orientations field v2 still requires, kind registries, and the static / publicState / privateState buckets that decide who can see what.
GameState API
Reading and mutating game state: the selector rules (plural string = kind, singular = id), addPiece/addSpace, property setters, player- and space-scoped lookups, and activePlayerIds for turn order.
Build a React game (workflow)
End-to-end workflow for building a v2 game: what to write first, how to keep /src/game.ts authoritative, validating .tsx, and committing. The v2 counterpart to build-game-instructions.
BWSS page styling
The style object for the compiled page surfaces (rules and marketing): the BwssStyle allow-list, color and length grammar, and $theme-token refs. Does NOT apply to /src/frontend.tsx, which is ordinary React.
Build rules instructions
How to author styled rules pages (/src/rules/*.bwss): develop the theme first, align with the author on the page outline, the rules-surface BWSS nodes (incl. Anchor links), and committing to compile.
Build marketing page instructions
How to author a styled marketing/landing page (/src/marketing/*.bwss): develop the theme first, agree the page outline, the marketing-surface BWSS nodes (incl. the special PlayButton and RulesButton), and committing to compile.
Design theme instructions
How to collaborate with the author on a visual theme — recovering mood/voice from the game, three style-tile directions, the HTML/CSS rules, iteration, and saving the chosen theme to /src/theme.html.
Game themes
The /theme.json structured theme artifact: top-level shape, colors and semanticTokens reference grammar, optional background layers, and the validation rules that gate save.
Deprecated. New games are created on the current framework, but v1 games keep running and their authors can keep editing them.
Core concepts
The render → select → action → applyActions → score loop in ~15 lines. Read first.
Source files
Required exports (gameConfig + hooks), GameStateConfigObject fields, the boardweaver import surface.
Pieces
PieceDef subclass: kind/width/height, orientations vs render(), state buckets, mouse handlers.
Spaces
SpaceDef subclass: kind/type/x/y/width/height, playerId, isPrivate, scrollable, nested pieces, render().
Actions
Action union dispatched into applyActions: SpaceClick, PieceClick, ButtonClick. Multi-step flows via metaData.
Game logic hooks
Signatures and contracts for applyActions, getSelectableItems, getPlayerScores, isGameOver, getButtons, preGameInitialization.
GameState API
GameState/Player/Piece/Space query and mutate methods, currentPlayer, activePlayerIds, addPiece/addSpace.
publicState, privateState, static, metaData
Where each data bucket lives, mutability, and viewer scrubbing for privateState.
Images
GameImageKey (string), upload flow, binding to orientations[].imageSrc, null = blank tile.
Layout and overlays
getLayout (RadialLayout | GridLayout) and renderOverlay (Overlay handle resolver, OverlayBwssNode[]).
BWSS styling
BWSS node types (Box/Image/Svg/Text/Pieces), style allow-list, color/length validators, $theme-token refs.
API reference
No-prose cheatsheet of every hook signature and every GameState/Player/Piece/Space method.
Build game instructions
How to implement a BoardWeaver game from a design — structure, hooks, state buckets, and the incremental build workflow.
Build rules instructions
How to author styled rules pages (/src/rules/*.bwss): develop the theme first, align with the author on the page outline, the rules-surface BWSS nodes (incl. Anchor links), and committing to compile.
Build marketing page instructions
How to author a styled marketing/landing page (/src/marketing/*.bwss): develop the theme first, agree the page outline, the marketing-surface BWSS nodes (incl. the special PlayButton and RulesButton), and committing to compile.
Design theme instructions
How to collaborate with the author on a visual theme — recovering mood/voice from the game, three style-tile directions, the HTML/CSS rules, iteration, and saving the chosen theme to /src/theme.html.
Game themes
The /theme.json structured theme artifact: top-level shape, colors and semanticTokens reference grammar, optional background layers, and the validation rules that gate save.