pi-roundtable-drawing 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -5,6 +5,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.7.4] - 2026-10-03
+
+- Add `cardPresentation.result` for the card draw result text and `mapLimits` for longer relationship-map text.
+
+## [0.7.3] - 2026-10-03
+
+- Add `DrawingOptions.cardPresentation` for trusted operator card headings and reversal suffixes.
+
 ## [0.7.2] - 2026-10-02
 
 First release published by the lockstep workflow; no changes to the package.

package/README.md

@@ -82,8 +82,15 @@ export default {
 | `deckDir` | `string` | none | A directory with one subdirectory for each deck; see [the deck directory](#the-deck-directory). Without it the plugin has no `draw_cards` tool. A directory that does not exist, holds no deck, or holds an invalid manifest stops the start with a message that names the deck and what to fix |
 | `random` | `() => number` | `Math.random` | The random source of the map layouts and the card draws, returning a number from 0 up to, not including, 1. A seeded source makes a run reproducible: a new `seededRandom(seed)` given the same calls draws the same pictures. `seededRandom(seed)` is exported for that |
 | `minTier` | `"owner" \| "admin" \| "member"` | `member` | The lowest tier that may use the tools. The operator's `toolTiers` setting still wins |
+| `cardPresentation` | `CardPresentation` | package captions | Trusted operator-local headings, reversal suffixes and result text |
+| `mapLimits` | `{ title?, text? }` | 80 and 60 | Longest relationship-map title, and node id, node label or edge label, in characters, for a host whose callers already draw longer text; the renderer's size limit still applies |
 
 The plugin is named `drawing`.
+`cardPresentation.heading(draw, turn)` returns `{ title, subtitle }`; `draw` holds the selected `deck`, `count`, and optional `question`, and `turn` carries the host-bound speaker/channel.
+`cardPresentation.reversedSuffix` replaces the default `" (reversed)"` on pictured reversed card names.
+`cardPresentation.result({ deck, cards, positions })` replaces the text the model reads back after a draw; `{file}` stands for the attached file's name.
+These hooks change only presentation, not card selection, model-visible arguments, or attachment limits.
+They are trusted configuration callbacks, never guest-supplied code.
 
 ## The tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-drawing",
-	"version": "0.7.2",
+	"version": "0.7.4",
 	"description": "Relationship maps, magic circles, sigils, sacred geometry, and card spreads drawn locally for pi-roundtable",
 	"type": "module",
 	"license": "MIT",
@@ -48,7 +48,7 @@
 	"devDependencies": {
 		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.2",
-		"pi-roundtable": "0.7.2",
+		"pi-roundtable": "0.7.4",
 		"typescript": "7.0.2"
 	}
 }

package/src/cards/spread.ts

@@ -112,6 +112,7 @@ export async function renderSpread(
 	cards: readonly DrawnCard[],
 	positions: readonly SpreadPosition[],
 	heading: { title: string; subtitle: string },
+	reversedSuffix = " (reversed)",
 ): Promise<Uint8Array> {
 	checkSpread(positions, cards.length);
 	ensureFont();
@@ -225,7 +226,7 @@ export async function renderSpread(
 
 		ctx.fillStyle = card.reversed ? PALETTE.accentLight : PALETTE.text;
 		ctx.font = font(width < 150 ? 12 : 15);
-		const name = card.reversed ? `${card.name} (reversed)` : card.name;
+		const name = card.reversed ? `${card.name}${reversedSuffix}` : card.name;
 		ctx.fillText(fitText(ctx, name, width), x + width / 2, y + height + 8);
 	}
 	return new Uint8Array(canvas.toBuffer("image/png"));

package/src/index.ts

@@ -1,5 +1,9 @@
 export type { Card, Deck } from "./cards/deck.ts";
-export type { DrawingOptions } from "./plugin.ts";
+export type {
+	CardPresentation,
+	DrawingOptions,
+	RelationshipMapLimits,
+} from "./plugin.ts";
 export { drawing } from "./plugin.ts";
 export type { Random } from "./random.ts";
 export { seededRandom } from "./random.ts";

package/src/plugin.ts

@@ -1,4 +1,9 @@
-import { definePlugin, PluginError, type Tier } from "pi-roundtable";
+import {
+	definePlugin,
+	PluginError,
+	type Tier,
+	type ToolTurn,
+} from "pi-roundtable";
 import { type Deck, DeckError, loadDecks } from "./cards/deck.ts";
 import type { Random } from "./random.ts";
 import { drawCardsTool } from "./tools/draw-cards-tool.ts";
@@ -10,6 +15,32 @@ import {
 } from "./tools/magic-tools.ts";
 import { relationshipMapTool } from "./tools/relationship-map-tool.ts";
 
+export interface CardPresentation {
+	/** Trusted host presentation; never part of the model's tool arguments. */
+	heading?: (
+		draw: { deck: Deck; count: number; question?: string },
+		turn: ToolTurn,
+	) => { title: string; subtitle: string };
+	/** Appended to reversed card names on the picture; default " (reversed)". */
+	reversedSuffix?: string;
+	/**
+	 * The text the model reads back after a draw; `{file}` stands for the attached file's name.
+	 * Default: the deck id, then one numbered line per card with its position label and id.
+	 */
+	result?: (draw: {
+		deck: Deck;
+		cards: { id: string; name: string; reversed: boolean }[];
+		positions: { row: number; col: number; label?: string | undefined }[];
+	}) => string;
+}
+
+/** Longest map text a host accepts, in characters; the defaults suit a picture that stays readable. */
+export interface RelationshipMapLimits {
+	title?: number;
+	/** Node ids, node labels and edge labels. */
+	text?: number;
+}
+
 export interface DrawingOptions {
 	/**
 	 * A directory with one subdirectory for each deck, each holding a `deck.json` and the card
@@ -21,6 +52,10 @@ export interface DrawingOptions {
 	random?: Random;
 	/** The lowest tier that may use the tools; default `member`. */
 	minTier?: Tier;
+	/** Operator-local captions and reversal wording; default package presentation. */
+	cardPresentation?: CardPresentation;
+	/** Longer map text than the defaults, for a host whose callers already draw longer labels. */
+	mapLimits?: RelationshipMapLimits;
 }
 
 function readDecks(deckDir: string): Deck[] {
@@ -49,11 +84,13 @@ export function drawing(options: DrawingOptions = {}) {
 			};
 			return {
 				tools: [
-					relationshipMapTool(env, random),
+					relationshipMapTool(env, random, options.mapLimits),
 					magicCircleTool(env),
 					sigilTool(env),
 					sacredGeometryTool(env),
-					...(decks.length > 0 ? [drawCardsTool(decks, env, random)] : []),
+					...(decks.length > 0
+						? [drawCardsTool(decks, env, random, options.cardPresentation)]
+						: []),
 				],
 			};
 		},

package/src/tools/draw-cards-tool.ts

@@ -10,6 +10,7 @@ import {
 	type SpreadPosition,
 } from "../cards/spread.ts";
 import { DrawingError } from "../errors.ts";
+import type { CardPresentation } from "../plugin.ts";
 import type { Random } from "../random.ts";
 import {
 	type ImageToolEnv,
@@ -32,6 +33,7 @@ export function drawCardsTool(
 	decks: readonly Deck[],
 	env: ImageToolEnv,
 	random: Random,
+	presentation: CardPresentation = {},
 ) {
 	const [first, ...rest] = decks;
 	if (!first) throw new DrawingError("draw_cards needs at least one deck.");
@@ -81,7 +83,7 @@ export function drawCardsTool(
 					Type.String({ description: "The question, shown on the picture." }),
 				),
 			}),
-			draw: async (args) => {
+			draw: async (args, turn) => {
 				const deck = decks.find((candidate) => candidate.id === args.deck);
 				if (!deck)
 					throw new DrawingError(
@@ -99,12 +101,22 @@ export function drawCardsTool(
 					allowReversed: args.allow_reversed,
 					random,
 				});
-				const image = await renderSpread(deck, cards, positions, {
+				const heading = presentation.heading?.(
+					{ deck, count: cards.length, question: args.question },
+					turn,
+				) ?? {
 					title: deck.name,
 					subtitle:
 						args.question ??
 						`${cards.length} card${cards.length === 1 ? "" : "s"}`,
-				});
+				};
+				const image = await renderSpread(
+					deck,
+					cards,
+					positions,
+					heading,
+					presentation.reversedSuffix,
+				);
 				const lines = cards.map((card, i) => {
 					const label = positions[i]?.label ? `${positions[i]?.label}: ` : "";
 					return `${i + 1}. ${label}${card.name}${card.reversed ? " (reversed)" : ""} [id: ${card.id}]`;
@@ -112,7 +124,9 @@ export function drawCardsTool(
 				return {
 					stem: "cards",
 					image,
-					text: `Drew ${cards.length} from ${deck.id}; the spread picture is attached to your reply as {file}.\n${lines.join("\n")}`,
+					text:
+						presentation.result?.({ deck, cards, positions }) ??
+						`Drew ${cards.length} from ${deck.id}; the spread picture is attached to your reply as {file}.\n${lines.join("\n")}`,
 				};
 			},
 		},

package/src/tools/relationship-map-tool.ts

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import type { RelationshipMapLimits } from "../plugin.ts";
 import type { Random } from "../random.ts";
 import {
 	EDGE_TYPES,
@@ -16,25 +17,31 @@ import {
 	strictObject,
 } from "./image-tool.ts";
 
-export function relationshipMapTool(env: ImageToolEnv, random: Random) {
+export function relationshipMapTool(
+	env: ImageToolEnv,
+	random: Random,
+	limits: RelationshipMapLimits = {},
+) {
+	const maxTitle = limits.title ?? MAX_TITLE;
+	const maxText = limits.text ?? MAX_TEXT;
 	return imageTool(
 		{
 			name: "relationship_map",
 			description:
 				"Draw a hand-drawn relationship map of characters (pc, npc) and factions, with typed relationships between them, and attach it to your reply as an image.",
 			parameters: strictObject({
-				title: Type.Optional(Type.String({ maxLength: MAX_TITLE })),
+				title: Type.Optional(Type.String({ maxLength: maxTitle })),
 				nodes: Type.Array(
 					strictObject({
 						id: Type.String({
 							minLength: 1,
-							maxLength: MAX_TEXT,
+							maxLength: maxText,
 							description: "Character or faction name.",
 						}),
 						type: literals(NODE_TYPES),
 						label: Type.Optional(
 							Type.String({
-								maxLength: MAX_TEXT,
+								maxLength: maxText,
 								description: "A sub-label such as a role.",
 							}),
 						),
@@ -49,7 +56,7 @@ export function relationshipMapTool(env: ImageToolEnv, random: Random) {
 							EDGE_TYPES,
 							"romantic: arrow; entanglement: dashed arrow; bond: plain line; faction: dashed arrow; hostile: arrows both ways.",
 						),
-						label: Type.Optional(Type.String({ maxLength: MAX_TEXT })),
+						label: Type.Optional(Type.String({ maxLength: maxText })),
 					}),
 					{ maxItems: MAX_EDGES },
 				),