@kradle/challenges-sdk 0.14.0 → 0.14.1

package/CHANGELOG.md

@@ -17,6 +17,13 @@ also hand-edit this file or the [Unreleased] section at any time.
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-09-18
+
+### Changed
+
+- `README.md`, `LLM_README.md` and `MIGRATION-0.13.md`, all three in the package, show one chain by default: the root call, then the steps, then `export default challenge;`. The README quick start keeps its `damaged` handler inline, so the first example needs no helper.
+- The guides say when to split the root call from the steps: only when TypeScript needs it to resolve a circular type. This can occur when a step receives a helper typed from the same challenge (`.start(begin)`), or when a callback's return type depends on that helper (`scores: (g, p) => totalOf(g, p)`). A helper alone does not require a split, and `CtxOf<typeof challenge>` still gives it its context type.
+
 ## [0.14.0] - 2026-09-17
 
 ### Changed
@@ -207,7 +214,8 @@ also hand-edit this file or the [Unreleased] section at any time.
 - Voting primitives (`votedFor`, `promptVote`, `allVotesIn`, `assignDefaultVotes`) for challenges that use discuss-then-vote-then-act phases as an alternative to pad-based voting.
 - Build-time validation of vote IDs and options against `KRADLE_CHALLENGE_VOTING_OPTIONS` (when set), matching the existing `getLocation`/`setEndState` pattern. `promptVote` also validates each announced option against the declared `votingOptions`.
 
-[Unreleased]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.14.0...HEAD
+[Unreleased]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.14.1...HEAD
+[0.14.1]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.14.0...v0.14.1
 [0.14.0]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.13.1...v0.14.0
 [0.13.1]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.13.0...v0.13.1
 [0.13.0]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.12.0...v0.13.0

package/LLM_README.md

@@ -89,12 +89,7 @@ const challenge = defineChallenge(config, {
 	votes: { room: { options: ["red", "blue"], final: true }, player: { final: true } },
 	phases: ["BUILD", "FIGHT"],         // the names; each gets a .phase() step
 	initialPhase: "BUILD",
-});
-
-type G = CtxOf<typeof challenge>;      // the gameplay context, for helpers
-type R = ReadCtxOf<typeof challenge>;  // the read-only context, for pure helpers
-
-export default challenge
+})
 	.setup((g) => { /* the world build */ })
 	.start((g) => { /* the first tick of the game */ })
 	.phase("BUILD", { duration: "2m", next: "FIGHT", enter(g) {}, on: {} })
@@ -102,13 +97,18 @@ export default challenge
 	.on({ died(g, { player, killer }) {} })
 	.outcome({ scores: (g, p) => (p.role === "seeker" ? p.state.found : 0), winners: winBy.highestScore() })
 	.onOver((g, result) => g.say("Game over"));
+
+export default challenge;
+
+type G = CtxOf<typeof challenge>;      // the gameplay context, for helpers
+type R = ReadCtxOf<typeof challenge>;  // the read-only context, for pure helpers
 ```
 
 The root declaration holds data, the state initializers and pure predicates (a vote's `accept`). No event handler lives in it. Every literal type comes from it: the phase names, the zone names, the timer names, the vote ids and options, the roles and end states of `config`. A typo in any of them does not compile.
 
-The steps register behavior and return the same challenge object, so a definition reads as one chain or as separate statements (`challenge.on({...})` after `export default challenge`). The definition locks on first use (`init()`, or the manifest read); a step after the lock throws.
+The steps register behavior and return the same challenge object. Use one chain by default, then `export default challenge;`. Separate statements are also valid when needed. The definition locks on first use (`init()`, or the manifest read); a step after the lock throws.
 
-**Helpers.** Name the root call in a const and type helpers from it: `CtxOf<typeof challenge>` (handlers), `ReadCtxOf<typeof challenge>` (pure callbacks), `SetupCtxOf<typeof challenge>` (world builders), `PlayerIn<G>` (a player). The chain hangs off the const, so the helper's type never depends on the steps. A helper called by a root predicate is typed independently.
+**Helpers.** Use `CtxOf<typeof challenge>` (handlers), `ReadCtxOf<typeof challenge>` (pure callbacks), `SetupCtxOf<typeof challenge>` (world builders), or `PlayerIn<G>` (a player). A helper alone does not require a split. If TypeScript reports a circular type, keep the root call in a separate const and register the steps afterward. This can occur when a step receives a helper whose type depends on the same challenge (`.start(begin)`). It can also occur when a callback's return type depends on that helper (`scores: (g, p) => totalOf(g, p)`). A helper called by a root predicate needs an independent type.
 
 **State initializers.** They run once, when the last participant is connected and positioned, before `setup`. `player(p, init)` receives the observed player (position included, no state yet); `game(init)` and `player` receive `init = { params, random, players, locations }`. `init.random` is the run's seeded generator. The return value is JSON: no functions, no class instances, no player objects (store names).
 
@@ -233,8 +233,7 @@ const FORT = defineStructure({
 const MODEL = { x: 40, y: -60, z: 10 };
 const SITE = { x: 10, y: -60, z: 10 };
 
-const challenge = defineChallenge(config, { life: "respawn", duration: "10m", state: { game: () => ({ built: false }) } });
-export default challenge
+const challenge = defineChallenge(config, { life: "respawn", duration: "10m", state: { game: () => ({ built: false }) } })
 	.setup((g) => placeStructure(g, FORT, MODEL))
 	.on({
 		blocksChanged: (g) => {
@@ -244,6 +243,8 @@ export default challenge
 		},
 	})
 	.outcome({ endWhen: (g) => g.state.built, winners: (g) => (g.state.built ? g.players : []), endState: (g) => (g.state.built ? "done" : "time_up") });
+
+export default challenge;
 ```
 
 ---
@@ -344,7 +345,7 @@ export default defineChallenge(config, {
 	});
 ```
 
-A phased game with a vote, helpers and a loop:
+A phased game with a vote, helpers and a loop follows. Here the score callback returns the result of a helper typed from the challenge. The separate root call prevents a circular type.
 
 ```ts
 import { type ChallengeConfig, type CtxOf, defineChallenge, type PlayerIn, type ReadCtxOf, winBy } from "@kradle/challenges-sdk";
@@ -425,7 +426,7 @@ export default challenge
 - `openVote` on an open round throws: close it or reset it first.
 - `setScore` throws `score_derived` when `outcome.scores` exists. Pick one mode.
 - `blockCount` and `findBlocks` throw when a chunk of the box is not loaded; pass `{ partial: true }` to count what is loaded.
-- A helper typed from the challenge (`CtxOf<typeof challenge>`) takes its type from the root const, not from the full chain: keep `const challenge = defineChallenge(...)` and hang the steps off it.
+- Keep one chain unless TypeScript reports a circular type. If a helper depends on `typeof challenge` and a step depends on that helper's type, split the root call from the steps. Pass that helper to the separate steps.
 - A root predicate (`votes.x.accept`) cannot call a helper typed from the challenge.
 - Every player has `p.pos` from the initializers onward; before that, the initializers are the only code that runs, and they receive the position.
 
@@ -435,6 +436,7 @@ export default challenge
 
 - Start from `config.ts`: the roles, the end states and the params make the types. Write `as const satisfies ChallengeConfig`.
 - Put the names in the root declaration first (phases, zones, timers, votes), then write the steps. The compiler then checks every name you use.
+- Use one chain by default, followed by `export default challenge;`. Split only to resolve a circular type; do not copy a split into every challenge.
 - Prefer `outcome.scores` over manual score writes: the score is then a function of the state, computed after every event.
 - Keep `p.state` small and JSON. Copy what you keep from an event (`{ ...e.pos }`).
 - Test with `Game` before you build: a test is faster than a run, and `kradle challenge test` runs the same file under the arena's sandbox.

package/MIGRATION-0.13.md

@@ -83,13 +83,26 @@ The root declaration holds data and the state initializers: `state`, `life`, `du
 | `announce: { deaths, gameOver }`; the SDK's "=== GAME OVER ===" lines | removed: the SDK prints nothing; say it in `onOver` |
 | `mirror: {...}` | removed: the mirror holds every loaded chunk |
 | `effectFailed { kind, detail }` | `{ kind, detail, effect?, batch? }`; `g.batch(name, fn)` + `on.batchDone` |
-| `ContextOf<typeof config, typeof state>`, `typeof challenge.ctx` | `CtxOf<typeof challenge>`, `ReadCtxOf`, `SetupCtxOf`, `PlayerIn<G>`, from the root const |
+| `ContextOf<typeof config, typeof state>`, `typeof challenge.ctx` | `CtxOf<typeof challenge>`, `ReadCtxOf`, `SetupCtxOf`, `PlayerIn<G>`; split the root call only to resolve a circular type |
 | `game.state.status === "LOBBY"` (in a test) | `game.status === "CONNECTING"` (the author context has no `status` field in 0.12; a rule reads `g.status` now) |
 | `Game.begin(seed, roster)` without positions | `begin` supplies a position per participant (`at` to choose); `g.state` is the shared data, `g.reducerState` the whole state; `Fake.has` is `setInventory`; `g.all("store")` is `g.all("metric")` |
 
 ## Helpers
 
-Name the root call in a const and type the helpers from it. A helper typed from a whole chain expression and used inside that chain is circular.
+Use one chain by default, then export the completed challenge. A helper alone does not require a split.
+
+```ts
+// no-compile
+const challenge = defineChallenge(config, decl)
+	.start((g) => g.say("Start"))
+	.outcome({ winners: (g) => g.players });
+
+export default challenge;
+```
+
+Split the root call only when TypeScript needs it to resolve a circular type. This can occur when a step receives a helper typed from the same challenge. It can also occur when a callback's return type depends on that helper, such as `scores: (g, p) => totalOf(g, p)`.
+
+The next example needs a split because `endState` receives `classify` directly:
 
 ```ts
 // no-compile

package/README.md

@@ -45,10 +45,10 @@ Then run `kradle challenge test <slug>` in the consumer project.
 One root call with the data and the state initializers, then steps for the
 behavior. Every type is inferred from the root: the phase names, the zones,
 the timers, the vote options, the roles and the end states of the config.
-Helpers take their context type from the root const with `CtxOf`.
+Use one chain by default, then export the completed challenge.
 
 ```ts
-import { type ChallengeConfig, type CtxOf, defineChallenge, type PlayerIn, winBy } from "@kradle/challenges-sdk";
+import { type ChallengeConfig, defineChallenge, winBy } from "@kradle/challenges-sdk";
 
 export const config = {
 	name: "Hide and Seek",
@@ -67,25 +67,19 @@ const challenge = defineChallenge(config, {
 	life: "respawn",
 	world: { time: "day" },
 	zones: { base: { from: { x: -5, y: -60, z: -5 }, to: { x: 5, y: -55, z: 5 } } },
-});
-type G = CtxOf<typeof challenge>;
-
-/** A helper: the seeker tags a hider. */
-function tag(g: G, seeker: PlayerIn<G>, hider: PlayerIn<G>): void {
-	if (seeker.role !== "seeker" || hider.role !== "hider") return;
-	seeker.state.tags += 1;
-	g.state.found.push(hider.name);
-	g.say(`${seeker.name} found ${hider.name}!`);
-}
-
-export default challenge
+})
 	.start((g) => {
 		for (const p of g.playersWithRole("hider")) g.give(p, "minecraft:ender_pearl", 2);
 		g.say("Hiders, run! Seekers start in 30 seconds.");
 	})
 	.at([{ at: "30s", run: (g) => g.say("Seekers, go!") }])
 	.on({
-		damaged: (g, { player, attacker }) => attacker && tag(g, attacker, player),
+		damaged(g, { player, attacker }) {
+			if (attacker?.role !== "seeker" || player.role !== "hider") return;
+			attacker.state.tags += 1;
+			g.state.found.push(player.name);
+			g.say(`${attacker.name} found ${player.name}!`);
+		},
 		zoneEntered: (g, { player, zone }) => zone === "base" && g.tell(player, "You are safe here."),
 	})
 	.outcome({
@@ -94,8 +88,17 @@ export default challenge
 		winners: winBy.highestScore({ among: (g) => g.playersWithRole("seeker") }),
 		endState: (g) => (g.state.found.length === g.playersWithRole("hider").length ? "all_found" : "time_up"),
 	});
+
+export default challenge;
 ```
 
+Helpers can use `CtxOf<typeof challenge>` for their context type.
+Split the root call from the steps only when TypeScript requires it to resolve
+a circular type. This can occur when a step receives a helper typed from the
+same challenge, or when a callback's return type depends on that helper.
+Examples include `.start(begin)` and `scores: (g, p) => totalOf(g, p)`.
+A helper alone does not require a split.
+
 `p.state` is the challenge's; every other field of a player (`pos`, `health`,
 `inventory`, `score`, ...) is an observation the SDK writes. The score changes
 through `outcome.scores` (derived after every event) or `g.setScore` /

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kradle/challenges-sdk",
-	"version": "0.14.0",
+	"version": "0.14.1",
 	"publishConfig": {
 		"tag": "next"
 	},