pi-roundtable-drawing 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -5,6 +5,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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,13 @@ 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 and reversal suffixes |
 
 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.
+These hooks change only presentation, not card selection, model-visible arguments, tool result text, 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.3",
 	"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.3",
 		"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,5 @@
 export type { Card, Deck } from "./cards/deck.ts";
-export type { DrawingOptions } from "./plugin.ts";
+export type { CardPresentation, DrawingOptions } 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,16 @@ 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;
+}
+
 export interface DrawingOptions {
 	/**
 	 * A directory with one subdirectory for each deck, each holding a `deck.json` and the card
@@ -21,6 +36,8 @@ 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;
 }
 
 function readDecks(deckDir: string): Deck[] {
@@ -53,7 +70,9 @@ export function drawing(options: DrawingOptions = {}) {
 					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}]`;