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.
Images, fonts, and assets
Uploaded art (JPEG/PNG only, 5 MB, key rules, replace vs auto-uniquify, no delete), useImage, bulk upload via API token, vector art with inline SVG, Google Fonts as the one custom-font path, the frame CSP, and what does and does not count against the bundle cap.
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.
For organizers: putting a game in front of a room, a class, or a blind playtest.
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.