@jjlmoya/utils-pets 1.20.0 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-pets",
-    "version": "1.20.0",
+    "version": "1.22.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -4,10 +4,11 @@ import { petRation } from '../tool/petRation/entry';
 import { petGestation } from '../tool/petGestation/entry';
 import { petToxicity } from '../tool/petToxicity/entry';
 import { petWaterIntake } from '../tool/petWaterIntake/entry';
+import { petCarrierCrateSizePlanner } from '../tool/petCarrierCrateSizePlanner/entry';
 
 export const petsCategory: PetCategoryEntry = {
   icon: 'mdi:paw',
-  tools: [petAge, petRation, petGestation, petToxicity, petWaterIntake],
+  tools: [petAge, petRation, petGestation, petToxicity, petWaterIntake, petCarrierCrateSizePlanner],
   i18n: {
     en: () => import('./i18n/en').then((m) => m.content),
     es: () => import('./i18n/es').then((m) => m.content),

package/src/entries.ts

@@ -6,10 +6,13 @@ export { petToxicity } from './tool/petToxicity/entry';
 export type { PetToxicityUI, PetToxicityLocaleContent } from './tool/petToxicity/entry';
 export { petWaterIntake } from './tool/petWaterIntake/entry';
 export type { PetWaterIntakeUI, PetWaterIntakeLocaleContent } from './tool/petWaterIntake/entry';
+export { petCarrierCrateSizePlanner } from './tool/petCarrierCrateSizePlanner/entry';
+export type { PetCarrierCrateSizePlannerUI, PetCarrierCrateSizePlannerLocaleContent } from './tool/petCarrierCrateSizePlanner/entry';
 export { petsCategory } from './category';
 import { petAge } from './tool/petAge/entry';
 import { petRation } from './tool/petRation/entry';
 import { petGestation } from './tool/petGestation/entry';
 import { petToxicity } from './tool/petToxicity/entry';
 import { petWaterIntake } from './tool/petWaterIntake/entry';
-export const ALL_ENTRIES = [petAge, petRation, petGestation, petToxicity, petWaterIntake];
+import { petCarrierCrateSizePlanner } from './tool/petCarrierCrateSizePlanner/entry';
+export const ALL_ENTRIES = [petAge, petRation, petGestation, petToxicity, petWaterIntake, petCarrierCrateSizePlanner];

package/src/index.ts

@@ -1,6 +1,7 @@
 export { petAge, PET_AGE_TOOL } from './tool/petAge';
 export { petRation, PET_RATION_TOOL } from './tool/petRation';
 export { petGestation, PET_GESTATION_TOOL } from './tool/petGestation';
+export { petCarrierCrateSizePlanner, PET_CARRIER_CRATE_SIZE_PLANNER_TOOL } from './tool/petCarrierCrateSizePlanner';
 
 export { petsCategory } from './category';
 export const PetsCategorySEO = () => import('./category/seo.astro').then((m) => m.default);

package/src/tests/i18n_coverage.test.ts

@@ -4,6 +4,7 @@ import { ALL_TOOLS } from '../tools';
 const EXPECTED_LOCALES = [
   'de', 'en', 'es', 'fr', 'id', 'it', 'ja', 'ko', 'nl', 'pl', 'pt', 'ru', 'sv', 'tr', 'zh'
 ];
+const ENGLISH_FIRST_TOOLS = new Set(['pet-carrier-crate-size-planner']);
 
 describe('I18n Coverage Validation', () => {
   it('all tools should be registered', () => {
@@ -12,9 +13,11 @@ describe('I18n Coverage Validation', () => {
 
   ALL_TOOLS.forEach(({ entry }: { entry: any }) => {
     describe(`Tool: ${entry.id}`, () => {
+      const expectedLocales = ENGLISH_FIRST_TOOLS.has(entry.id) ? ['en'] : EXPECTED_LOCALES;
+
       it('should have all 15 required locales', () => {
         const registeredLocales = Object.keys(entry.i18n);
-        EXPECTED_LOCALES.forEach((locale) => {
+        expectedLocales.forEach((locale) => {
           expect(
             registeredLocales,
             `Tool "${entry.id}" is missing locale "${locale}"`,
@@ -23,7 +26,7 @@ describe('I18n Coverage Validation', () => {
       });
 
       it('all locale loaders should be functions', () => {
-        EXPECTED_LOCALES.forEach((locale) => {
+        expectedLocales.forEach((locale) => {
           const loader = entry.i18n[locale as keyof typeof entry.i18n];
           expect(
             typeof loader,

package/src/tests/locale_completeness.test.ts

@@ -26,6 +26,6 @@ describe('Locale Completeness Validation', () => {
   });
 
   it('all tools registered', () => {
-    expect(ALL_TOOLS.length).toBe(5);
+    expect(ALL_TOOLS.length).toBe(6);
   });
 });

package/src/tests/qa-test-helpers.ts

@@ -0,0 +1,32 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export const repositoryRoot = process.cwd();
+export const toolRoot = join(repositoryRoot, 'src', 'tool');
+
+export function listToolDirectories(): string[] {
+  return readdirSync(toolRoot)
+    .map((name) => join(toolRoot, name))
+    .filter((path) => statSync(path).isDirectory());
+}
+
+export function findFiles(directory: string, extensions: string[]): string[] {
+  const files: string[] = [];
+
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...findFiles(path, extensions));
+    else if (extensions.some((extension) => entry.name.endsWith(extension))) files.push(path);
+  }
+
+  return files;
+}
+
+export function read(path: string): string {
+  return readFileSync(path, 'utf8');
+}
+
+export function displayPath(path: string): string {
+  return relative(repositoryRoot, path).replace(/\\/g, '/');
+}
+

package/src/tests/qa_bibliography_links.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import type { ToolLocaleContent } from '../types';
+
+interface LinkFailure {
+  tool: string;
+  message: string;
+}
+
+function checkBibliographyEntry(tool: string, entry: { url: string }, seen: Set<string>): LinkFailure[] {
+  const failures: LinkFailure[] = [];
+  let url: URL;
+  try {
+    url = new URL(entry.url);
+  } catch {
+    return [{ tool, message: `invalid URL: ${entry.url}` }];
+  }
+
+  if (url.protocol !== 'https:') failures.push({ tool, message: `non-HTTPS URL: ${entry.url}` });
+  if (url.pathname === '/' && !url.search && !url.hash) failures.push({ tool, message: `generic homepage, cite the exact document: ${entry.url}` });
+  if (seen.has(url.href)) failures.push({ tool, message: `duplicate source URL: ${entry.url}` });
+  seen.add(url.href);
+  return failures;
+}
+
+async function checkToolBibliography(tool: (typeof ALL_TOOLS)[number]): Promise<LinkFailure[]> {
+  const loader = tool.entry.i18n.en;
+  if (!loader) return [{ tool: tool.entry.id, message: 'English locale loader is missing' }];
+  const content = (await loader()) as ToolLocaleContent;
+  const seen = new Set<string>();
+  return (content.bibliography ?? []).flatMap((entry) => checkBibliographyEntry(tool.entry.id, entry, seen));
+}
+
+describe('QA: bibliography links are specific and usable', () => {
+  it('uses unique HTTPS links to exact source pages instead of generic homepages', async () => {
+    const failures = (await Promise.all(ALL_TOOLS.map(checkToolBibliography))).flat();
+    const messages = failures.map(({ tool, message }) => `${tool}: ${message}`);
+    expect(messages, `Bibliography hygiene failures:\n${messages.join('\n')}`).toEqual([]);
+  });
+});

package/src/tests/qa_claim_evidence.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { displayPath, listToolDirectories, read } from './qa-test-helpers';
+
+const evidenceClaims = [
+  /\bofficial algorithm\b/i,
+  /\balgoritmo oficial\b/i,
+  /\b(?:records|data|rates|tables) updated(?:\s+(?:to|through)\s+20\d{2})?\b/i,
+  /\b(?:registros|datos|tasas|tablas) actualizad[oa]s?(?:\s+(?:a|hasta)\s+20\d{2})?\b/i,
+  /\b(?:validated|verified) (?:method|algorithm|calculation)\b/i,
+  /\b(?:método|algoritmo|cálculo) (?:validado|verificado)\b/i,
+  /\b(?:guarantees|ensures)\b/i,
+  /\bgarantiza\b/i,
+  /\bofficial (?:data|rate|calculation)\b/i,
+  /\b(?:datos|tasa|cálculo) oficial(?:es)?\b/i,
+];
+
+const requiredEvidenceFields = [
+  'reviewedAt',
+  'methodology',
+  'sources',
+  'referenceCases',
+  'limitations',
+];
+
+describe('QA: strong factual claims are traceable', () => {
+  it('requires machine-readable validation evidence beside tools making strong claims', () => {
+    const failures: string[] = [];
+
+    for (const directory of listToolDirectories()) {
+      const localePaths = ['en', 'es']
+        .map((locale) => join(directory, 'i18n', `${locale}.ts`))
+        .filter(existsSync);
+      const claims = localePaths.flatMap((path) => {
+        const source = read(path);
+        return evidenceClaims
+          .filter((pattern) => pattern.test(source))
+          .map((pattern) => `${displayPath(path)} matches ${pattern.source}`);
+      });
+      if (claims.length === 0) continue;
+
+      const evidencePath = join(directory, 'validation.ts');
+      if (!existsSync(evidencePath)) {
+        failures.push(`${displayPath(evidencePath)} missing; claims: ${claims.join(' | ')}`);
+        continue;
+      }
+
+      const evidence = read(evidencePath);
+      const missingFields = requiredEvidenceFields.filter(
+        (field) => !new RegExp(`\\b${field}\\s*:`).test(evidence),
+      );
+      if (missingFields.length > 0) {
+        failures.push(`${displayPath(evidencePath)} missing fields: ${missingFields.join(', ')}`);
+      }
+    }
+
+    expect(
+      failures,
+      [
+        'Claims such as official, validated, guaranteed or updated need inspectable evidence.',
+        'Add validation.ts with reviewedAt, methodology, sources, referenceCases and limitations,',
+        'or weaken/remove the unsupported claim.',
+        ...failures,
+      ].join('\n'),
+    ).toEqual([]);
+  });
+});
+

package/src/tests/qa_logic_reference_coverage.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { basename, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  displayPath,
+  findFiles,
+  listToolDirectories,
+  read,
+  repositoryRoot,
+} from './qa-test-helpers';
+
+function hasDedicatedLogicTest(toolDirectory: string): boolean {
+  const localCandidates = [
+    join(toolDirectory, 'logic.test.ts'),
+    join(toolDirectory, 'logic.spec.ts'),
+    join(toolDirectory, '__tests__', 'logic.test.ts'),
+    join(toolDirectory, '__tests__', 'logic.spec.ts'),
+  ];
+  if (localCandidates.some(existsSync)) return true;
+
+  const toolName = basename(toolDirectory);
+  const centralTests = findFiles(join(repositoryRoot, 'src', 'tests'), ['.test.ts', '.spec.ts']);
+  return centralTests.some((testPath) => {
+    const source = read(testPath).replace(/\\/g, '/');
+    return source.includes(`/tool/${toolName}/logic`) || source.includes(`../tool/${toolName}/logic`);
+  });
+}
+
+describe('QA: calculation logic has reference tests', () => {
+  it('gives every public calculator logic module its own behavioral test suite', () => {
+    const failures = listToolDirectories()
+      .filter((directory) => existsSync(join(directory, 'logic.ts')))
+      .filter((directory) => !hasDedicatedLogicTest(directory))
+      .map((directory) => `${displayPath(join(directory, 'logic.ts'))} -> no test imports this module`);
+
+    expect(
+      failures,
+      [
+        'Add behavioral tests through each logic module public API.',
+        'At minimum cover a documented reference case, boundaries, invalid input and invariants.',
+        ...failures,
+      ].join('\n'),
+    ).toEqual([]);
+  });
+});
+

package/src/tests/qa_runtime_i18n.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import { basename, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  displayPath,
+  findFiles,
+  listToolDirectories,
+  read,
+  repositoryRoot,
+} from './qa-test-helpers';
+
+interface VisibleLiteral {
+  line: number;
+  value: string;
+}
+
+const domTextAssignment = /\.(?:innerText|textContent|innerHTML)\s*=/;
+const quotedLiteral = /(['"`])((?:\\.|(?!\1).)*)\1/g;
+
+function visibleWords(value: string): string {
+  return value
+    .replace(/\$\{[^}]*\}/g, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&[a-z]+;/gi, ' ')
+    .replace(/[\d\p{P}\p{S}_]+/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function isTechnicalLiteral(value: string): boolean {
+  return ['.', '#', '['].some((prefix) => value.startsWith(prefix))
+    || /^data-[a-z0-9-]+$/i.test(value);
+}
+
+function hardcodedVisibleLiterals(source: string): VisibleLiteral[] {
+  const failures: VisibleLiteral[] = [];
+
+  source.split(/\r?\n/).forEach((line, index) => {
+    if (!domTextAssignment.test(line)) return;
+
+    const assignment = line.slice(line.search(domTextAssignment));
+    for (const match of assignment.matchAll(quotedLiteral)) {
+      const value = match[2];
+      if (!value || isTechnicalLiteral(value)) continue;
+      const words = visibleWords(value);
+      if (words && /\p{L}/u.test(words)) {
+        failures.push({ line: index + 1, value });
+      }
+    }
+  });
+
+  return failures;
+}
+
+function runtimeSources(toolDirectory: string): string {
+  return findFiles(toolDirectory, ['.astro', '.ts', '.js'])
+    .filter((path) => !path.includes(`${join(toolDirectory, 'i18n')}`))
+    .filter((path) => basename(path) !== 'ui.ts')
+    .map(read)
+    .join('\n');
+}
+
+describe('QA: runtime copy is localized', () => {
+  const componentFiles = findFiles(join(repositoryRoot, 'src', 'tool'), ['.astro']);
+
+  it('does not write user-facing string literals directly into the DOM', () => {
+    const failures = componentFiles.flatMap((path) =>
+      hardcodedVisibleLiterals(read(path)).map(
+        ({ line, value }) => `${displayPath(path)}:${line} -> ${JSON.stringify(value)}`,
+      ),
+    );
+
+    expect(
+      failures,
+      `Move visible browser copy to the tool UI locale contract:\n${failures.join('\n')}`,
+    ).toEqual([]);
+  });
+
+  it('uses every string declared by each UI locale contract', () => {
+    const failures: string[] = [];
+
+    for (const directory of listToolDirectories()) {
+      const uiPath = join(directory, 'ui.ts');
+      if (!existsSync(uiPath)) continue;
+
+      const keys = Array.from(read(uiPath).matchAll(/^\s*(\w+)\??:\s*string\s*;/gm), (match) => match[1]);
+      const runtime = runtimeSources(directory);
+      const unused = keys.filter((key) => !new RegExp(`\\b${key}\\b`).test(runtime));
+
+      if (unused.length > 0) {
+        failures.push(`${displayPath(uiPath)} -> unused: ${unused.join(', ')}`);
+      }
+    }
+
+    expect(
+      failures,
+      `Unused locale keys are dead copy or may mean the browser bypasses translations:\n${failures.join('\n')}`,
+    ).toEqual([]);
+  });
+});

package/src/tests/tool_validation.test.ts

@@ -71,7 +71,7 @@ describe('Tool Validation Suite', () => {
               expect(content.slug).toMatch(/^[a-z0-9]+(-[a-z0-9]+)*$/);
 
               if (locale === 'es') {
-                const validSlugs = ['calculadora-edad-mascotas', 'calculadora-racion-diaria-mascotas', 'calculadora-gestacion-mascotas', 'buscador-alimentos-toxicos-perros-gatos', 'calculadora-agua-diaria-perros-gatos'];
+                const validSlugs = ['calculadora-edad-mascotas', 'calculadora-racion-diaria-mascotas', 'calculadora-gestacion-mascotas', 'buscador-alimentos-toxicos-perros-gatos', 'calculadora-agua-diaria-perros-gatos', 'planificador-dimensiones-transportin-mascotas'];
                 expect(validSlugs).toContain(content.slug);
               }
             });
@@ -97,11 +97,11 @@ describe('Tool Validation Suite', () => {
 
   describe('Library Registration', () => {
     it('should have 5 tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(5);
+      expect(ALL_TOOLS.length).toBe(6);
     });
 
     it('should have all tools in petsCategory', () => {
-      expect(petsCategory.tools.length).toBe(5);
+      expect(petsCategory.tools.length).toBe(6);
       ALL_TOOLS.forEach(({ entry }) => {
         const exists = petsCategory.tools.some((t: any) => t.id === entry.id);
         expect(exists).toBe(true);

package/src/tool/petCarrierCrateSizePlanner/bibliography.astro

@@ -0,0 +1,6 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { bibliography } from './bibliography';
+---
+
+<SharedBibliography links={bibliography} />

package/src/tool/petCarrierCrateSizePlanner/bibliography.ts

@@ -0,0 +1,12 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  {
+    name: 'International Air Transport Association: Traveler\'s Pet Corner',
+    url: 'https://www.iata.org/en/programs/cargo/live-animals/pets/',
+  },
+  {
+    name: 'USDA APHIS: Preparing Pets for Air Travel',
+    url: 'https://www.aphis.usda.gov/pet-travel/pets-on-planes/preparing-pets-air-travel',
+  },
+];

package/src/tool/petCarrierCrateSizePlanner/component.astro

@@ -0,0 +1,89 @@
+---
+import { Icon } from 'astro-icon/components';
+import type { PetCarrierCrateSizePlannerUI } from './index';
+
+interface Props {
+  ui: PetCarrierCrateSizePlannerUI;
+}
+
+const { ui } = Astro.props;
+---
+
+<div class="pet-carrier-crate-size-planner" data-carrier-root>
+  <script is:inline type="application/json" data-carrier-ui set:html={JSON.stringify(ui)}></script>
+  <header class="carrier-hero">
+    <div class="carrier-hero-copy">
+      <p class="carrier-kicker">{ui.heroEyebrow}</p>
+      <p class="carrier-journey">{ui.journeyHint}</p>
+    </div>
+    <div class="unit-switch" role="group" aria-label={ui.unitLegend}>
+      <span>{ui.unitLegend}</span>
+      <button type="button" data-unit="metric" aria-pressed="true">{ui.metricUnit}</button>
+      <button type="button" data-unit="imperial" aria-pressed="false">{ui.imperialUnit}</button>
+    </div>
+  </header>
+  <div class="carrier-workbench">
+    <div class="carrier-controls">
+      <div class="carrier-panel-heading">
+        <span class="carrier-step">01</span>
+        <div><p>{ui.speciesStep}</p><h2>{ui.speciesLegend}</h2></div>
+      </div>
+      <fieldset>
+        <legend>{ui.speciesLegend}</legend>
+        <div class="choice-row">
+          <button type="button" data-species="cat" aria-pressed="true"><Icon name="mdi:cat" /><span>{ui.speciesCat}</span></button>
+          <button type="button" data-species="dog" aria-pressed="false"><Icon name="mdi:dog-side" /><span>{ui.speciesDog}</span></button>
+        </div>
+      </fieldset>
+      <fieldset>
+        <legend>{ui.modeLegend}</legend>
+        <div class="choice-row mode-row">
+          <button type="button" data-mode="car" aria-pressed="true"><Icon name="mdi:car-side" /><span>{ui.modeCar}</span></button>
+          <button type="button" data-mode="air" aria-pressed="false"><Icon name="mdi:airplane" /><span>{ui.modeAir}</span></button>
+        </div>
+      </fieldset>
+      <fieldset class="measurements">
+        <legend>{ui.measurementsLegend}</legend>
+        <label><span>{ui.noseTailLabel}<small>{ui.noseTailHint}</small></span><input data-field="noseToTail" type="number" min="1" step="0.1" inputmode="decimal" /><b data-length-unit>{ui.cmUnit}</b></label>
+        <label><span>{ui.elbowHeightLabel}</span><input data-field="elbowHeight" type="number" min="1" step="0.1" inputmode="decimal" /><b data-length-unit>{ui.cmUnit}</b></label>
+        <label><span>{ui.shoulderWidthLabel}</span><input data-field="shoulderWidth" type="number" min="1" step="0.1" inputmode="decimal" /><b data-length-unit>{ui.cmUnit}</b></label>
+        <label><span>{ui.standingHeightLabel}</span><input data-field="standingHeight" type="number" min="1" step="0.1" inputmode="decimal" /><b data-length-unit>{ui.cmUnit}</b></label>
+        <label><span>{ui.beddingLabel}</span><input data-field="bedding" type="number" min="0" step="0.1" inputmode="decimal" /><b data-length-unit>{ui.cmUnit}</b></label>
+        <label><span>{ui.weightLabel}</span><input data-field="weight" type="number" min="0.1" step="0.1" inputmode="decimal" /><b data-weight-unit>{ui.kgUnit}</b></label>
+      </fieldset>
+      <label class="snub-toggle"><input data-snub-nosed type="checkbox" /><span><strong>{ui.snubNosedLabel}</strong><small>{ui.snubNosedHint}</small></span></label>
+      <div class="preset-strip">
+        <span>{ui.presetLegend}</span>
+        <button type="button" data-preset="cat">{ui.presetCat}</button>
+        <button type="button" data-preset="smallDog">{ui.presetSmallDog}</button>
+        <button type="button" data-preset="mediumDog">{ui.presetMediumDog}</button>
+        <button type="button" data-preset="largeDog">{ui.presetLargeDog}</button>
+      </div>
+      <p class="carrier-error" data-error role="alert"></p>
+    </div>
+    <section class="carrier-result" data-result aria-live="polite">
+      <div class="result-heading"><div class="result-title-row"><div><p>{ui.resultEyebrow}</p><h2>{ui.resultTitle}</h2></div><span class="result-status" data-status></span></div><span class="result-status-detail" data-status-detail></span></div>
+      <div class="carrier-scene" data-scene aria-label={ui.blueprintLabel}></div>
+      <div class="dimension-ledger">
+        <p>{ui.resultDimensionLabel}</p>
+        <div class="dimension-primary"><div><span>{ui.lengthLabel}</span><strong data-length-result></strong></div><div><span>{ui.widthLabel}</span><strong data-width-result></strong></div><div><span>{ui.heightLabel}</span><strong data-height-result></strong></div></div>
+        <div class="dimension-context"><div><span>{ui.petWeightLabel}</span><strong data-weight-result></strong></div><div><span>{ui.journeyLabel}</span><strong data-mode-result></strong></div></div>
+      </div>
+      <div class="carrier-checklist">
+        <h3>{ui.checklistTitle}</h3>
+        <p><span>{ui.checkMark}</span>{ui.checklistStand}</p>
+        <p><span>{ui.checkMark}</span>{ui.checklistTurn}</p>
+        <p><span>{ui.checkMark}</span>{ui.checklistLie}</p>
+        <p><span>{ui.checkMark}</span>{ui.checklistAirline}</p>
+      </div>
+    </section>
+  </div>
+  <aside class="carrier-note"><strong>{ui.noteTitle}</strong><span>{ui.noteText}</span></aside>
+  <p class="carrier-method"><strong>{ui.methodTitle}</strong> {ui.methodText}</p>
+</div>
+
+<script>
+  import { initCarrierController } from './controller';
+  const root = document.querySelector<HTMLElement>('[data-carrier-root]');
+  if (root) initCarrierController(root);
+</script>

package/src/tool/petCarrierCrateSizePlanner/controller.ts

@@ -0,0 +1,128 @@
+import { calculateCarrier, convertLength, convertWeight, formatInputValue, type PetSpecies, type TravelMode, type UnitSystem } from './logic';
+import { renderEvaluation, renderScene } from './dom-views';
+import { loadCarrierState, saveCarrierState, type CarrierStorageState } from './storage';
+import type { PetCarrierCrateSizePlannerUI } from './ui';
+
+type LengthField = 'noseToTail' | 'elbowHeight' | 'shoulderWidth' | 'standingHeight' | 'bedding';
+type ControllerState = CarrierStorageState;
+
+const presets: Record<string, Omit<CarrierStorageState, 'unit' | 'mode' | 'snubNosed'>> = {
+  cat: { species: 'cat', noseToTail: 45, elbowHeight: 15, shoulderWidth: 16, standingHeight: 35, bedding: 2, weight: 5 },
+  smallDog: { species: 'dog', noseToTail: 45, elbowHeight: 16, shoulderWidth: 18, standingHeight: 38, bedding: 2, weight: 7 },
+  mediumDog: { species: 'dog', noseToTail: 70, elbowHeight: 30, shoulderWidth: 22, standingHeight: 55, bedding: 3, weight: 18 },
+  largeDog: { species: 'dog', noseToTail: 90, elbowHeight: 38, shoulderWidth: 28, standingHeight: 72, bedding: 4, weight: 32 },
+};
+
+function readUI(root: HTMLElement): PetCarrierCrateSizePlannerUI {
+  const script = root.querySelector<HTMLScriptElement>('[data-carrier-ui]');
+  return JSON.parse(script?.textContent || '{}') as PetCarrierCrateSizePlannerUI;
+}
+
+function defaultState(): ControllerState {
+  return {
+    species: 'cat',
+    mode: 'car',
+    unit: 'metric',
+    noseToTail: 45,
+    elbowHeight: 15,
+    shoulderWidth: 16,
+    standingHeight: 35,
+    bedding: 2,
+    weight: 5,
+    snubNosed: false,
+  };
+}
+
+function mergeState(stored: Partial<ControllerState>): ControllerState {
+  const cleanStored = { ...stored } as Partial<ControllerState> & { theme?: unknown };
+  delete cleanStored.theme;
+  return { ...defaultState(), ...cleanStored };
+}
+
+function setPressed(root: HTMLElement, attribute: string, value: string): void {
+  root.querySelectorAll<HTMLButtonElement>(`[data-${attribute}]`).forEach((button) => {
+    const active = button.dataset[attribute] === value;
+    button.classList.toggle('is-active', active);
+    button.setAttribute('aria-pressed', String(active));
+  });
+}
+
+function setInput(root: HTMLElement, field: string, value: number): void {
+  const input = root.querySelector<HTMLInputElement>(`[data-field="${field}"]`);
+  if (input) input.value = formatInputValue(value);
+}
+
+function syncStateToForm(root: HTMLElement, state: ControllerState, ui: PetCarrierCrateSizePlannerUI): void {
+  (Object.keys(state) as (keyof ControllerState)[]).forEach((field) => {
+    if (typeof state[field] === 'number') setInput(root, field, state[field] as number);
+  });
+  setPressed(root, 'species', state.species);
+  setPressed(root, 'mode', state.mode);
+  setPressed(root, 'unit', state.unit);
+  const snub = root.querySelector<HTMLInputElement>('[data-snub-nosed]');
+  if (snub) snub.checked = state.snubNosed;
+  root.querySelectorAll<HTMLElement>('[data-length-unit]').forEach((element) => { element.textContent = state.unit === 'metric' ? ui.cmUnit : ui.inchUnit; });
+  const weightUnit = root.querySelector<HTMLElement>('[data-weight-unit]');
+  if (weightUnit) weightUnit.textContent = state.unit === 'metric' ? ui.kgUnit : ui.lbUnit;
+}
+
+function readNumbers(root: HTMLElement, state: ControllerState): void {
+  const fields: LengthField[] = ['noseToTail', 'elbowHeight', 'shoulderWidth', 'standingHeight', 'bedding'];
+  fields.forEach((field) => { const input = root.querySelector<HTMLInputElement>(`[data-field="${field}"]`); if (input) state[field] = Number(input.value); });
+  const weight = root.querySelector<HTMLInputElement>('[data-field="weight"]');
+  if (weight) state.weight = Number(weight.value);
+}
+
+function render(root: HTMLElement, state: ControllerState, ui: PetCarrierCrateSizePlannerUI): void {
+  try {
+    readNumbers(root, state);
+    const result = calculateCarrier(state);
+    saveCarrierState(state);
+    const scene = root.querySelector<HTMLElement>('[data-scene]');
+    if (scene) renderScene(scene, result, ui);
+    renderEvaluation(root, result, ui);
+    const error = root.querySelector<HTMLElement>('[data-error]');
+    if (error) error.textContent = '';
+  } catch {
+    const error = root.querySelector<HTMLElement>('[data-error]');
+    if (error) error.textContent = ui.invalidInput;
+  }
+}
+
+function changeUnit(root: HTMLElement, state: ControllerState, ui: PetCarrierCrateSizePlannerUI, unit: UnitSystem): void {
+  if (state.unit === unit) return;
+  const fields: LengthField[] = ['noseToTail', 'elbowHeight', 'shoulderWidth', 'standingHeight', 'bedding'];
+  fields.forEach((field) => { state[field] = convertLength(state[field], state.unit, unit); });
+  state.weight = convertWeight(state.weight, state.unit, unit);
+  state.unit = unit;
+  syncStateToForm(root, state, ui);
+  render(root, state, ui);
+}
+
+function applyPreset(root: HTMLElement, state: ControllerState, ui: PetCarrierCrateSizePlannerUI, key: string): void {
+  const preset = presets[key];
+  if (!preset) return;
+  const currentUnit = state.unit;
+  const metric = { ...preset, unit: 'metric' as const, mode: state.mode, snubNosed: state.snubNosed };
+  Object.assign(state, metric, { unit: currentUnit });
+  if (currentUnit === 'imperial') {
+    const fields: LengthField[] = ['noseToTail', 'elbowHeight', 'shoulderWidth', 'standingHeight', 'bedding'];
+    fields.forEach((field) => { state[field] = convertLength(state[field], 'metric', 'imperial'); });
+    state.weight = convertWeight(state.weight, 'metric', 'imperial');
+  }
+  syncStateToForm(root, state, ui);
+  render(root, state, ui);
+}
+
+export function initCarrierController(root: HTMLElement): void {
+  const ui = readUI(root);
+  const state = mergeState(loadCarrierState());
+  syncStateToForm(root, state, ui);
+  root.querySelectorAll<HTMLButtonElement>('[data-species]').forEach((button) => button.addEventListener('click', () => { state.species = (button.dataset.species || 'cat') as PetSpecies; setPressed(root, 'species', state.species); render(root, state, ui); }));
+  root.querySelectorAll<HTMLButtonElement>('[data-mode]').forEach((button) => button.addEventListener('click', () => { state.mode = (button.dataset.mode || 'car') as TravelMode; setPressed(root, 'mode', state.mode); render(root, state, ui); }));
+  root.querySelectorAll<HTMLButtonElement>('[data-unit]').forEach((button) => button.addEventListener('click', () => changeUnit(root, state, ui, (button.dataset.unit || 'metric') as UnitSystem)));
+  root.querySelectorAll<HTMLButtonElement>('[data-preset]').forEach((button) => button.addEventListener('click', () => applyPreset(root, state, ui, button.dataset.preset || 'cat')));
+  root.querySelectorAll<HTMLInputElement>('[data-field]').forEach((input) => input.addEventListener('input', () => render(root, state, ui)));
+  root.querySelector<HTMLInputElement>('[data-snub-nosed]')?.addEventListener('change', (event) => { state.snubNosed = (event.target as HTMLInputElement).checked; render(root, state, ui); });
+  render(root, state, ui);
+}