@jjlmoya/utils-aquarium 1.0.0

package/src/tool/aquariumTankVolumeWaterChangeCalculator/dom-views.ts

@@ -0,0 +1,64 @@
+import type { AquariumTankVolumeWaterChangeCalculatorUI } from './ui';
+import type { TankVolume, UnitSystem } from './logic';
+import { getSubstrateShare, getTankScale } from './evaluator';
+import { kilogramsToPounds, litresToGallons } from './logic';
+
+function getElement<T extends HTMLElement>(root: HTMLElement, selector: string): T | null {
+  return root.querySelector<T>(selector);
+}
+
+function setText(root: HTMLElement, selector: string, text: string): void {
+  const element = getElement<HTMLElement>(root, selector);
+  if (element !== null) element.textContent = text;
+}
+
+function formatNumber(value: number, locale: string): string {
+  return new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(value);
+}
+
+function displayVolume(value: number, unit: UnitSystem, locale: string): string {
+  const amount = unit === 'metric' ? value : litresToGallons(value);
+  const label = unit === 'metric' ? 'L' : 'US gal';
+  return formatNumber(amount, locale) + ' ' + label;
+}
+
+function displayMass(value: number, unit: UnitSystem, locale: string): string {
+  const amount = unit === 'metric' ? value : kilogramsToPounds(value);
+  const label = unit === 'metric' ? 'kg' : 'lb';
+  return formatNumber(amount, locale) + ' ' + label;
+}
+
+interface RenderOptions {
+  result: TankVolume;
+  unit: UnitSystem;
+  locale: string;
+  ui: AquariumTankVolumeWaterChangeCalculatorUI;
+}
+
+export function renderResults(root: HTMLElement, options: RenderOptions): void {
+  const { result, unit, locale, ui } = options;
+  setText(root, '[data-result="gross"]', displayVolume(result.grossLitres, unit, locale));
+  setText(root, '[data-result="substrate"]', displayVolume(result.substrateLitres, unit, locale));
+  setText(root, '[data-result="net"]', displayVolume(result.netLitres, unit, locale));
+  setText(root, '[data-result="change"]', displayVolume(result.changeLitres, unit, locale));
+  setText(root, '[data-result="mass"]', displayMass(result.waterMassKg, unit, locale));
+  setText(root, '[data-result="footprint"]', formatNumber(result.footprintCm2 / 10000, locale) + ' m²');
+  setText(root, '[data-result="share"]', formatNumber(getSubstrateShare(result), locale) + '%');
+  setText(root, '[data-result="scale"]', ui[getTankScale(result.netLitres)] ?? '');
+  const water = getElement<HTMLElement>(root, '[data-water]');
+  if (water !== null) water.style.setProperty('--water-level', String(Math.min(92, Math.max(20, result.netLitres / 4))));
+  root.classList.add('has-results');
+  root.classList.remove('has-error');
+}
+
+export function renderError(root: HTMLElement, message: string): void {
+  setText(root, '[data-error]', message);
+  root.classList.remove('has-results');
+  root.classList.add('has-error');
+}
+
+export function renderEmpty(root: HTMLElement, message: string): void {
+  setText(root, '[data-empty]', message);
+  root.classList.remove('has-results');
+  root.classList.remove('has-error');
+}

package/src/tool/aquariumTankVolumeWaterChangeCalculator/entry.ts

@@ -0,0 +1,13 @@
+import type { AquariumToolEntry, ToolLocaleContent } from '../../types';
+import type { AquariumTankVolumeWaterChangeCalculatorUI } from './ui';
+
+export type { AquariumTankVolumeWaterChangeCalculatorUI };
+export type AquariumTankVolumeWaterChangeCalculatorLocaleContent = ToolLocaleContent<AquariumTankVolumeWaterChangeCalculatorUI>;
+
+export const aquariumTankVolumeWaterChangeCalculator: AquariumToolEntry<AquariumTankVolumeWaterChangeCalculatorUI> = {
+  id: 'aquarium-tank-volume-water-change-calculator',
+  icons: { bg: 'mdi:fishbowl-outline', fg: 'mdi:water-opacity' },
+  i18n: {
+    en: () => import('./i18n/en').then((m) => m.content),
+  },
+};

package/src/tool/aquariumTankVolumeWaterChangeCalculator/evaluator.ts

@@ -0,0 +1,19 @@
+import type { TankVolume } from './logic';
+
+export type TankScale = 'nano' | 'compact' | 'roomy' | 'showcase';
+
+export function getTankScale(litres: number): TankScale {
+  if (litres < 20) return 'nano';
+  if (litres < 100) return 'compact';
+  if (litres < 300) return 'roomy';
+  return 'showcase';
+}
+
+export function getSubstrateShare(volume: TankVolume): number {
+  if (volume.grossLitres <= 0) return 0;
+  return volume.substrateLitres / volume.grossLitres * 100;
+}
+
+export function clampPercentage(value: number): number {
+  return Math.min(100, Math.max(0, value));
+}

package/src/tool/aquariumTankVolumeWaterChangeCalculator/i18n/en.ts

@@ -0,0 +1,186 @@
+import { bibliography } from '../bibliography';
+import type { FAQPage, HowTo, SoftwareApplication, WithContext } from 'schema-dts';
+import type { ToolLocaleContent } from '../../../types';
+import type { AquariumTankVolumeWaterChangeCalculatorUI } from '../ui';
+
+const slug = 'aquarium-tank-volume-water-change-calculator';
+const title = 'Aquarium Tank Volume and Water Change Calculator';
+const description = 'Calculate usable aquarium volume, substrate displacement, water change litres and water weight from your own tank dimensions. Works offline with Metric and Imperial units.';
+
+const faq = [
+  {
+    question: 'Does this calculator use the advertised tank capacity?',
+    answer: 'No. It subtracts the substrate depth from the geometric tank volume, so the result is an estimate of usable water volume rather than a manufacturer capacity claim.',
+  },
+  {
+    question: 'How does the bow front option work?',
+    answer: 'It adds a two thirds circular segment to the rectangular footprint. Treat that result as an approximation because real curved glass profiles vary by tank.',
+  },
+  {
+    question: 'Which imperial units are shown?',
+    answer: 'Imperial mode shows US gallons for volume, pounds for water mass and inches for dimensions.',
+  },
+  {
+    question: 'Does this recommend a water change schedule?',
+    answer: 'No. It only calculates the amount represented by the percentage you enter. It does not assess water quality, stocking, species or husbandry.',
+  },
+  {
+    question: 'Does my data leave the browser?',
+    answer: 'No network request is needed for the calculation. Your last local settings may be saved in this browser so the form can reopen with the same values.',
+  },
+];
+
+const howTo = [
+  {
+    name: 'Choose the tank shape',
+    text: 'Select rectangular, cylindrical or bow front. The form shows only the dimensions needed for that shape.',
+  },
+  {
+    name: 'Enter inside dimensions',
+    text: 'Enter the tank length, width and height, or the diameter and height for a cylinder. Use inside measurements when possible.',
+  },
+  {
+    name: 'Account for substrate',
+    text: 'Enter the average substrate depth. The calculator subtracts that layer from the gross geometric volume.',
+  },
+  {
+    name: 'Set the water change percentage',
+    text: 'Choose the percentage you plan to replace. The result gives the corresponding volume and approximate water mass.',
+  },
+];
+
+const faqSchema: WithContext<FAQPage> = {
+  '@context': 'https://schema.org',
+  '@type': 'FAQPage',
+  mainEntity: faq.map((item) => ({
+    '@type': 'Question',
+    name: item.question,
+    acceptedAnswer: { '@type': 'Answer', text: item.answer },
+  })),
+};
+
+const howToSchema: WithContext<HowTo> = {
+  '@context': 'https://schema.org',
+  '@type': 'HowTo',
+  name: title,
+  description,
+  step: howTo.map((step, index) => ({
+    '@type': 'HowToStep',
+    position: index + 1,
+    name: step.name,
+    text: step.text,
+  })),
+};
+
+const appSchema: WithContext<SoftwareApplication> = {
+  '@context': 'https://schema.org',
+  '@type': 'SoftwareApplication',
+  name: title,
+  description,
+  applicationCategory: 'UtilityApplication',
+  operatingSystem: 'All',
+  offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
+  inLanguage: 'en',
+};
+
+export const content: ToolLocaleContent<AquariumTankVolumeWaterChangeCalculatorUI> = {
+  slug,
+  title,
+  description,
+  faq,
+  bibliography,
+  howTo,
+  schemas: [faqSchema, howToSchema, appSchema],
+  seo: [
+    {
+      type: 'title',
+      text: 'Know the Water You Really Have',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'A tank may be sold with a headline capacity that does not match the water you can actually fill. This calculator turns inside dimensions into a clearer working estimate, then removes the substrate layer before it tells you how much a chosen water change represents.',
+    },
+    {
+      type: 'title',
+      text: 'Three Tank Shapes in One Quiet Lab',
+      level: 2,
+    },
+    {
+      type: 'list',
+      items: [
+        '<strong>Rectangular:</strong> length multiplied by width multiplied by height.',
+        '<strong>Cylindrical:</strong> pi multiplied by radius squared multiplied by height.',
+        '<strong>Bow front:</strong> rectangular footprint plus a two thirds circular segment approximation.',
+      ],
+    },
+    {
+      type: 'title',
+      text: 'From Glass to Gravel to Water',
+      level: 2,
+    },
+    {
+      type: 'paragraph',
+      html: 'The working volume is the geometric volume minus the volume occupied by the substrate layer. The water change result is that working volume multiplied by your chosen percentage. Water mass uses a rounded density of 1 kilogram per litre, so temperature, salinity and dissolved material can shift the real value slightly.',
+    },
+    {
+      type: 'tip',
+      title: 'Measure inside the tank',
+      html: '<p>Use internal dimensions and the average substrate depth. A ruler and a quick three-point average will usually be more useful than relying on a product box capacity.</p>',
+    },
+    {
+      type: 'table',
+      headers: ['Output', 'What it means'],
+      rows: [
+        ['Gross volume', 'The geometric volume before substrate displacement'],
+        ['Substrate volume', 'The estimated space occupied by the substrate layer'],
+        ['Net water volume', 'The working water estimate after displacement'],
+        ['Water change', 'The entered percentage of the net water volume'],
+      ],
+    },
+  ],
+  ui: {
+    toolTitle: 'Tank volume lab',
+    toolSubtitle: 'Shape, substrate and water change in one calm view.',
+    dimensionsTitle: 'Tank dimensions',
+    shapeLabel: 'Tank shape',
+    rectangularShape: 'Rectangular',
+    cylindricalShape: 'Cylindrical',
+    bowShape: 'Bow front',
+    lengthLabel: 'Inside length',
+    widthLabel: 'Inside width',
+    heightLabel: 'Inside height',
+    diameterLabel: 'Inside diameter',
+    bowDepthLabel: 'Front curve depth',
+    substrateLabel: 'Average substrate depth',
+    changeLabel: 'Water change',
+    unitLabel: 'Units',
+    metricLabel: 'Metric',
+    imperialLabel: 'Imperial',
+    calculateLabel: 'Calculate volume',
+    resetLabel: 'Reset',
+    grossVolumeLabel: 'Gross volume',
+    substrateVolumeLabel: 'Substrate displacement',
+    netVolumeLabel: 'Net water volume',
+    changeVolumeLabel: 'Water to replace',
+    waterWeightLabel: 'Water weight',
+    emptyState: 'Adjust the dimensions to see the tank fill.',
+    invalidState: 'Check the dimensions: use positive values, keep substrate below the tank height and keep the change between 0 and 100 percent.',
+    litreUnit: 'L',
+    gallonUnit: 'US gal',
+    kilogramUnit: 'kg',
+    poundUnit: 'lb',
+    lengthUnitMetric: 'cm',
+    lengthUnitImperial: 'in',
+    shapeHint: 'Use inside measurements for a more useful estimate.',
+    bowHint: 'Bow front uses a transparent two thirds segment approximation.',
+    substrateHint: 'This layer is subtracted from the gross volume.',
+    resultHint: 'Your result updates locally as you type.',
+    approximationLabel: 'Substrate share',
+    footprintLabel: 'Footprint',
+    nano: 'Nano',
+    compact: 'Compact',
+    roomy: 'Roomy',
+    showcase: 'Showcase',
+  },
+};

package/src/tool/aquariumTankVolumeWaterChangeCalculator/index.ts

@@ -0,0 +1,11 @@
+import { aquariumTankVolumeWaterChangeCalculator } from './entry';
+import type { ToolDefinition } from '../../types';
+
+export * from './entry';
+
+export const AQUARIUM_TANK_VOLUME_WATER_CHANGE_CALCULATOR_TOOL: ToolDefinition = {
+  entry: aquariumTankVolumeWaterChangeCalculator,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

package/src/tool/aquariumTankVolumeWaterChangeCalculator/logic.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_TANK_INPUT,
+  calculateTankVolume,
+  centimetresToInches,
+  inchesToCentimetres,
+  kilogramsToPounds,
+  litresToGallons,
+} from './logic';
+
+describe('aquarium tank volume logic', () => {
+  it('calculates a rectangular tank after substrate displacement', () => {
+    const result = calculateTankVolume(DEFAULT_TANK_INPUT);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.grossLitres).toBeCloseTo(63, 8);
+      expect(result.value.substrateLitres).toBeCloseTo(7.2, 8);
+      expect(result.value.netLitres).toBeCloseTo(55.8, 8);
+      expect(result.value.changeLitres).toBeCloseTo(13.95, 8);
+      expect(result.value.waterMassKg).toBeCloseTo(55.8, 8);
+    }
+  });
+
+  it('calculates a cylindrical tank with no substrate', () => {
+    const result = calculateTankVolume({
+      ...DEFAULT_TANK_INPUT,
+      shape: 'cylindrical',
+      diameterCm: 40,
+      heightCm: 50,
+      substrateDepthCm: 0,
+      changePercent: 50,
+    });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.grossLitres).toBeCloseTo(62.831853, 5);
+      expect(result.value.changeLitres).toBeCloseTo(31.415926, 5);
+    }
+  });
+
+  it('uses the bow front approximation and rejects impossible substrate', () => {
+    const bowResult = calculateTankVolume({ ...DEFAULT_TANK_INPUT, shape: 'bow', bowDepthCm: 6 });
+    expect(bowResult.ok).toBe(true);
+    const invalid = calculateTankVolume({ ...DEFAULT_TANK_INPUT, substrateDepthCm: 35 });
+    expect(invalid).toEqual({ ok: false, error: 'substrateDepth' });
+  });
+
+  it('rejects non-finite, negative, oversized and impossible values', () => {
+    expect(calculateTankVolume({ ...DEFAULT_TANK_INPUT, lengthCm: Number.NaN })).toEqual({ ok: false, error: 'dimensions' });
+    expect(calculateTankVolume({ ...DEFAULT_TANK_INPUT, widthCm: -1 })).toEqual({ ok: false, error: 'dimensions' });
+    expect(calculateTankVolume({ ...DEFAULT_TANK_INPUT, heightCm: 501 })).toEqual({ ok: false, error: 'dimensions' });
+    expect(calculateTankVolume({ ...DEFAULT_TANK_INPUT, changePercent: 101 })).toEqual({ ok: false, error: 'changePercent' });
+  });
+
+  it('converts display units using reversible factors', () => {
+    expect(inchesToCentimetres(10)).toBeCloseTo(25.4, 8);
+    expect(centimetresToInches(25.4)).toBeCloseTo(10, 8);
+    expect(litresToGallons(3.785411784)).toBeCloseTo(1, 8);
+    expect(kilogramsToPounds(1)).toBeCloseTo(2.2046226218, 8);
+  });
+});

package/src/tool/aquariumTankVolumeWaterChangeCalculator/logic.ts

@@ -0,0 +1,132 @@
+export type TankShape = 'rectangular' | 'cylindrical' | 'bow';
+export type UnitSystem = 'metric' | 'imperial';
+
+export interface TankInput {
+  shape: TankShape;
+  lengthCm: number;
+  widthCm: number;
+  heightCm: number;
+  diameterCm: number;
+  bowDepthCm: number;
+  substrateDepthCm: number;
+  changePercent: number;
+  waterDensityKgPerL: number;
+}
+
+export interface TankVolume {
+  footprintCm2: number;
+  grossLitres: number;
+  substrateLitres: number;
+  netLitres: number;
+  changeLitres: number;
+  waterMassKg: number;
+}
+
+export type CalculationResult =
+  | { ok: true; value: TankVolume }
+  | { ok: false; error: string };
+
+export const DEFAULT_TANK_INPUT: TankInput = {
+  shape: 'rectangular',
+  lengthCm: 60,
+  widthCm: 30,
+  heightCm: 35,
+  diameterCm: 40,
+  bowDepthCm: 5,
+  substrateDepthCm: 4,
+  changePercent: 25,
+  waterDensityKgPerL: 1,
+};
+
+const MAX_DIMENSION_CM = 500;
+const BOW_AREA_FACTOR = 2 / 3;
+
+function isFinitePositive(value: number): boolean {
+  return Number.isFinite(value) && value > 0;
+}
+
+function isValidDimension(value: number): boolean {
+  return isFinitePositive(value) && value <= MAX_DIMENSION_CM;
+}
+
+function calculateFootprint(input: TankInput): number {
+  if (input.shape === 'cylindrical') return Math.PI * (input.diameterCm / 2) ** 2;
+  const base = input.lengthCm * input.widthCm;
+  if (input.shape === 'bow') return base + BOW_AREA_FACTOR * input.lengthCm * input.bowDepthCm;
+  return base;
+}
+
+function validateDimensions(input: TankInput): string | null {
+  const dimensions = input.shape === 'cylindrical'
+    ? [input.diameterCm, input.heightCm]
+    : [input.lengthCm, input.widthCm, input.heightCm];
+  if (dimensions.some((value) => isValidDimension(value) === false)) return 'dimensions';
+  return null;
+}
+
+function validateBow(input: TankInput): string | null {
+  if (input.shape !== 'bow') return null;
+  if (Number.isFinite(input.bowDepthCm) === false || input.bowDepthCm < 0 || input.bowDepthCm > input.widthCm) return 'bowDepth';
+  return null;
+}
+
+function validateSubstrate(input: TankInput): string | null {
+  if (Number.isFinite(input.substrateDepthCm) === false || input.substrateDepthCm < 0 || input.substrateDepthCm >= input.heightCm) return 'substrateDepth';
+  return null;
+}
+
+function validateChange(input: TankInput): string | null {
+  if (Number.isFinite(input.changePercent) === false || input.changePercent < 0 || input.changePercent > 100) return 'changePercent';
+  return null;
+}
+
+function validateDensity(input: TankInput): string | null {
+  if (Number.isFinite(input.waterDensityKgPerL) === false || input.waterDensityKgPerL <= 0) return 'density';
+  return null;
+}
+
+function validateInput(input: TankInput): string | null {
+  const validators = [validateDimensions, validateBow, validateSubstrate, validateChange, validateDensity];
+  for (const validator of validators) {
+    const error = validator(input);
+    if (error !== null) return error;
+  }
+  return null;
+}
+
+export function calculateTankVolume(input: TankInput): CalculationResult {
+  const error = validateInput(input);
+  if (error !== null) return { ok: false, error };
+  const footprintCm2 = calculateFootprint(input);
+  const grossLitres = (footprintCm2 * input.heightCm) / 1000;
+  const substrateLitres = (footprintCm2 * input.substrateDepthCm) / 1000;
+  const netLitres = grossLitres - substrateLitres;
+  const changeLitres = netLitres * input.changePercent / 100;
+  return {
+    ok: true,
+    value: {
+      footprintCm2,
+      grossLitres,
+      substrateLitres,
+      netLitres,
+      changeLitres,
+      waterMassKg: netLitres * input.waterDensityKgPerL,
+    },
+  };
+}
+
+export function litresToGallons(litres: number): number {
+  return litres / 3.785411784;
+}
+
+export function kilogramsToPounds(kilograms: number): number {
+  return kilograms * 2.2046226218;
+}
+
+export function centimetresToInches(centimetres: number): number {
+  return centimetres / 2.54;
+}
+
+export function inchesToCentimetres(inches: number): number {
+  return inches * 2.54;
+}

package/src/tool/aquariumTankVolumeWaterChangeCalculator/seo.astro

@@ -0,0 +1,13 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { aquariumTankVolumeWaterChangeCalculator } from './entry';
+import type { KnownLocale } from '../../types';
+
+interface Props { locale?: KnownLocale; }
+
+const { locale = 'en' } = Astro.props;
+const loader = aquariumTankVolumeWaterChangeCalculator.i18n[locale] ?? aquariumTankVolumeWaterChangeCalculator.i18n.en;
+const content = loader === undefined ? undefined : await loader();
+---
+
+{content && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/aquariumTankVolumeWaterChangeCalculator/storage.ts

@@ -0,0 +1,30 @@
+import { DEFAULT_TANK_INPUT, type TankInput, type UnitSystem } from './logic';
+
+const STORAGE_KEY = 'jjlmoya-utils-aquarium:tank-volume-water-change';
+
+export interface SavedAquariumState {
+  unit: UnitSystem;
+  input: TankInput;
+}
+
+export function loadAquariumState(): SavedAquariumState | null {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (raw === null) return null;
+    const parsed = JSON.parse(raw) as SavedAquariumState;
+    if (parsed.input === undefined || (parsed.unit !== 'metric' && parsed.unit !== 'imperial')) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function saveAquariumState(state: SavedAquariumState): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch {}
+}
+
+export function defaultAquariumState(): SavedAquariumState {
+  return { unit: 'metric', input: { ...DEFAULT_TANK_INPUT } };
+}

package/src/tool/aquariumTankVolumeWaterChangeCalculator/ui.ts

@@ -0,0 +1,41 @@
+export interface AquariumTankVolumeWaterChangeCalculatorUI {
+  [key: string]: string;
+  toolTitle: string;
+  toolSubtitle: string;
+  dimensionsTitle: string;
+  shapeLabel: string;
+  rectangularShape: string;
+  cylindricalShape: string;
+  bowShape: string;
+  lengthLabel: string;
+  widthLabel: string;
+  heightLabel: string;
+  diameterLabel: string;
+  bowDepthLabel: string;
+  substrateLabel: string;
+  changeLabel: string;
+  unitLabel: string;
+  metricLabel: string;
+  imperialLabel: string;
+  calculateLabel: string;
+  resetLabel: string;
+  grossVolumeLabel: string;
+  substrateVolumeLabel: string;
+  netVolumeLabel: string;
+  changeVolumeLabel: string;
+  waterWeightLabel: string;
+  emptyState: string;
+  invalidState: string;
+  litreUnit: string;
+  gallonUnit: string;
+  kilogramUnit: string;
+  poundUnit: string;
+  lengthUnitMetric: string;
+  lengthUnitImperial: string;
+  shapeHint: string;
+  bowHint: string;
+  substrateHint: string;
+  resultHint: string;
+  approximationLabel: string;
+  footprintLabel: string;
+}

package/src/tools.ts

@@ -0,0 +1,9 @@
+export { ALL_ENTRIES } from './entries';
+import { aquariumTankVolumeWaterChangeCalculator } from './tool/aquariumTankVolumeWaterChangeCalculator/entry';
+
+export const ALL_TOOLS = [{
+  entry: aquariumTankVolumeWaterChangeCalculator,
+  Component: () => import('./tool/aquariumTankVolumeWaterChangeCalculator/component.astro'),
+  SEOComponent: () => import('./tool/aquariumTankVolumeWaterChangeCalculator/seo.astro'),
+  BibliographyComponent: () => import('./tool/aquariumTankVolumeWaterChangeCalculator/bibliography.astro'),
+}];

package/src/types.ts

@@ -0,0 +1,54 @@
+import type { SEOSection } from '@jjlmoya/utils-shared';
+import type { WithContext, Thing } from 'schema-dts';
+
+export type { SEOSection };
+
+export type KnownLocale =
+  | 'ar' | 'da' | 'de' | 'en' | 'es' | 'fi'
+  | 'fr' | 'id' | 'it' | 'ja' | 'ko' | 'nb' | 'nl'
+  | 'pl' | 'pt' | 'ru' | 'sv' | 'tr' | 'zh';
+
+export interface FAQItem { question: string; answer: string; }
+export interface BibliographyEntry { name: string; url: string; }
+export interface HowToStep { name: string; text: string; }
+
+export interface ToolLocaleContent<TUI extends Record<string, string> = Record<string, string>> {
+  slug: string;
+  title: string;
+  description: string;
+  ui: TUI;
+  seo: SEOSection[];
+  faq: FAQItem[];
+  bibliography: BibliographyEntry[];
+  howTo: HowToStep[];
+  schemas: WithContext<Thing>[];
+}
+
+export interface CategoryLocaleContent {
+  slug: string;
+  title: string;
+  description: string;
+  seo: SEOSection[];
+}
+
+export type LocaleLoader<T> = () => Promise<T>;
+export type LocaleMap<T> = Partial<Record<KnownLocale, LocaleLoader<T>>>;
+
+export interface AquariumToolEntry<TUI extends Record<string, string> = Record<string, string>> {
+  id: string;
+  icons: { bg: string; fg: string; };
+  i18n: LocaleMap<ToolLocaleContent<TUI>>;
+}
+
+export interface AquariumCategoryEntry {
+  icon: string;
+  tools: AquariumToolEntry<Record<string, string>>[];
+  i18n: LocaleMap<CategoryLocaleContent>;
+}
+
+export interface ToolDefinition {
+  entry: AquariumToolEntry;
+  Component: unknown;
+  SEOComponent: unknown;
+  BibliographyComponent: unknown;
+}