@jjlmoya/utils-tabletop 1.25.0 → 1.27.0

package/src/tool/encounter-difficulty-calculator/logic.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { calculateEncounter } from './logic';
+
+describe('calculateEncounter', () => {
+  it('calculates a medium encounter for a level five party', () => {
+    const result = calculateEncounter({ partyLevel: 5, partySize: 4, monsterCr: 3, monsterCount: 2 });
+    expect(result.monsterXp).toBe(700);
+    expect(result.adjustedXp).toBe(2100);
+    expect(result.difficulty).toBe('medium');
+  });
+
+  it('applies the multiple monster multiplier', () => {
+    const result = calculateEncounter({ partyLevel: 3, partySize: 4, monsterCr: 1, monsterCount: 4 });
+    expect(result.baseXp).toBe(800);
+    expect(result.multiplier).toBe(2);
+    expect(result.adjustedXp).toBe(1600);
+    expect(result.difficulty).toBe('deadly');
+  });
+
+  it('raises the multiplier for a small party', () => {
+    const result = calculateEncounter({ partyLevel: 5, partySize: 2, monsterCr: 2, monsterCount: 2 });
+    expect(result.multiplier).toBe(2);
+    expect(result.warnings).toContain('partyAdjustment');
+  });
+
+  it('lowers the multiplier for a large party', () => {
+    const result = calculateEncounter({ partyLevel: 5, partySize: 6, monsterCr: 2, monsterCount: 6 });
+    expect(result.multiplier).toBe(1.5);
+    expect(result.warnings).toContain('partyAdjustment');
+  });
+
+  it('clamps unsafe inputs to the supported range', () => {
+    const result = calculateEncounter({ partyLevel: 99, partySize: 99, monsterCr: 99, monsterCount: 99 });
+    expect(result.settings).toEqual({ partyLevel: 20, partySize: 8, monsterCr: 30, monsterCount: 15 });
+    expect(result.difficulty).toBe('deadly');
+  });
+});

package/src/tool/encounter-difficulty-calculator/logic.ts

@@ -0,0 +1,174 @@
+export type EncounterDifficulty = 'belowEasy' | 'easy' | 'medium' | 'hard' | 'deadly';
+
+export interface EncounterSettings {
+  partyLevel: number;
+  partySize: number;
+  monsterCr: number;
+  monsterCount: number;
+}
+
+export interface EncounterThresholds {
+  easy: number;
+  medium: number;
+  hard: number;
+  deadly: number;
+}
+
+export interface EncounterResult {
+  settings: EncounterSettings;
+  monsterXp: number;
+  baseXp: number;
+  multiplier: number;
+  adjustedXp: number;
+  thresholds: EncounterThresholds;
+  difficulty: EncounterDifficulty;
+  crLabel: string;
+  warnings: string[];
+}
+
+interface CrEntry {
+  value: number;
+  label: string;
+  xp: number;
+}
+
+const CR_ENTRIES: CrEntry[] = [
+  { value: 0, label: '0', xp: 10 },
+  { value: 0.125, label: '1/8', xp: 25 },
+  { value: 0.25, label: '1/4', xp: 50 },
+  { value: 0.5, label: '1/2', xp: 100 },
+  { value: 1, label: '1', xp: 200 },
+  { value: 2, label: '2', xp: 450 },
+  { value: 3, label: '3', xp: 700 },
+  { value: 4, label: '4', xp: 1100 },
+  { value: 5, label: '5', xp: 1800 },
+  { value: 6, label: '6', xp: 2300 },
+  { value: 7, label: '7', xp: 2900 },
+  { value: 8, label: '8', xp: 3900 },
+  { value: 9, label: '9', xp: 5000 },
+  { value: 10, label: '10', xp: 5900 },
+  { value: 11, label: '11', xp: 7200 },
+  { value: 12, label: '12', xp: 8400 },
+  { value: 13, label: '13', xp: 10000 },
+  { value: 14, label: '14', xp: 11500 },
+  { value: 15, label: '15', xp: 13000 },
+  { value: 16, label: '16', xp: 15000 },
+  { value: 17, label: '17', xp: 18000 },
+  { value: 18, label: '18', xp: 20000 },
+  { value: 19, label: '19', xp: 22000 },
+  { value: 20, label: '20', xp: 25000 },
+  { value: 21, label: '21', xp: 33000 },
+  { value: 22, label: '22', xp: 41000 },
+  { value: 23, label: '23', xp: 50000 },
+  { value: 24, label: '24', xp: 62000 },
+  { value: 25, label: '25', xp: 75000 },
+  { value: 26, label: '26', xp: 90000 },
+  { value: 27, label: '27', xp: 105000 },
+  { value: 28, label: '28', xp: 120000 },
+  { value: 29, label: '29', xp: 135000 },
+  { value: 30, label: '30', xp: 155000 },
+];
+
+const THRESHOLDS = [
+  [25, 50, 75, 100], [50, 100, 150, 200], [75, 150, 225, 400],
+  [125, 250, 375, 500], [250, 500, 750, 1100], [300, 600, 900, 1400],
+  [350, 750, 1100, 1700], [450, 900, 1400, 2100], [550, 1100, 1600, 2400],
+  [600, 1200, 1900, 2800], [800, 1600, 2400, 3600], [1000, 2000, 3000, 4500],
+  [1100, 2200, 3400, 5100], [1250, 2500, 3800, 5700], [1400, 2800, 4300, 6400],
+  [1600, 3200, 4800, 7200], [2000, 3900, 5900, 8800], [2100, 4200, 6300, 9500],
+  [2400, 4900, 7300, 10900], [2800, 5700, 8500, 12700],
+] as const;
+
+const MULTIPLIERS = [1, 1.5, 2, 2.5, 3, 4];
+
+export const DEFAULT_SETTINGS: EncounterSettings = {
+  partyLevel: 5,
+  partySize: 4,
+  monsterCr: 2,
+  monsterCount: 2,
+};
+
+export const CR_OPTIONS = CR_ENTRIES;
+export const QUICK_CR_VALUES = [0, 0.125, 0.25, 0.5, 1, 2, 3, 4, 5, 8, 10, 15];
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function findCrEntry(cr: number): CrEntry {
+  return CR_ENTRIES.reduce((closest, entry) => (
+    Math.abs(entry.value - cr) < Math.abs(closest.value - cr) ? entry : closest
+  ));
+}
+
+function getBaseMultiplier(monsterCount: number): number {
+  if (monsterCount === 1) return 1;
+  if (monsterCount === 2) return 1.5;
+  if (monsterCount <= 6) return 2;
+  if (monsterCount <= 10) return 2.5;
+  if (monsterCount <= 14) return 3;
+  return 4;
+}
+
+function getPartyAdjustment(partySize: number): number {
+  if (partySize < 3) return 1;
+  if (partySize > 5) return -1;
+  return 0;
+}
+
+function getMultiplier(monsterCount: number, partySize: number): number {
+  const baseIndex = MULTIPLIERS.indexOf(getBaseMultiplier(monsterCount));
+  const partyAdjustment = getPartyAdjustment(partySize);
+  return MULTIPLIERS[clamp(baseIndex + partyAdjustment, 0, MULTIPLIERS.length - 1)];
+}
+
+function getThresholds(partyLevel: number, partySize: number): EncounterThresholds {
+  const row = THRESHOLDS[clamp(partyLevel, 1, 20) - 1];
+  return {
+    easy: row[0] * partySize,
+    medium: row[1] * partySize,
+    hard: row[2] * partySize,
+    deadly: row[3] * partySize,
+  };
+}
+
+function getDifficulty(adjustedXp: number, thresholds: EncounterThresholds): EncounterDifficulty {
+  if (adjustedXp < thresholds.easy) return 'belowEasy';
+  if (adjustedXp < thresholds.medium) return 'easy';
+  if (adjustedXp < thresholds.hard) return 'medium';
+  if (adjustedXp < thresholds.deadly) return 'hard';
+  return 'deadly';
+}
+
+function getWarnings(settings: EncounterSettings): string[] {
+  const warnings: string[] = [];
+  if (settings.partySize < 3 || settings.partySize > 5) warnings.push('partyAdjustment');
+  if (settings.monsterCr > settings.partyLevel) warnings.push('highCr');
+  if (settings.monsterCount >= 11) warnings.push('manyMonsters');
+  return warnings;
+}
+
+export function calculateEncounter(rawSettings: EncounterSettings): EncounterResult {
+  const settings: EncounterSettings = {
+    partyLevel: clamp(Math.round(rawSettings.partyLevel), 1, 20),
+    partySize: clamp(Math.round(rawSettings.partySize), 1, 8),
+    monsterCr: findCrEntry(rawSettings.monsterCr).value,
+    monsterCount: clamp(Math.round(rawSettings.monsterCount), 1, 15),
+  };
+  const crEntry = findCrEntry(settings.monsterCr);
+  const thresholds = getThresholds(settings.partyLevel, settings.partySize);
+  const baseXp = crEntry.xp * settings.monsterCount;
+  const multiplier = getMultiplier(settings.monsterCount, settings.partySize);
+  const adjustedXp = Math.round(baseXp * multiplier);
+  return {
+    settings,
+    monsterXp: crEntry.xp,
+    baseXp,
+    multiplier,
+    adjustedXp,
+    thresholds,
+    difficulty: getDifficulty(adjustedXp, thresholds),
+    crLabel: crEntry.label,
+    warnings: getWarnings(settings),
+  };
+}

package/src/tool/encounter-difficulty-calculator/seo.astro

@@ -0,0 +1,16 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { encounterDifficultyCalculator } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props as Props;
+const loader = encounterDifficultyCalculator.i18n[locale] || encounterDifficultyCalculator.i18n.en;
+const content = await loader?.();
+if (!content) return null;
+---
+
+{content.seo?.length > 0 && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/encounter-difficulty-calculator/storage.ts

@@ -0,0 +1,26 @@
+import type { EncounterSettings } from './logic';
+
+const STORAGE_KEY = 'jjlmoya-encounter-difficulty-settings-v1';
+
+function isSettings(value: unknown): value is EncounterSettings {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Record<string, unknown>;
+  return ['partyLevel', 'partySize', 'monsterCr', 'monsterCount'].every((key) => typeof candidate[key] === 'number');
+}
+
+export function readEncounterSettings(): EncounterSettings | null {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (!stored) return null;
+    const value: unknown = JSON.parse(stored);
+    return isSettings(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeEncounterSettings(settings: EncounterSettings): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(settings));
+  } catch {}
+}

package/src/tool/encounter-difficulty-calculator/ui.ts

@@ -0,0 +1,45 @@
+export interface EncounterDifficultyUI {
+  intro: string;
+  partySection: string;
+  partyLevel: string;
+  partyLevelHint: string;
+  partySize: string;
+  partySizeHint: string;
+  threatSection: string;
+  monsterCr: string;
+  monsterCrHint: string;
+  moreCr: string;
+  lessCr: string;
+  monsterCount: string;
+  monsterCountHint: string;
+  presets: string;
+  presetClassic: string;
+  presetBoss: string;
+  presetSwarm: string;
+  resultSection: string;
+  belowEasyHint: string;
+  easyHint: string;
+  mediumHint: string;
+  hardHint: string;
+  deadlyHint: string;
+  adjustedXp: string;
+  baseXp: string;
+  multiplier: string;
+  partyThreshold: string;
+  belowEasy: string;
+  easy: string;
+  medium: string;
+  hard: string;
+  deadly: string;
+  warning: string;
+  partyAdjustment: string;
+  highCr: string;
+  manyMonsters: string;
+  rulesNote: string;
+  rulesLinkLabel: string;
+  reset: string;
+  xpUnit: string;
+  sceneLabel: string;
+  partyMarker: string;
+  threatMarker: string;
+}

package/src/tool/token-stamp-studio/bibliography.astro

@@ -0,0 +1,16 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { tokenStampStudio } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props as Props;
+const loader = tokenStampStudio.i18n[locale] || tokenStampStudio.i18n.en;
+const content = await loader?.();
+if (!content) return null;
+---
+
+{content && <SharedBibliography links={content.bibliography} />}

package/src/tool/token-stamp-studio/bibliography.ts

@@ -0,0 +1,12 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  {
+    name: 'Foundry Virtual Tabletop, Tokens',
+    url: 'https://foundryvtt.com/article/tokens/',
+  },
+  {
+    name: 'Foundry Virtual Tabletop, Actors',
+    url: 'https://foundryvtt.com/article/actors/',
+  },
+];

package/src/tool/token-stamp-studio/component.astro

@@ -0,0 +1,91 @@
+---
+import './token-stamp-studio.css';
+import type { TokenStampUI } from './ui';
+
+const { ui } = Astro.props as { ui: TokenStampUI };
+---
+
+<div class="token-stamp-studio" data-token-stamp-studio data-ui={JSON.stringify(ui)}>
+  <div class="foundry-shell">
+  <section class="marker-library marker-library-header" aria-label={ui.savedMarkers}>
+    <div class="marker-library-grid" data-marker-library></div>
+  </section>
+    <div class="foundry-layout">
+    <section class="foundry-stage-panel" aria-label={ui.stageLabel}>
+      <label class="marker-name-field marker-name-stage"><input data-marker-name type="text" maxlength="48" placeholder={ui.markerNamePlaceholder} aria-label={ui.markerName} /></label>
+      <div class="token-stage" data-drop-zone>
+        <canvas data-token-canvas aria-label={ui.stageLabel}></canvas>
+        <p class="stage-caption"><span>{ui.positionHint}</span><span data-current-image>{ui.noImage}</span></p>
+      </div>
+      <div class="stage-actions">
+        <label class="button button-primary" for="token-image-input">{ui.chooseImage}</label>
+        <input id="token-image-input" data-image-input type="file" accept="image/png,image/jpeg,image/webp,image/gif" hidden />
+        <button class="button button-quiet" type="button" data-clear-image>{ui.clearImage}</button>
+        <button class="button button-quiet" type="button" data-copy>{ui.copy}</button>
+        <button class="button button-primary" type="button" data-download>{ui.download}</button>
+      </div>
+      <p class="export-hint">{ui.exportHint}</p>
+    </section>
+
+    <aside class="foundry-inspector" aria-label={ui.tokenDetails}>
+      <section class="inspector-block inspector-frames">
+        <div class="block-heading"><div><p class="eyebrow">01</p><h3>{ui.frameLegend}</h3></div><button class="micro-action" type="button" data-random-frame>{ui.randomFrame}</button></div>
+        <p class="block-hint">{ui.frameHint}</p>
+        <div class="frame-gallery" data-frame-gallery></div>
+      </section>
+
+      <section class="inspector-block">
+        <div class="block-heading"><div><p class="eyebrow">02</p><h3>{ui.surfaceLegend}</h3></div><button class="micro-action" type="button" data-random-colors>{ui.randomColors}</button></div>
+        <div class="color-grid">
+          <label class="color-control"><span>{ui.backgroundLabel}</span><input data-color="background" type="color" value="#1d2430" /></label>
+          <label class="color-control"><span>{ui.borderLabel}</span><input data-color="border" type="color" value="#d89555" /></label>
+          <label class="color-control"><span>{ui.textLabel}</span><input data-color="text" type="color" value="#fff4d6" /></label>
+          <label class="color-control"><span>{ui.overlayLabel}</span><input data-color="overlay" type="color" value="#e05b4f" /></label>
+        </div>
+        <label class="range-control"><span>{ui.borderWidthLabel}<output data-border-width-output>16</output></span><input data-border-width type="range" min="4" max="34" step="1" value="16" /></label>
+        <label class="range-control"><span>{ui.opacityLabel}<output data-border-opacity-output>100%</output></span><input data-border-opacity type="range" min="0.2" max="1" step="0.05" value="1" /></label>
+        <label class="range-control"><span>{ui.overlayOpacityLabel}<output data-overlay-opacity-output>0%</output></span><input data-overlay-opacity type="range" min="0" max="0.8" step="0.05" value="0" /></label>
+      </section>
+
+      <section class="inspector-block">
+        <div class="block-heading"><div><p class="eyebrow">03</p><h3>{ui.imageLegend}</h3></div></div>
+        <label class="range-control"><span>{ui.imageZoomLabel}<output data-image-zoom-output>100%</output></span><input data-image-zoom type="range" min="0.7" max="1.8" step="0.05" value="1" /></label>
+        <label class="range-control"><span>{ui.scaleLabel}<output data-scale-output>100%</output></span><input data-scale type="range" min="0.75" max="1.5" step="0.05" value="1" /></label>
+      </section>
+
+      <section class="inspector-block">
+        <div class="block-heading"><div><p class="eyebrow">04</p><h3>{ui.textLegend}</h3></div></div>
+        <p class="block-hint" data-text-hint>{ui.textHint}</p>
+        <div class="text-layer-list" data-text-layers></div>
+        <div class="text-editor">
+          <input data-text-input type="text" maxlength="24" placeholder={ui.textPlaceholder} aria-label={ui.textPlaceholder} />
+          <div class="editor-row"><label class="range-control"><span>{ui.textSizeLabel}<output data-text-size-output>54</output></span><input data-text-size type="range" min="22" max="86" step="1" value="54" /></label></div>
+          <div class="align-actions" aria-label={ui.alignmentLabel}>
+            <button type="button" data-align="left" aria-label={ui.alignLeft} title={ui.alignLeft}>↤</button><button type="button" data-align="center" aria-label={ui.alignCenter} title={ui.alignCenter}>↔</button><button type="button" data-align="right" aria-label={ui.alignRight} title={ui.alignRight}>↦</button>
+          </div>
+          <div class="editor-actions"><button class="button button-quiet" type="button" data-add-text>{ui.addText}</button><button class="button button-danger" type="button" data-remove-text>{ui.removeText}</button></div>
+        </div>
+      </section>
+
+    </aside>
+    </div>
+
+  <details class="batch-advanced">
+    <summary>{ui.batchLabel}</summary>
+    <section class="batch-dock" aria-labelledby="batch-title">
+      <div><h3 id="batch-title">{ui.batchHint}</h3><p data-batch-status>{ui.batchHint}</p></div>
+      <div class="batch-actions"><label class="button button-quiet" for="token-batch-input">{ui.chooseBatch}</label><input id="token-batch-input" data-batch-input type="file" accept="image/png,image/jpeg,image/webp,image/gif" multiple hidden /><button class="button button-primary" type="button" data-batch-download disabled>{ui.downloadBatch}</button></div>
+    </section>
+  </details>
+  </div>
+</div>
+
+<script>
+  import { mountTokenStampStudio } from './controller';
+
+  const root = document.querySelector<HTMLElement>('[data-token-stamp-studio]');
+  if (root) {
+    const ui = JSON.parse(root.dataset.ui ?? '{}');
+    void mountTokenStampStudio(root, ui);
+  }
+</script>

package/src/tool/token-stamp-studio/controller.ts

@@ -0,0 +1,179 @@
+import { createTextLayer, FRAME_PRESETS, getRandomPalette, hitTestText, updateTextLayer, clamp } from './logic';
+import { pointerToCanvas } from './dom-views';
+import { attachBatchEvents, attachFileEvents, attachWorkspaceEvents } from './workspace';
+import { StudioStore } from './store';
+import type { TokenStampUI } from './ui';
+import type { TextAlign, TokenStampState } from './types';
+
+export interface StudioElements {
+  root: HTMLElement;
+  canvas: HTMLCanvasElement;
+  frames: HTMLElement;
+  textLayers: HTMLElement;
+  imageInput: HTMLInputElement;
+  batchInput: HTMLInputElement;
+  textInput: HTMLInputElement;
+  textSize: HTMLInputElement;
+  imageZoom: HTMLInputElement;
+  scale: HTMLInputElement;
+  borderWidth: HTMLInputElement;
+  borderOpacity: HTMLInputElement;
+  overlayOpacity: HTMLInputElement;
+  currentImage: HTMLElement;
+  batchStatus: HTMLElement;
+  library: HTMLElement;
+  markerName: HTMLInputElement;
+  copy: HTMLButtonElement;
+  download: HTMLButtonElement;
+  batchDownload: HTMLButtonElement;
+}
+
+function getElement<T extends Element>(root: HTMLElement, selector: string): T {
+  const element = root.querySelector<T>(selector);
+  if (!element) throw new Error(`Token stamp studio element missing: ${selector}`);
+  return element;
+}
+
+function getElements(root: HTMLElement): StudioElements {
+  return {
+    root,
+    canvas: getElement(root, '[data-token-canvas]'),
+    frames: getElement(root, '[data-frame-gallery]'),
+    textLayers: getElement(root, '[data-text-layers]'),
+    imageInput: getElement(root, '[data-image-input]'),
+    batchInput: getElement(root, '[data-batch-input]'),
+    textInput: getElement(root, '[data-text-input]'),
+    textSize: getElement(root, '[data-text-size]'),
+    imageZoom: getElement(root, '[data-image-zoom]'),
+    scale: getElement(root, '[data-scale]'),
+    borderWidth: getElement(root, '[data-border-width]'),
+    borderOpacity: getElement(root, '[data-border-opacity]'),
+    overlayOpacity: getElement(root, '[data-overlay-opacity]'),
+    currentImage: getElement(root, '[data-current-image]'),
+    batchStatus: getElement(root, '[data-batch-status]'),
+    library: getElement(root, '[data-marker-library]'),
+    markerName: getElement<HTMLInputElement>(root, '[data-marker-name]'),
+    copy: getElement<HTMLButtonElement>(root, '[data-copy]'),
+    download: getElement(root, '[data-download]'),
+    batchDownload: getElement(root, '[data-batch-download]'),
+  };
+}
+
+function getColor(root: HTMLElement, name: string): HTMLInputElement {
+  return getElement<HTMLInputElement>(root, `[data-color="${name}"]`);
+}
+
+function attachFrameEvents(elements: StudioElements, getState: () => TokenStampState, setState: (state: TokenStampState) => void): void {
+  elements.frames.addEventListener('click', (event) => {
+    const target = event.target as HTMLElement;
+    const button = target.closest<HTMLButtonElement>('[data-frame-id]');
+    if (button?.dataset.frameId) setState({ ...getState(), frameId: button.dataset.frameId });
+  });
+}
+
+function attachColorEvents(elements: StudioElements, getState: () => TokenStampState, setState: (state: TokenStampState) => void): void {
+  const colors: Array<[string, keyof TokenStampState]> = [['background', 'background'], ['border', 'border'], ['text', 'textColor'], ['overlay', 'overlay']];
+  colors.forEach(([name, key]) => getColor(elements.root, name).addEventListener('input', (event) => {
+    setState({ ...getState(), [key]: (event.target as HTMLInputElement).value } as TokenStampState);
+  }));
+}
+
+function attachRangeEvents(elements: StudioElements, getState: () => TokenStampState, setState: (state: TokenStampState) => void): void {
+  const ranges: Array<[HTMLInputElement, keyof TokenStampState]> = [
+    [elements.imageZoom, 'imageZoom'], [elements.scale, 'scale'], [elements.borderWidth, 'borderWidth'], [elements.borderOpacity, 'borderOpacity'], [elements.overlayOpacity, 'overlayOpacity'],
+  ];
+  ranges.forEach(([input, key]) => input.addEventListener('input', (event) => setState({ ...getState(), [key]: Number((event.target as HTMLInputElement).value) } as TokenStampState)));
+}
+
+function updateDraftText(value: string, getState: () => TokenStampState, setState: (state: TokenStampState) => void): void {
+  const current = getState();
+  if (!current.selectedTextId && value.trim()) {
+    const text = { ...createTextLayer(current.texts.length + 1), text: value };
+    setState({ ...current, texts: [...current.texts, text], selectedTextId: text.id });
+    return;
+  }
+  setState({ ...current, texts: updateTextLayer(current.texts, current.selectedTextId, { text: value }) });
+}
+
+function attachTextEvents(elements: StudioElements, getState: () => TokenStampState, setState: (state: TokenStampState) => void, ui: TokenStampUI): void {
+  elements.textLayers.addEventListener('click', (event) => {
+    const button = (event.target as HTMLElement).closest<HTMLButtonElement>('[data-text-id]');
+    if (button?.dataset.textId) setState({ ...getState(), selectedTextId: button.dataset.textId });
+  });
+  elements.textInput.addEventListener('input', (event) => updateDraftText((event.target as HTMLInputElement).value, getState, setState));
+  elements.textSize.addEventListener('input', (event) => setState({ ...getState(), texts: updateTextLayer(getState().texts, getState().selectedTextId, { size: Number((event.target as HTMLInputElement).value) }) }));
+  elements.root.querySelectorAll<HTMLButtonElement>('[data-align]').forEach((button) => button.addEventListener('click', () => {
+    const align = button.dataset.align as TextAlign;
+    setState({ ...getState(), texts: updateTextLayer(getState().texts, getState().selectedTextId, { align }) });
+  }));
+  getElement<HTMLButtonElement>(elements.root, '[data-add-text]').addEventListener('click', () => {
+    const text = createTextLayer(getState().texts.length + 1);
+    setState({ ...getState(), texts: [...getState().texts, text], selectedTextId: text.id });
+  });
+  getElement<HTMLButtonElement>(elements.root, '[data-remove-text]').addEventListener('click', () => {
+    const current = getState();
+    const texts = current.texts.filter((text) => text.id !== current.selectedTextId);
+    setState({ ...current, texts, selectedTextId: texts[0]?.id ?? null });
+  });
+  getElement<HTMLElement>(elements.root, '[data-text-hint]').textContent = ui.textHint;
+}
+
+function attachCanvasEvents(elements: StudioElements, getState: () => TokenStampState, setState: (state: TokenStampState) => void): void {
+  let drag: { mode: 'image' | 'text'; start: { x: number; y: number }; imageX: number; imageY: number; textX: number; textY: number } | null = null;
+  elements.canvas.addEventListener('pointerdown', (event) => {
+    const point = pointerToCanvas(elements.canvas, event);
+    const state = getState();
+    const text = state.texts.find((item) => hitTestText(item, point));
+    if (text) setState({ ...state, selectedTextId: text.id });
+    drag = { mode: text ? 'text' : 'image', start: point, imageX: state.imageX, imageY: state.imageY, textX: text?.x ?? 0.5, textY: text?.y ?? 0.8 };
+    elements.canvas.setPointerCapture(event.pointerId);
+  });
+  elements.canvas.addEventListener('pointermove', (event) => {
+    if (!drag) return;
+    const point = pointerToCanvas(elements.canvas, event);
+    const state = getState();
+    const delta = { x: point.x - drag.start.x, y: point.y - drag.start.y };
+    if (drag.mode === 'image') setState({ ...state, imageX: clamp(drag.imageX + delta.x, -0.5, 0.5), imageY: clamp(drag.imageY + delta.y, -0.5, 0.5) });
+    else setState({ ...state, texts: updateTextLayer(state.texts, state.selectedTextId, { x: clamp(drag.textX + delta.x, 0.12, 0.88), y: clamp(drag.textY + delta.y, 0.12, 0.9) }) });
+  });
+  elements.canvas.addEventListener('pointerup', () => { drag = null; });
+  elements.canvas.addEventListener('pointercancel', () => { drag = null; });
+  elements.canvas.addEventListener('wheel', (event) => {
+    event.preventDefault();
+    const nextZoom = clamp(getState().imageZoom - event.deltaY * 0.001, 0.7, 1.8);
+    setState({ ...getState(), imageZoom: nextZoom });
+  }, { passive: false });
+}
+
+function attachStudioInteractions(elements: StudioElements, ui: TokenStampUI, store: StudioStore): void {
+  attachFrameEvents(elements, store.getState, store.setState);
+  attachRandomEvents(elements, store.getState, store.setState);
+  attachColorEvents(elements, store.getState, store.setState);
+  attachRangeEvents(elements, store.getState, store.setState);
+  attachTextEvents(elements, store.getState, store.setState, ui);
+  attachCanvasEvents(elements, store.getState, store.setState);
+  const context = { getState: store.getState, setState: store.setState, ui, getMarkers: store.getMarkers, getImage: store.getImage, selectMarker: store.selectMarker, addMarker: store.addMarker, removeMarker: store.removeMarker, setImage: store.setImage };
+  attachWorkspaceEvents(elements, context);
+  attachFileEvents(elements, context);
+  attachBatchEvents(elements, context);
+}
+
+export async function mountTokenStampStudio(root: HTMLElement, ui: TokenStampUI): Promise<void> {
+  const elements = getElements(root);
+  const store = new StudioStore(elements, ui);
+  await store.restore();
+  store.render();
+  attachStudioInteractions(elements, ui, store);
+}
+
+function attachRandomEvents(elements: StudioElements, getState: () => TokenStampState, setState: (state: TokenStampState) => void): void {
+  getElement<HTMLButtonElement>(elements.root, '[data-random-frame]').addEventListener('click', () => {
+    const available = FRAME_PRESETS.filter((frame) => frame.id !== getState().frameId);
+    const frame = available[Math.floor(Math.random() * available.length)] ?? FRAME_PRESETS[0]!;
+    setState({ ...getState(), frameId: frame.id });
+  });
+  getElement<HTMLButtonElement>(elements.root, '[data-random-colors]').addEventListener('click', () => {
+    const palette = getRandomPalette();
+    setState({ ...getState(), ...palette, overlayOpacity: 0.18 });
+  });
+}