@johnmorrisdotca/kumimoji 1.2.2 → 1.3.1

package/dist/computerTurn.d.ts

@@ -24,9 +24,48 @@ import type { TileWords } from "./tileWords.ts";
  * - Resign only where the rules offer it (`mayResign`) and it can do nothing
  *   at all: nothing to lay, nothing to trade for, and it is not its last turn.
  */
-/** The most things a computer does in one turn before pressing Done: at the page's pause, a turn of about three seconds. */
+/** The most things a computer does in one turn before pressing Done: at the page's pause, a turn of about three seconds.
+ *
+ * @example
+ * ```ts
+ * import { COMPUTER_STEPS_MOST } from "@johnmorrisdotca/kumimoji";
+ * console.log(COMPUTER_STEPS_MOST);
+ * ```
+ */
 export declare const COMPUTER_STEPS_MOST = 8;
-/** A computer seat's whole turn as its steps, in order, for a page to show one at a time. None when it is not a computer's turn or the game is over. */
+/** A computer seat's whole turn as its steps, in order, for a page to show one at a time. None when it is not a computer's turn or the game is over.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns A computer seat's whole turn as its steps, in order, for a page to show one at a time. None when it is not a computer's turn or the game is over.
+ * @example
+ * ```ts no-run
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { planComputerTurn, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(planComputerTurn(game,words).map(step=>step.said));
+ * ```
+ */
 export declare function planComputerTurn(game: PartyGame, words: TileWords): ComputerStep[];
-/** The game a computer's turn passes on: its plan's last step, or the game as it was where there is nothing to play. */
+/** The game a computer's turn passes on: its plan's last step, or the game as it was where there is nothing to play.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns The game a computer's turn passes on: its plan's last step, or the game as it was where there is nothing to play.
+ * @example
+ * ```ts no-run
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { afterComputerTurn, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(afterComputerTurn(game,words).turn);
+ * ```
+ */
 export declare function afterComputerTurn(game: PartyGame, words: TileWords): PartyGame;

package/dist/computerTurn.js

@@ -1,6 +1,6 @@
 import { bestLaying, judgeTiles, tradeChoice } from "./computerPlay.js";
 import { drawAll, isComputer, mayDrawAll, mayTradeThisTurn, seatPlay, withSeatPlay } from "./party.js";
-import { doneRefused, endTurn, goesOut, handCanSpell, isLastTurn, laidThisTurn, mayResign, resign } from "./partyTurns.js";
+import { doneRefused, endTurn, goesOut, handCanSpell, isLastTurn, laidThisTurn, mayResign, resign, } from "./partyTurns.js";
 import { liftAll, mayTrade, trade } from "./play.js";
 /**
  * A COMPUTER'S TURN in a pass-and-play game (John, 2026-09-28: "Also you can
@@ -25,11 +25,34 @@ import { liftAll, mayTrade, trade } from "./play.js";
  * - Resign only where the rules offer it (`mayResign`) and it can do nothing
  *   at all: nothing to lay, nothing to trade for, and it is not its last turn.
  */
-/** The most things a computer does in one turn before pressing Done: at the page's pause, a turn of about three seconds. */
+/** The most things a computer does in one turn before pressing Done: at the page's pause, a turn of about three seconds.
+ *
+ * @example
+ * ```ts
+ * import { COMPUTER_STEPS_MOST } from "@johnmorrisdotca/kumimoji";
+ * console.log(COMPUTER_STEPS_MOST);
+ * ```
+ */
 export const COMPUTER_STEPS_MOST = 8;
 /** How many settling steps may be needed at the end to be allowed Done at all; one trade a turn and a hand of tiles, so it is bounded anyway. */
 const SETTLING_MOST = 200;
-/** A computer seat's whole turn as its steps, in order, for a page to show one at a time. None when it is not a computer's turn or the game is over. */
+/** A computer seat's whole turn as its steps, in order, for a page to show one at a time. None when it is not a computer's turn or the game is over.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns A computer seat's whole turn as its steps, in order, for a page to show one at a time. None when it is not a computer's turn or the game is over.
+ * @example
+ * ```ts no-run
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { planComputerTurn, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(planComputerTurn(game,words).map(step=>step.said));
+ * ```
+ */
 export function planComputerTurn(game, words) {
     const steps = [];
     if (game.ending !== null || !isComputer(game, game.turn))
@@ -77,7 +100,10 @@ export function planComputerTurn(game, words) {
             break;
     }
     const hand = now.players[now.turn].hand;
-    const stuck = hand.length > 0 && !laidThisTurn(now) && !mayTrade(seatPlay(now)) && bestLaying(seatPlay(now), words, rules) === null;
+    const stuck = hand.length > 0 &&
+        !laidThisTurn(now) &&
+        !mayTrade(seatPlay(now)) &&
+        bestLaying(seatPlay(now), words, rules) === null;
     const refused = doneRefused(now, verdict(), handSpells) !== null;
     if ((refused || (stuck && !isLastTurn(now))) && mayResign(now)) {
         take(resign(now), { kind: "resigned" });
@@ -89,7 +115,23 @@ export function planComputerTurn(game, words) {
     take(endTurn(now, verdict(), handSpells), { kind: "done", out: goesOut(now, verdict()) });
     return steps;
 }
-/** The game a computer's turn passes on: its plan's last step, or the game as it was where there is nothing to play. */
+/** The game a computer's turn passes on: its plan's last step, or the game as it was where there is nothing to play.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns The game a computer's turn passes on: its plan's last step, or the game as it was where there is nothing to play.
+ * @example
+ * ```ts no-run
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { afterComputerTurn, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(afterComputerTurn(game,words).turn);
+ * ```
+ */
 export function afterComputerTurn(game, words) {
     return planComputerTurn(game, words).at(-1)?.game ?? game;
 }

package/dist/daily.d.ts

@@ -8,7 +8,27 @@
  * hand, level, length) gets the same bag, in the same order. The race against
  * the clock is then theirs.
  */
-/** The day a moment falls on, in UTC, written `YYYY-MM-DD`. Throws a `RangeError` for an invalid `Date`. */
+/** The day a moment falls on, in UTC, written `YYYY-MM-DD`. Throws a `RangeError` for an invalid `Date`.
+ *
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns The day a moment falls on, in UTC, written `YYYY-MM-DD`. Throws a `RangeError` for an invalid `Date`.
+ * @example
+ * ```ts
+ * import { kumimojiDay } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiDay(new Date("2026-10-12T12:00:00Z")));
+ * ```
+ */
 export declare function kumimojiDay(at: Date): string;
-/** Today's seed, the date as a number: 2026-10-01 is 20261001. The day is UTC, so it is one seed worldwide. */
+/** Today's seed, the date as a number: 2026-10-01 is 20261001. The day is UTC, so it is one seed worldwide.
+ *
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns Today's seed, the date as a number: 2026-10-01 is 20261001. The day is UTC, so it is one seed worldwide.
+ * @example
+ * ```ts
+ * import { kumimojiDailySeed } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiDailySeed(new Date("2026-10-12T12:00:00Z")));
+ * ```
+ */
 export declare function kumimojiDailySeed(at: Date): number;

package/dist/daily.js

@@ -9,14 +9,34 @@
  * the clock is then theirs.
  */
 const pad = (value, width) => String(value).padStart(width, "0");
-/** The day a moment falls on, in UTC, written `YYYY-MM-DD`. Throws a `RangeError` for an invalid `Date`. */
+/** The day a moment falls on, in UTC, written `YYYY-MM-DD`. Throws a `RangeError` for an invalid `Date`.
+ *
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns The day a moment falls on, in UTC, written `YYYY-MM-DD`. Throws a `RangeError` for an invalid `Date`.
+ * @example
+ * ```ts
+ * import { kumimojiDay } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiDay(new Date("2026-10-12T12:00:00Z")));
+ * ```
+ */
 export function kumimojiDay(at) {
     if (Number.isNaN(at.getTime()))
         throw new RangeError("kumimoji: an invalid Date has no day");
     return `${pad(at.getUTCFullYear(), 4)}-${pad(at.getUTCMonth() + 1, 2)}-${pad(at.getUTCDate(), 2)}`;
 }
-/** Today's seed, the date as a number: 2026-10-01 is 20261001. The day is UTC, so it is one seed worldwide. */
+/** Today's seed, the date as a number: 2026-10-01 is 20261001. The day is UTC, so it is one seed worldwide.
+ *
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns Today's seed, the date as a number: 2026-10-01 is 20261001. The day is UTC, so it is one seed worldwide.
+ * @example
+ * ```ts
+ * import { kumimojiDailySeed } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiDailySeed(new Date("2026-10-12T12:00:00Z")));
+ * ```
+ */
 export function kumimojiDailySeed(at) {
     const [year, month, day] = kumimojiDay(at).split("-").map(Number);
-    return year * 10000 + month * 100 + day;
+    return year * 10_000 + month * 100 + day;
 }

package/dist/element-define.d.ts

@@ -1 +1 @@
-export {};
+export * from "./element.ts";

package/dist/element-define.js

@@ -1,13 +1,3 @@
-/**
- * Defines the `<kumimoji-table>` element on the page. Import it for its effect:
- *
- * ```html
- * <script type="module" src="https://cdn.jsdelivr.net/npm/@johnmorrisdotca/kumimoji@1/dist/element-define.js"></script>
- * <kumimoji-table language="english" hand="7"></kumimoji-table>
- * ```
- *
- * A tag already defined is left as it is, and on a server, where there is no page, nothing happens.
- */
-import { KumimojiTable } from "./element.js";
-if (typeof customElements !== "undefined" && customElements.get("kumimoji-table") === undefined)
-    customElements.define("kumimoji-table", KumimojiTable);
+import { defineTable } from "./element.js";
+defineTable();
+export * from "./element.js";

package/dist/element.d.ts

@@ -1,5 +1,5 @@
-import { type KumimojiTableHandle } from "./ui/mount.ts";
 import type { KumimojiSaved } from "./export.ts";
+import { type KumimojiTableHandle, type KumimojiTableOptions } from "./ui/mount.ts";
 declare const ElementBase: typeof HTMLElement;
 /**
  * THE `<kumimoji-table>` ELEMENT: a game of Kumimoji alone in a tag, with no
@@ -12,8 +12,7 @@ declare const ElementBase: typeof HTMLElement;
  * <kumimoji-table language="japanese" level="easy" seed="daily"></kumimoji-table>
  * ```
  *
- * Attributes (each is read again when it changes; a change to any but `lang`
- * deals a new game):
+ * Attributes configure the starting game; display, language and control changes preserve play:
  *  - `language`: the tiles, `english` (default) or `japanese` kana.
  *  - `hand`: the opening hand, 3, 7 (default) or 11.
  *  - `level`: how many tiles are wild, `easy` (most), `medium` (default) or `hard` (none).
@@ -25,11 +24,41 @@ declare const ElementBase: typeof HTMLElement;
  * It fires `kumimoji-change` after every change to the game, with the game as it would
  * be saved as `event.detail.saved`, and `kumimoji-finish` when the last tile is laid and every run
  * is a word, with `event.detail` the deal, the play and the time it took. It has the methods
- * `newGame()` and `setGame()`. A table the rules do not offer (a hand of 5, say) draws nothing.
+ * `newGame()` and `setGame()`. Invalid input shows a status and a plain error event.
+ */
+/**
+ * Native table options, checked alongside builder coverage.
+ * @example
+ * ```ts
+ * import { KUMIMOJI_EMBED_OPTION_KEYS } from "@johnmorrisdotca/kumimoji/element";
+ * console.log(KUMIMOJI_EMBED_OPTION_KEYS.includes("saved"));
+ * ```
+ */
+export declare const KUMIMOJI_EMBED_OPTION_KEYS: string[];
+/**
+ * Full native host options, including saved state, private words and callbacks.
+ * @example
+ * ```ts
+ * import type { KumimojiElementOptions } from "@johnmorrisdotca/kumimoji/element";
+ * const options: KumimojiElementOptions = { keep: false, locale: "ja" };
+ * console.log(options.locale);
+ * ```
+ */
+export type KumimojiElementOptions = KumimojiTableOptions;
+/**
+ * A reflected crossword table with the native table handle and saved-state getter.
+ * @example
+ * ```ts
+ * import { KumimojiTable } from "@johnmorrisdotca/kumimoji/element";
+ * console.log(KumimojiTable.observedAttributes.includes("daily"));
+ * ```
  */
 export declare class KumimojiTable extends ElementBase {
     #private;
     static observedAttributes: string[];
+    /** Native host options. Callback/presentation changes preserve the current game. */
+    get options(): KumimojiElementOptions;
+    set options(value: KumimojiElementOptions);
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(): void;
@@ -41,5 +70,57 @@ export declare class KumimojiTable extends ElementBase {
     newGame(options?: Parameters<KumimojiTableHandle["newGame"]>[0]): Promise<void>;
     /** Put a game on the table: see `KumimojiTableHandle.setGame`. */
     setGame(saved: KumimojiSaved): Promise<void>;
+    /** The `language` attribute, reflected. */
+    get language(): string | null;
+    set language(value: string | number | boolean | null | undefined);
+    /** The `hand` attribute, reflected. */
+    get hand(): string | null;
+    set hand(value: string | number | boolean | null | undefined);
+    /** The `level` attribute, reflected. */
+    get level(): string | null;
+    set level(value: string | number | boolean | null | undefined);
+    /** The `length` attribute, reflected. */
+    get length(): string | null;
+    set length(value: string | number | boolean | null | undefined);
+    /** The `diagonals` attribute, reflected. */
+    get diagonals(): string | null;
+    set diagonals(value: string | number | boolean | null | undefined);
+    /** The `seed` attribute, reflected. */
+    get seed(): string | null;
+    set seed(value: string | number | boolean | null | undefined);
+    /** The `keep` attribute, reflected. */
+    get keep(): string | null;
+    set keep(value: string | number | boolean | null | undefined);
+    /** The `daily` attribute, reflected. */
+    get daily(): string | null;
+    set daily(value: string | number | boolean | null | undefined);
+    /** The `controls` attribute, reflected. */
+    get controls(): string | null;
+    set controls(value: string | number | boolean | null | undefined);
+    /** The `theme` attribute, reflected. */
+    get theme(): string | null;
+    set theme(value: string | number | boolean | null | undefined);
+    /** The `size` attribute, reflected. */
+    get size(): string | null;
+    set size(value: string | number | boolean | null | undefined);
+    /** The `width` attribute, reflected. */
+    get width(): string | null;
+    set width(value: string | number | boolean | null | undefined);
+    /** The `label` attribute, reflected. */
+    get label(): string | null;
+    set label(value: string | number | boolean | null | undefined);
 }
+/**
+ * Defines the table or a subclass under a custom tag. Server-safe and idempotent.
+ * @param tagName - The tag name; kumimoji-table by default.
+ * @param registry - The page registry, or undefined on a server.
+ * @returns Nothing; existing definitions are left alone.
+ * @example
+ * ```ts
+ * import { defineTable } from "@johnmorrisdotca/kumimoji/element";
+ * defineTable();
+ * console.log(typeof defineTable);
+ * ```
+ */
+export declare function defineTable(tagName?: string, registry?: CustomElementRegistry | undefined): void;
 export {};