feat: add bundle format versioning

Author: gkurt

.changeset/bundle-version.md

@@ -0,0 +1,7 @@
+---
+"tegaki": minor
+---
+
+Add bundle format versioning. Generated bundles now include a `version` field (currently `0`) so the engine can detect incompatible bundles. The engine checks the version when a bundle is registered or resolved and logs a console warning (once per bundle) if the version is missing or unsupported.
+
+New exports: `BUNDLE_VERSION`, `COMPATIBLE_BUNDLE_VERSIONS`. New optional `TegakiBundle` field: `version`. Existing bundles without a version field trigger the warning but continue to work.

packages/generator/src/commands/generate.ts

@@ -1,5 +1,5 @@
 import opentype from 'opentype.js';
-import type { BBox, FontOutput, LineCap, Point, Stroke } from 'tegaki';
+import { type BBox, BUNDLE_VERSION, type FontOutput, type LineCap, type Point, type Stroke } from 'tegaki';
 import * as z from 'zod/v4';
 import {
   charsHash,
@@ -499,6 +499,7 @@ function generateGlyphsModule(
   if (hasFull) fontFaceRules.push(`@font-face { font-family: '${esc(fullFamily)}'; src: url(\${fullFontUrl}); }`);
 
   const props = [
+    `  version: ${BUNDLE_VERSION},`,
     `  family: '${esc(fontFamily)}',`,
     ...(hasFull ? [`  fullFamily: '${esc(fullFamily)}',`] : []),
     `  lineCap: '${lineCap}',`,

packages/renderer/fonts/caveat/bundle.ts

@@ -4,6 +4,7 @@ import fullFontUrl from './caveat.ttf' with { type: 'url' };
 import glyphData from './glyphData.json' with { type: 'json' };
 
 const bundle = {
+  version: 0,
   family: 'Caveat Tegaki 3dc76002',
   fullFamily: 'Caveat',
   lineCap: 'round',

packages/renderer/fonts/italianno/bundle.ts

@@ -4,6 +4,7 @@ import fullFontUrl from './italianno.ttf' with { type: 'url' };
 import glyphData from './glyphData.json' with { type: 'json' };
 
 const bundle = {
+  version: 0,
   family: 'Italianno Tegaki 3dc76002',
   fullFamily: 'Italianno',
   lineCap: 'round',

packages/renderer/fonts/parisienne/bundle.ts

@@ -4,6 +4,7 @@ import fullFontUrl from './parisienne.ttf' with { type: 'url' };
 import glyphData from './glyphData.json' with { type: 'json' };
 
 const bundle = {
+  version: 0,
   family: 'Parisienne Tegaki 3dc76002',
   fullFamily: 'Parisienne',
   lineCap: 'round',

packages/renderer/fonts/tangerine/bundle.ts

@@ -4,6 +4,7 @@ import fullFontUrl from './tangerine.ttf' with { type: 'url' };
 import glyphData from './glyphData.json' with { type: 'json' };
 
 const bundle = {
+  version: 0,
   family: 'Tangerine Tegaki 3dc76002',
   fullFamily: 'Tangerine',
   lineCap: 'round',

packages/renderer/src/core/bundle-registry.ts

@@ -1,9 +1,23 @@
-import type { TegakiBundle } from '../types.ts';
+import { COMPATIBLE_BUNDLE_VERSIONS, type TegakiBundle } from '../types.ts';
 
 const bundles = new Map<string, TegakiBundle>();
+const warnedBundles = new Set<TegakiBundle>();
+
+function checkBundleVersion(bundle: TegakiBundle): void {
+  if (warnedBundles.has(bundle)) return;
+  if (bundle.version == null || !COMPATIBLE_BUNDLE_VERSIONS.has(bundle.version)) {
+    warnedBundles.add(bundle);
+    console.warn(
+      `[tegaki] Bundle "${bundle.family}" has version ${bundle.version ?? 'undefined'}, ` +
+        `but this engine supports versions [${[...COMPATIBLE_BUNDLE_VERSIONS].join(', ')}]. ` +
+        'The bundle may not render correctly. Regenerate it with a compatible version of tegaki-generator.',
+    );
+  }
+}
 
 /** Register a font bundle so it can be referenced by family name. */
 export function registerBundle(bundle: TegakiBundle): void {
+  checkBundleVersion(bundle);
   bundles.set(bundle.family, bundle);
 }
 
@@ -18,5 +32,6 @@ export function resolveBundle(font: TegakiBundle | string | undefined): TegakiBu
     if (!bundle) throw new Error(`TegakiEngine: no bundle registered for "${font}". Call TegakiEngine.registerBundle() first.`);
     return bundle;
   }
+  if (font) checkBundleVersion(font);
   return font;
 }

packages/renderer/src/core/createBundle.ts

@@ -1,4 +1,4 @@
-import type { LineCap, TegakiBundle, TegakiGlyphData } from '../types.ts';
+import { BUNDLE_VERSION, type LineCap, type TegakiBundle, type TegakiGlyphData } from '../types.ts';
 
 /**
  * Creates a {@link TegakiBundle} from its constituent parts.
@@ -41,6 +41,7 @@ export function createBundle({
     rules.push(`@font-face { font-family: '${fullFamily}'; src: url(${fullFontUrl}); }`);
   }
   return {
+    version: BUNDLE_VERSION,
     family,
     fullFamily,
     lineCap,

packages/renderer/src/core/index.ts

@@ -5,6 +5,7 @@ export { computeTextLayout, type TextLayout } from '../lib/textLayout.ts';
 export { computeTimeline, type Timeline, type TimelineConfig, type TimelineEntry } from '../lib/timeline.ts';
 export type * from '../types.ts';
 export type { TegakiEffectConfigs, TegakiEffects } from '../types.ts';
+export { BUNDLE_VERSION, COMPATIBLE_BUNDLE_VERSIONS } from '../types.ts';
 export { getBundle, registerBundle, resolveBundle } from './bundle-registry.ts';
 export { createBundle } from './createBundle.ts';
 export { TegakiEngine } from './engine.ts';

packages/renderer/src/types.ts

@@ -1,3 +1,16 @@
+/**
+ * Current bundle format version. Incremented when the bundle format changes
+ * in a way that older engines cannot consume.
+ */
+export const BUNDLE_VERSION = 0;
+
+/**
+ * Set of bundle versions that this engine can consume. The engine logs a
+ * console warning (once per bundle) when it encounters a version outside
+ * this set.
+ */
+export const COMPATIBLE_BUNDLE_VERSIONS: ReadonlySet<number> = new Set([BUNDLE_VERSION]);
+
 export type LineCap = 'round' | 'butt' | 'square';
 
 export interface Point {
@@ -108,6 +121,8 @@ export type TegakiEffects<T> = {
 };
 
 export interface TegakiBundle {
+  /** Bundle format version. Used by the engine to warn about incompatible bundles. */
+  version?: number;
   family: string;
   /**
    * Original font family name, used as a CSS fallback for characters not in