v0.5.5

Overview

Release 0.5.5 expands the HeroQuest Card Creator with a full light/dark/system theming system, a substantially enhanced export pipeline (bleed, crop/cut marks, unified export options UI), export-only watermarking and PNG metadata tagging, improved copyright color behavior (manual override + stabilized auto-contrast), broader i18n support with UX improvements, analytics instrumentation for both web and file:// usage, and a migration to the updated 756×1056 card canvas. This document summarizes both user-visible changes and internal technical changes for downstream documentation.

Baseline: origin/release/0.5.4 → Target: release/0.5.5

Breaking / Behavioral Changes & Migrations

• Card canvas sizing updated: card dimensions change to 756×1056 (from 750×1050). See src/config/card-canvas.ts. This affects all rendering and export sizing.
• IndexedDB migration for card image offsets: existing cards with schemaVersion: 1 are migrated to schemaVersion: 2 in src/lib/hqcc-db.ts. imageOffsetX/Y are scaled by the new SCALE_X/SCALE_Y factors.
• Theme preference storage: hqcc.theme now controls UI theme preference (dark | light | system). Defaults to dark.
• Export behavior changes: export pipeline supports bleed/crop/cut marks and export-only rounded corner control; export prompt changes do not persist to storage, while settings panel changes do.

Feature Details by Subsystem

Theme System & Appearance UX

User-facing behavior

• New Light, Dark, and System theme preferences, with system mode honoring prefers-color-scheme.
• Theme is applied via document.documentElement.dataset.theme and document.documentElement.style.colorScheme.
• Theme switching is available in Settings → Appearance and directly in the header burger menu (segmented icon toggle).

Key implementation points

• Theme context: src/components/Providers/ThemeProvider.tsx.
  • Storage key: hqcc.theme.
  • ThemePreference: "dark" | "light" | "system".
  • resolvedTheme computed via matchMedia for system mode.
• Pre-hydration theme script injected in src/app/layout.tsx to prevent flash.
• Appearance settings UI: src/components/Modals/SettingsModal/AppearanceSettingsPanel.tsx.
• Header menu segmented toggle: src/components/Layout/MainHeader/HeaderMenu.tsx with lucide icons (Sun, Moon, Monitor), aria-label and aria-pressed support.
• Extensive tokenization and light-theme overrides in src/variables.css and global styling updates in src/app/globals.css and src/app/page.module.css.
• Inspector/layout polish: label icon alignment, spacing adjustments, modal close button styling, and card grid title truncation.

Export Pipeline: Bleed, Crop/Cut Marks, Unified Options

User-facing behavior

• Export-only bleed support (0–36px) and optional crop/cut marks for print workflows.
• Export prompt vs. Settings panel behavior:
  • Settings persist to localStorage and backups.
  • Export prompt uses settings as defaults, does not persist changes.
• Rounded-corner export remains default ON, but is disabled when bleed/crop marks require straight edges.

Key implementation points

• Shared options UI: src/components/Export/ExportOptionsForm.tsx used by Settings panel and export prompt.
• Export prompt modal: src/components/Modals/ExportBleedPrompt/index.tsx.
• Export settings state: src/components/Providers/ExportSettingsContext.tsx.
• LocalStorage keys (all under hqcc.exportPng.*):
  • bleedEnabled, bleedPx, askBeforeExport,
  • cropMarksEnabled, cropMarksColor, cropMarksStyle,
  • cutMarksEnabled, cutMarksColor,
  • roundedCorners.
• Export pipeline additions:
  • src/lib/bleed-export.ts: bleed composition, crop mark and cut mark drawing, and clip adjustments.
  • renderBleedCanvas integrated into src/components/Cards/CardPreview/index.tsx.
  • Background fit switches to xMidYMid slice for bleed/marks.
  • “Half-source stretch” rule for bleed bands (sourcePx = floor(bleedPx / 2)).
• API surface changes:
  • CardPreviewHandle.exportAsPng accepts options for bleed, crop/cut marks, rounded corners.
  • CardPreviewHandle.renderToPngBlob accepts the same options.
  • src/lib/export-face-ids.ts and src/lib/export-cards.ts forward export options for bulk export.

Watermark + PNG Metadata (Export-Only)

User-facing behavior

• Exports include a subtle, adaptive-contrast dotted watermark (not shown in preview).
• Exported PNGs include metadata: tEXt chunk with Made using and app version.

Key implementation points

• Watermark logic: src/lib/watermark.ts.
  • 5 dots, 1px apart, alpha 0.25.
  • Adaptive color from local luminance sample.
• PNG metadata insertion: src/lib/png-metadata.ts.
  • Inserts tEXt chunk before IEND.
  • Keyword: Made using.
  • Value: HeroQuest Card Creator <APP_VERSION>.
• Controlled by flag: ENABLE_WATERMARK in src/config/flags.ts.

Copyright Auto-Color + Manual Override

User-facing behavior

• Manual copyright color override is supported and reflected in preview/export.
• Auto-contrast sampling is stabilized and avoids flicker/feedback.
• Auto-contrast prefers brown on mid-light parchment backgrounds while still switching to white on dark backgrounds.

Key implementation points

• New data field: copyrightColor?: string.
  • Added to src/types/card-data.ts, src/types/cards-db.ts.
  • Stored via src/lib/card-record-mapper.ts.
• Inspector updates: src/components/Cards/CardInspector/CopyrightField.tsx (manual color picker + Auto reset).
• Auto-contrast sampling:
  • Excludes the rendered copyright layer using data-layer-type="copyright" in src/components/BlueprintRenderer/index.tsx.
  • Samples background image directly when available; falls back to SVG sampling.
  • Uses text measurement via measureCardTextMaxLineWidth in src/components/Cards/CardParts/CardTextBlock.tsx.
• New default copyright color constant: DEFAULT_COPYRIGHT_COLOR in src/config/colors.ts.

I18n Expansion & Language Menu UX

User-facing behavior

• New supported languages: el, hu, pl, cs, sv, fi, pt-BR (plus existing).
• Language menu shows native-language labels with flags and a two-column grid layout.
• Current language is excluded from the options list; detected language is separated at the bottom.

Key implementation points

• Per-language message bundles moved into src/i18n/messages/*.ts.
• supportedLanguages, languageLabels, and templateNameLabels are centralized in src/i18n/messages.ts.
• Detection and storage precedence in src/i18n/getInitialLanguage.ts:
  • Stored language overrides detection.
  • Exact locale match, then primary tag match, fallback to en.
• Language menu ordering and layout:
  • Sorting by native label text (flag stripped).
  • Two-column grid layout in src/app/page.module.css.
  • Detected language separated by margin class in src/components/LanguageMenu/LanguageMenuPopover.tsx.
• Tooling: npm run i18n:audit via scripts/i18n-audit.cjs and bin/i18n-audit.js.

Analytics & Telemetry

User-facing behavior

• GA4 is used when available; file:// and non-gtag environments use a pixel fallback.

Key implementation points

• Analytics provider: src/components/Providers/AnalyticsProvider.tsx.
  • Tracks page_view events for core routes and modal navigation.
  • Pixel fallback uses NEXT_PUBLIC_PIXEL_URL and optional NEXT_PUBLIC_PIXEL_KEY.
  • Adds metadata: app version, language, timezone, screen/viewport, UA, and optional ip_override via ipify.
• GA4 integration moved to NEXT_PUBLIC_GA_ID (via @next/third-parties/google in src/app/layout.tsx).
• README updated with file:// analytics guidance.

Card Canvas Sizing & Rendering Adjustments

User-facing behavior

• Card renders and exports now use 756×1056 dimensions to match exact poker ratio.

Key implementation points

• src/config/card-canvas.ts defines new dimensions and scaling helpers (sx, sy, savg).
• src/components/Cards/CardPreview/consts.ts now derives from card-canvas scaling.
• Blueprints, stats blocks, ribbons, and borders adjusted to match updated sizing.

Storage / Config / Flags

LocalStorage keys

• Theme: hqcc.theme (dark | light | system).
• Export settings under hqcc.exportPng.*:
  • bleedEnabled, bleedPx, askBeforeExport,
  • cropMarksEnabled, cropMarksColor, cropMarksStyle,
  • cutMarksEnabled, cutMarksColor,
  • roundedCorners.

Backup import/export

• Export settings are persisted through backup (src/lib/backup.ts).

Flags (src/config/flags.ts)

• ENABLE_WATERMARK: toggles export-only watermark.
• USE_ROUNDED_CARD_CLIP: toggles clip path rounding (useful for bleed testing).

Environment variables

• NEXT_PUBLIC_GA_ID (GA4 Measurement ID).
• NEXT_PUBLIC_PIXEL_URL, NEXT_PUBLIC_PIXEL_KEY, NEXT_PUBLIC_PIXEL_DEBUG for pixel fallback.

API / Type Surface Changes

• CardPreviewHandle.exportAsPng(options) now accepts:
  • bleedPx, cropMarks, cutMarks, roundedCorners.
• CardPreviewHandle.renderToPngBlob(options) now accepts:
  • bleedPx, cropMarks, cutMarks, roundedCorners.
• exportFaceIdsToZip and runBulkExport now forward the same export options.
• CardRecord.schemaVersion expands to 1 | 2.
• copyrightColor?: string added to card data and DB record types.

Assets & Visual Adjustments

• Asset updates to support bleed and card sizing adjustments:
  • Updated background textures, bordered masks, and card parts.
  • Added/replaced background variants (e.g., hero-back-back.png, parchment copy.png).
• Layout tweaks to hero/monster stats blocks, ribbons, and borders aligned to new sizing.

Tests & Tooling

• New test coverage for:
  • Watermark behavior and placement.
  • PNG metadata insertion.
  • I18n ordering and detection.
  • Hex color parsing/formatting utilities.
• npm run i18n:audit script added (with CLI wrapper).

QA / Validation Checklist

• Theme
  • Toggle light/dark/system in Settings and header menu.
  • System theme follows OS changes.
  • Light theme readability across settings, modals, inspector.
• Export
  • Bleed adds padded output size; crop/cut marks only when bleed enabled.
  • Rounded corners export remains available when bleed is off.
  • Export prompt changes do not persist.
• Watermark + metadata
  • Watermark appears on exports only.
  • PNG contains Made using metadata with version.
• Copyright
  • Manual color overrides render in preview/export.
  • Auto-contrast is stable (no flicker) and selects brown on mid-light parchment.
• I18n
  • Language menu is two-column, native labels with flags.
  • Current language removed from options; detected language separated at bottom.
  • npm run i18n:audit reports missing = 0.