From 92c68ec4f63a7a0d6cbbcd0e975c6eafd54d06f1 Mon Sep 17 00:00:00 2001
From: Quintine <15965533+Quintine@users.noreply.github.com>
Date: Tue, 27 Oct 2026 19:23:23 +1100
Subject: [PATCH] Expose Basic Kull preview in lobby
---
components/game-table.tsx | 12 ++
docs/CHOAM_KULL_DESIGN.md | 38 +++++-
docs/CURRENT_STATUS.md | 11 ++
docs/IMPLEMENTATION_STATUS.md | 16 +++
docs/RULE_DECISIONS.md | 12 ++
game/engine.ts | 18 ++-
game/faction-reference.ts | 2 +-
game/reference.ts | 4 +-
tests/fixture-public-choam-kull.ts | 66 ++++++++++
tests/public-choam-kull-controls.test.tsx | 54 ++++++++
tests/public-choam-kull-runtime.test.ts | 152 ++++++++++++++++++++++
11 files changed, 375 insertions(+), 10 deletions(-)
create mode 100644 tests/fixture-public-choam-kull.ts
create mode 100644 tests/public-choam-kull-controls.test.tsx
create mode 100644 tests/public-choam-kull-runtime.test.ts
diff --git a/components/game-table.tsx b/components/game-table.tsx
index bfff4520..139ecca0 100644
--- a/components/game-table.tsx
+++ b/components/game-table.tsx
@@ -2203,6 +2203,18 @@ export function GameTable({
{label} · preview
))}
+
+
+ {g.lobbyModules?.kullPreview &&
+ Requires Basic CHOAM and classic factions, both CHOAM and Ix decks, and no other optional modules.
+ This preview does not support structured Truthtrance questions about bids, bribes, alliances, Revival,
+ or combined turn actions, and it defers unfunded non-CHOAM Karama-dependent bids. It does not represent complete
+ CHOAM rules. Every player must ready again after changing it.
+
}
;
+export const publicKullAttempt = (f: PublicChoamKullFixture): Action =>
+ ({type:'card',mode:'shipment',card:f.karama,target:f.actor});
diff --git a/tests/public-choam-kull-controls.test.tsx b/tests/public-choam-kull-controls.test.tsx
new file mode 100644
index 00000000..ab555831
--- /dev/null
+++ b/tests/public-choam-kull-controls.test.tsx
@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { registerHooks } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { viewGame, type GameView } from '../game/engine';
+import { act, createPublicChoamKullFixture as fixture, publicKullAttempt as attempt } from './fixture-public-choam-kull';
+
+const aliases = registerHooks({
+ resolve(specifier, context, next) {
+ return next(specifier === 'next/image' ? 'vinext/shims/image' : specifier === 'next/link' ? 'vinext/shims/link' : specifier, context);
+ },
+ load(url, context, next) {
+ if (!url.endsWith('.module.css')) return next(url, context);
+ const css = readFileSync(new URL(url),'utf8');
+ const classes = Object.fromEntries([...css.matchAll(/\.([a-zA-Z_][\w-]*)/g)].map(match => [match[1],match[1]]));
+ return {format:'module',source:`export default ${JSON.stringify(classes)}`,shortCircuit:true};
+ },
+});
+const { GameTable } = await import('../components/game-table');
+const { ChoamKull } = await import('../components/choam-kull');
+aliases.deregister();
+const table = (game: GameView,busy = false) => renderToStaticMarkup(createElement(GameTable,
+ {game,busy,send:async () => {},onExit() {}}));
+const reaction = (game: GameView,busy = false) => renderToStaticMarkup(createElement(ChoamKull,
+ {game,busy,act() {}}));
+
+void test('public host lobby shows the explicitly selected Kull preview and its limits', () => {
+ const f = fixture(), host = viewGame(f.lobby,f.lobby.host), html = table(host);
+ assert.equal(host.lobbyModules?.kullPreview,true);
+ assert.match(html,/Kull Wahad · Basic development preview/);
+ assert.match(html,/does not support structured Truthtrance questions about bids/);
+ assert.match(html,/defers unfunded non-CHOAM Karama-dependent bids/);
+ const off = act(f.lobby,f.lobby.host,{type:'moduleOption',module:'kullPreview',enabled:false});
+ const unselected = viewGame(off,off.host);
+ assert.equal(unselected.lobbyModules?.kullPreview,false);
+ assert.match(table(unselected),/Kull Wahad · Basic development preview/);
+ assert.doesNotMatch(table(unselected),/does not support structured Truthtrance questions about bids/);
+ const nonhost = table(viewGame(f.lobby,f.actor));
+ assert.match(nonhost,/disabled=""[^>]*type="checkbox"|type="checkbox"[^>]*disabled=""/);
+});
+
+void test('the real public table exposes Kull use and decline only to the reactor', () => {
+ const f = fixture(), offered = act(f.game,f.actor,attempt(f));
+ const holder = viewGame(offered,f.reactor), other = viewGame(offered,f.actor);
+ assert.match(reaction(holder),/Use Kull Wahad/);
+ assert.match(reaction(holder),/Decline Kull/);
+ assert.match(table(holder),/aria-label="Kull Wahad response"/);
+ assert.match(table(holder),/Use Kull Wahad/);
+ assert.match(reaction(holder,true),/disabled=""[^>]*>Use Kull Wahad/);
+ assert.doesNotMatch(reaction(other),/Use Kull Wahad|Decline Kull|ix-kull-wahad/);
+ assert.match(reaction(other),/Waiting for/);
+});
diff --git a/tests/public-choam-kull-runtime.test.ts b/tests/public-choam-kull-runtime.test.ts
new file mode 100644
index 00000000..2e96502b
--- /dev/null
+++ b/tests/public-choam-kull-runtime.test.ts
@@ -0,0 +1,152 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createGame, joinGame, newPlayer, viewGame, type Action, type Game } from '../game/engine';
+import { botActions } from '../game/bots';
+import { DIFFICULTIES } from '../game/bot-profiles';
+import { bribePromiseModeSupported } from '../game/bribe-promises';
+import { act, advance, clean, createPublicChoamKullFixture as fixture, player,
+ publicKullAttempt as attempt, publicKullInventory as inventory } from './fixture-public-choam-kull';
+
+const held = (g: Game,id: string,card: string) => player(g,id).hand.some(c => c.id === card);
+function reject(g: Game,id: string,action: Action) {
+ const before = structuredClone(g); assert.throws(() => act(g,id,action)); assert.deepEqual(g,before);
+}
+function createLobby(advanced = false, expansions: string[] = ['choam','ix'], last: 'guild'|'ixians' = 'guild') {
+ const game = createGame('KULLLOBBY',newPlayer('choam','CHOAM','choam'),advanced,expansions);
+ joinGame(game,newPlayer('emperor','Emperor','emperor'));
+ joinGame(game,newPlayer(last,last,last));
+ return game;
+}
+function ready(g: Game) {
+ for (const seat of g.players) g = act(g,seat.id,{type:'ready'});
+ return g;
+}
+function declare(g: Game,kull: string) {
+ const reaction = viewGame(g,'choam').kullReaction; assert.ok(reaction);
+ return act(g,'choam',{type:'kullDecision',event:reaction.event,source:'printed',card:kull});
+}
+
+void test('Kull is a host-selected lobby preview and default Basic Truth promises retain their existing scope', () => {
+ let lobby = createLobby();
+ assert.equal(lobby.lobbyOptions?.kullPreview,undefined);
+ assert.equal(bribePromiseModeSupported(lobby),true);
+ reject(lobby,'emperor',{type:'moduleOption',module:'kullPreview',enabled:true});
+ reject(lobby,'choam',{type:'moduleOption',module:'kullPreview',enabled:'true'});
+ reject(lobby,'choam',{type:'moduleOption',module:'kullPreview',enabled:true,other:true});
+ const baseline = act(ready(lobby),'choam',{type:'start'});
+ assert.equal(baseline.kullPreview ?? false,false);
+ assert.equal(bribePromiseModeSupported(baseline),true);
+ lobby = ready(lobby);
+ lobby = act(lobby,'choam',{type:'moduleOption',module:'kullPreview',enabled:true});
+ assert.ok(lobby.players.every(seat => !seat.ready));
+ assert.equal(lobby.lobbyOptions?.kullPreview,true);
+ lobby = act(lobby,'choam',{type:'moduleOption',module:'kullPreview',enabled:false});
+ assert.equal(lobby.lobbyOptions?.kullPreview,undefined);
+ const f = fixture();
+ assert.equal(f.setup.kullPreview,true);
+ assert.equal(bribePromiseModeSupported(f.setup),false,'The opt-in explicitly retains the existing partial promise boundary');
+ assert.ok(f.actions.some(row => row.actor === f.lobby.host && row.action.type === 'start'));
+});
+
+void test('incompatible opt-in starts reject without modifying their original lobby', () => {
+ for (const config of [
+ {advanced:true,expansions:['choam','ix'],last:'guild' as const,module:false},
+ {advanced:false,expansions:['choam'],last:'guild' as const,module:false},
+ {advanced:false,expansions:['choam','ix'],last:'ixians' as const,module:false},
+ {advanced:false,expansions:['choam','ix'],last:'guild' as const,module:true},
+ ]) {
+ let g = createLobby(config.advanced,config.expansions,config.last);
+ g = act(g,'choam',{type:'moduleOption',module:'kullPreview',enabled:true});
+ if (config.module) g = act(g,'choam',{type:'moduleOption',module:'leaderSkills',enabled:true});
+ g = ready(g);
+ reject(g,'choam',config.advanced ? {type:'start',advancedPreview:true} : {type:'start'});
+ }
+});
+
+void test('public Kull offer, decline, successful use, and distinct counter retain native custody and income', () => {
+ const f = fixture(), original = structuredClone(f.game), sourceCards = inventory(original);
+ assert.equal(original.kullPreview,true); assert.deepEqual(sourceCards,f.originalCards);
+ const wallet = original.players.map(p => p.spice), forces = original.players.map(p => ({forces:p.forces,reserves:p.reserves,tanks:p.tanks}));
+ const offered = act(original,f.actor,attempt(f));
+ assert.equal(offered.pendingKull?.stage,'offer');
+ assert.equal(offered.karamaShipping,null);
+ assert.ok(held(offered,f.actor,f.karama));
+ assert.deepEqual(offered.players.map(p => p.spice),wallet);
+ assert.deepEqual(offered.players.map(p => ({forces:p.forces,reserves:p.reserves,tanks:p.tanks})),forces);
+ for (const outsider of [f.actor,f.counterOwner]) {
+ const reaction = viewGame(offered,outsider).kullReaction; assert.ok(reaction);
+ assert.equal(reaction.canDecline,false); assert.deepEqual(reaction.plays,[]);
+ }
+ const reaction = viewGame(offered,f.reactor).kullReaction; assert.ok(reaction);
+ assert.ok(reaction.plays.some(play => play.source === 'printed' && play.card.id === f.kull && !play.blocked));
+ reject(offered,f.counterOwner,{type:'kullDecision',event:reaction.event,decline:true});
+ reject(offered,f.reactor,{type:'kullDecision',event:'stale',decline:true});
+ const declined = act(offered,f.reactor,{type:'kullDecision',event:reaction.event,decline:true});
+ assert.equal(declined.pendingKull,null);
+ assert.equal(declined.karamaShipping?.owner,f.actor);
+ assert.equal(declined.discard.filter(card => card.id === f.karama).length,1);
+ assert.ok(held(declined,f.reactor,f.kull));
+ assert.deepEqual(inventory(declined),sourceCards);
+ const declared = declare(offered,f.kull);
+ const successful = advance(declared,clean);
+ assert.equal(successful.karamaShipping,null);
+ assert.ok(held(successful,f.actor,f.karama));
+ assert.equal(successful.discard.filter(card => card.id === f.kull).length,1);
+ assert.deepEqual(successful.players.map(p => p.spice),wallet);
+ assert.deepEqual(inventory(successful),sourceCards);
+ reject(successful,f.actor,attempt(f));
+ const counter = viewGame(declared,f.counterOwner).responseControls?.cancelCards ?? [];
+ assert.ok(counter.includes(f.counter),'The distinct original Guild Karama is a legal counter');
+ const interrupted = act(declared,f.counterOwner,{type:'card',mode:'cancel',card:f.counter});
+ const resumed = advance(interrupted,clean);
+ assert.equal(resumed.pendingKull,null);
+ assert.equal(resumed.karamaShipping?.owner,f.actor);
+ assert.ok(held(resumed,f.reactor,f.kull));
+ assert.equal(resumed.discard.filter(card => card.id === f.karama).length,1);
+ assert.equal(resumed.discard.filter(card => card.id === f.counter).length,1);
+ assert.deepEqual(inventory(resumed),sourceCards);
+});
+
+void test('neutral public offer and deferred overbid do not depend on holding Kull', () => {
+ const f = fixture(), absent = structuredClone(f.game), owner = player(absent,f.reactor);
+ // Conserved controlled supplement: swap the original held Kull and a physical
+ // undealt deck card; this is not an earned trade or a new card.
+ const heldIndex = owner.hand.findIndex(card => card.id === f.kull); assert.ok(heldIndex >= 0);
+ assert.ok(absent.deck.length); [owner.hand[heldIndex],absent.deck[0]] = [absent.deck[0],owner.hand[heldIndex]];
+ assert.deepEqual(inventory(absent),f.originalCards);
+ const withCard = act(f.game,f.actor,attempt(f)), withoutCard = act(absent,f.actor,attempt(f));
+ assert.deepEqual(viewGame(withCard,f.actor).kullReaction,viewGame(withoutCard,f.actor).kullReaction);
+ const auctionWithout = structuredClone(f.auction), auctionOwner = player(auctionWithout,f.reactor);
+ const index = auctionOwner.hand.findIndex(card => card.id === f.kull); assert.ok(index >= 0);
+ assert.ok(auctionWithout.deck.length); [auctionOwner.hand[index],auctionWithout.deck[0]] = [auctionWithout.deck[0],auctionOwner.hand[index]];
+ for (const g of [f.auction,auctionWithout]) {
+ const amount = player(g,f.actor).spice + 1;
+ reject(g,f.actor,{type:'bid',amount});
+ assert.notEqual(g.auction?.bidder,f.actor);
+ assert.ok(held(g,f.actor,f.karama));
+ }
+});
+
+void test('all four profiles use only the projected physical Kull cost', () => {
+ const f = fixture(), offered = act(f.game,f.actor,attempt(f));
+ for (const difficulty of DIFFICULTIES) {
+ const v = viewGame(offered,f.reactor); v.players.find(p => p.id === f.reactor)!.bot = difficulty;
+ const action = botActions(v)[0]; assert.ok(action,difficulty);
+ assert.deepEqual(action,{type:'kullDecision',event:v.kullReaction!.event,source:'printed',card:f.kull});
+ const result = act(offered,f.reactor,action); assert.equal(result.pendingKull?.stage,'counter');
+ assert.deepEqual(inventory(result),f.originalCards);
+ }
+});
+
+void test('a legacy unmarked Basic game retains its original Karama path', () => {
+ const f = fixture(), legacy = structuredClone(f.game);
+ // This controlled legacy-shape supplement removes the opt-in stamp only;
+ // the original cards, turn, board and wallets remain from native play.
+ delete legacy.kullPreview;
+ const completed = act(legacy,f.actor,attempt(f));
+ assert.equal(completed.pendingKull ?? null,null);
+ assert.equal(completed.karamaShipping?.owner,f.actor);
+ assert.equal(completed.discard.filter(card => card.id === f.karama).length,1);
+ assert.ok(held(completed,f.reactor,f.kull));
+ assert.deepEqual(inventory(completed),f.originalCards);
+});