capture-flow 0.0.0-stage → 0.1.0

package/vendor/wajha/model/instantiate.ts

@@ -0,0 +1,280 @@
+/**
+ * Template <-> project conversion. Owned by the model/store work package.
+ *
+ * Templates carry one layout per aspect class, each authored on a reference
+ * canvas: tall = the iPhone design canvas, tablet = iPad, wide = Mac. A new
+ * project stores only what the editor cannot derive (ARCHITECTURE 6.1): the
+ * primary family's layout, plus the template's own layout for any other
+ * aspect class it designs. Every other family follows the primary family
+ * through resolveLayout until the user edits it.
+ */
+import { adaptLayout } from './adapt';
+import { FAMILIES } from './catalog';
+import { deepClone } from './clone';
+import { DEFAULT_FAMILY, DEFAULT_LANGUAGE, DEFAULT_PROJECT_NAME, defaultExportSettings, newSlide } from './defaults';
+import { newId } from './ids';
+import { resolveLayout } from './resolve';
+import { LIMITS, cleanName, cleanText, isTemplateId, uniqueFamilies, uniqueLanguages } from './rules';
+import type {
+  AspectClass,
+  AssetInfo,
+  Background,
+  Fill,
+  FamilyId,
+  LangCode,
+  Project,
+  Slide,
+  SlideLayout,
+  Template,
+  TemplateCategory,
+  TemplateSlide,
+  Theme,
+} from './types';
+
+export interface NewProjectOptions {
+  name: string;
+  families: FamilyId[];
+  languages: LangCode[];
+}
+
+/** The family whose design canvas a template's class layout is authored on. */
+export const REFERENCE_FAMILY: Readonly<Record<AspectClass, FamilyId>> = { tall: 'iphone', tablet: 'ipad', wide: 'mac' };
+
+const ASPECT_CLASSES: readonly AspectClass[] = ['tall', 'tablet', 'wide'];
+
+export const TEMPLATE_CATEGORIES: readonly TemplateCategory[] = ['minimal', 'bold', 'gradient', 'dark', 'playful', 'panorama', 'elegant'];
+
+/** Copy of `layout` with element ids mapped through `ids` (one fresh id per old id, unique within the layout). */
+function remapIds(layout: SlideLayout, ids: Map<string, string>): SlideLayout {
+  const used = new Set<string>();
+  const elements = (Array.isArray(layout.elements) ? layout.elements : []).map((el) => {
+    const copy = deepClone(el);
+    let id = ids.get(el.id);
+    if (!id || used.has(id)) {
+      id = newId('e');
+      if (!ids.has(el.id)) ids.set(el.id, id);
+    }
+    used.add(id);
+    copy.id = id;
+    return copy;
+  });
+  return { background: layout.background ? deepClone(layout.background) : null, elements };
+}
+
+/** The script subtag of a language code ("hans" in "zh-Hans"), lower case, or undefined. */
+const scriptOf = (code: LangCode) => code.split('-').find((part, i) => i > 0 && /^[A-Za-z]{4}$/.test(part))?.toLowerCase();
+
+/**
+ * The template's own copy for `lang`: the same language, else a regional
+ * variant of it ("ar-SA" <- "ar" or "ar-EG"), but never one in another
+ * script ("zh-Hant" does not take "zh-Hans"). Undefined when it has none.
+ */
+export function sameLanguageTexts(texts: Record<LangCode, Record<string, string>>, lang: LangCode): Record<string, string> | undefined {
+  const own = (k: string) => (Object.prototype.hasOwnProperty.call(texts, k) ? texts[k] : undefined);
+  const exact = own(lang);
+  if (exact) return exact;
+  const primary = lang.split('-')[0];
+  const bare = own(primary);
+  if (bare) return bare;
+  const script = scriptOf(lang);
+  const variant = Object.keys(texts).find((k) => {
+    if (k.split('-')[0] !== primary) return false;
+    const other = scriptOf(k);
+    return !script || !other || script === other;
+  });
+  return variant ? texts[variant] : undefined;
+}
+
+/**
+ * Sample copy for `lang`: the template's own copy for it (see
+ * sameLanguageTexts), else "en-US", else any English, else anything.
+ */
+export function pickTexts(texts: Record<LangCode, Record<string, string>>, lang: LangCode): Record<string, string> {
+  const same = sameLanguageTexts(texts, lang);
+  if (same) return same;
+  const keys = Object.keys(texts);
+  const en = (Object.prototype.hasOwnProperty.call(texts, DEFAULT_LANGUAGE) ? texts[DEFAULT_LANGUAGE] : undefined) ?? keys.filter((k) => k.split('-')[0] === 'en').map((k) => texts[k])[0];
+  if (en) return en;
+  return keys.length ? texts[keys[0]] : {};
+}
+
+/** Layout for `family` from a template slide whose class layouts already carry the project's element ids. */
+function layoutForFamily(classLayouts: Partial<Record<AspectClass, SlideLayout>>, family: FamilyId): SlideLayout {
+  const info = FAMILIES[family];
+  const ref = REFERENCE_FAMILY[info.aspectClass];
+  const own = classLayouts[info.aspectClass];
+  if (own) return family === ref ? deepClone(own) : adaptLayout(own, FAMILIES[ref].design, info.design, family);
+  const tall = classLayouts.tall;
+  if (!tall) return { background: null, elements: [] };
+  return adaptLayout(tall, FAMILIES.iphone.design, info.design, family);
+}
+
+function slideFromTemplate(ts: TemplateSlide, families: FamilyId[], languages: LangCode[]): Slide {
+  // One id map per slide: the same template element gets the same new id in every class layout.
+  const ids = new Map<string, string>();
+  const classLayouts: Partial<Record<AspectClass, SlideLayout>> = {};
+  for (const cls of ASPECT_CLASSES) {
+    const l = ts.layouts?.[cls];
+    if (l) classLayouts[cls] = remapIds(l, ids);
+  }
+  if (!classLayouts.tall) {
+    // Validated templates always have one; derive it rather than fail on hand-made data.
+    const cls = ASPECT_CLASSES.find((k) => classLayouts[k]);
+    if (cls) classLayouts.tall = adaptLayout(classLayouts[cls] as SlideLayout, FAMILIES[REFERENCE_FAMILY[cls]].design, FAMILIES.iphone.design, 'iphone');
+  }
+  // Only what cannot be derived: other families follow the primary one until edited.
+  const primary = families[0];
+  const primaryClass = FAMILIES[primary].aspectClass;
+  const layouts: Slide['layouts'] = {};
+  for (const f of families) {
+    const cls = FAMILIES[f].aspectClass;
+    if (f === primary || (cls !== primaryClass && ts.layouts?.[cls])) layouts[f] = layoutForFamily(classLayouts, f);
+  }
+  // The base language always shows sample copy. Other languages get the
+  // template's translation, or nothing: they fall back to the base text and
+  // count as untranslated instead of shipping another language's samples.
+  const texts: Slide['texts'] = {};
+  const source = ts.texts ?? {};
+  languages.forEach((lang, i) => {
+    const copy = i === 0 ? pickTexts(source, lang) : sameLanguageTexts(source, lang);
+    if (copy) texts[lang] = deepClone(copy);
+  });
+  return { id: newId('s'), texts, shots: {}, layouts };
+}
+
+/** New project from a template: copies theme, slides, sample texts and assets. */
+export function projectFromTemplate(template: Template, opts: NewProjectOptions): Project {
+  const families = uniqueFamilies(opts?.families);
+  if (!families.length) families.push(DEFAULT_FAMILY);
+  const languages = uniqueLanguages(opts?.languages);
+  if (!languages.length) languages.push(DEFAULT_LANGUAGE);
+  const theme = deepClone(template.theme);
+  const slides = (Array.isArray(template.slides) ? template.slides : [])
+    .slice(0, LIMITS.templateSlides)
+    .map((ts) => slideFromTemplate(ts, families, languages));
+  if (!slides.length) slides.push(newSlide(families, theme, languages));
+  const name = (typeof opts?.name === 'string' ? cleanName(opts.name) : '') || cleanName(template.name ?? '') || DEFAULT_PROJECT_NAME;
+  const now = Date.now();
+  return {
+    format: 'wajha.project',
+    version: 1,
+    id: newId(),
+    name,
+    createdAt: now,
+    updatedAt: now,
+    templateId: isTemplateId(template.id) ? template.id : null,
+    theme,
+    families,
+    languages,
+    slides,
+    assets: deepClone(template.assets ?? {}),
+    export: defaultExportSettings(),
+  };
+}
+
+export interface TemplateMeta {
+  id: string;
+  name: string;
+  author: string;
+  description: string;
+  category: TemplateCategory;
+  tags: string[];
+}
+
+/** kebab-case id from `id`, else from `name`, else a fresh "t..." id. */
+export function templateIdFrom(id: string, name: string): string {
+  if (isTemplateId(id)) return id;
+  for (const raw of [id, name]) {
+    if (typeof raw !== 'string') continue;
+    const slug = raw
+      .normalize('NFKD')
+      // Accents become separate combining marks under NFKD; drop them so "é" slugs to "e".
+      .replace(/[\u0300-\u036f]/g, '')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, LIMITS.id)
+      .replace(/-+$/g, '');
+    if (isTemplateId(slug)) return slug;
+  }
+  return newId('t');
+}
+
+function fillAssets(fill: Fill | null | undefined, into: Set<string>): void {
+  if (fill && fill.type === 'image') into.add(fill.assetId);
+}
+
+function backgroundAssets(bg: Background | null | undefined, into: Set<string>): void {
+  if (bg) fillAssets(bg.fill, into);
+}
+
+/** Asset ids a design (theme + layouts) references; screenshots are not design. */
+export function designAssets(theme: Theme, layouts: Iterable<SlideLayout>): Set<string> {
+  const ids = new Set<string>();
+  backgroundAssets(theme.background, ids);
+  for (const l of layouts) {
+    backgroundAssets(l.background, ids);
+    for (const el of l.elements) {
+      if (el.kind === 'image') ids.add(el.assetId);
+      else if (el.kind === 'shape') fillAssets(el.fill, ids);
+    }
+  }
+  return ids;
+}
+
+function templateSlide(project: Project, slide: Slide): TemplateSlide {
+  const base = project.languages[0] ?? DEFAULT_LANGUAGE;
+  const sample = deepClone(slide.texts[base] ?? {});
+  const texts: TemplateSlide['texts'] = { [DEFAULT_LANGUAGE]: sample };
+  if (base !== DEFAULT_LANGUAGE) texts[base] = deepClone(sample);
+
+  const byClass: Partial<Record<AspectClass, SlideLayout>> = {};
+  for (const f of project.families) {
+    const info = FAMILIES[f];
+    if (!info || byClass[info.aspectClass]) continue;
+    const ref = REFERENCE_FAMILY[info.aspectClass];
+    const layout = resolveLayout(project, slide, f);
+    // Store it as authored on the reference canvas so instantiation reads it the same way.
+    byClass[info.aspectClass] = f === ref ? deepClone(layout) : adaptLayout(layout, info.design, FAMILIES[ref].design, ref);
+  }
+  if (!byClass.tall) {
+    const cls = ASPECT_CLASSES.find((k) => byClass[k]);
+    const from = cls ? (byClass[cls] as SlideLayout) : resolveLayout(project, slide, DEFAULT_FAMILY);
+    byClass.tall = cls ? adaptLayout(from, FAMILIES[REFERENCE_FAMILY[cls]].design, FAMILIES.iphone.design, 'iphone') : deepClone(from);
+  }
+  const layouts: TemplateSlide['layouts'] = { tall: byClass.tall };
+  if (byClass.tablet) layouts.tablet = byClass.tablet;
+  if (byClass.wide) layouts.wide = byClass.wide;
+  return { texts, layouts };
+}
+
+/** "Save as template": keeps design, drops screenshots, keeps base-language texts as samples. */
+export function templateFromProject(project: Project, meta: TemplateMeta): Template {
+  const slides = project.slides.slice(0, LIMITS.templateSlides).map((s) => templateSlide(project, s));
+  const theme = deepClone(project.theme);
+  const used = designAssets(theme, slides.flatMap((s) => [s.layouts.tall, s.layouts.tablet, s.layouts.wide].filter((l): l is SlideLayout => !!l)));
+  const assets: Record<string, AssetInfo> = {};
+  for (const id of used) {
+    const info = project.assets[id];
+    if (info) assets[id] = deepClone(info);
+  }
+  const tags: string[] = [];
+  for (const t of Array.isArray(meta?.tags) ? meta.tags : []) {
+    const tag = typeof t === 'string' ? cleanName(t, LIMITS.tag).toLowerCase() : '';
+    if (tag && !tags.includes(tag) && tags.length < LIMITS.tags) tags.push(tag);
+  }
+  const name = (typeof meta?.name === 'string' ? cleanName(meta.name) : '') || project.name || DEFAULT_PROJECT_NAME;
+  return {
+    format: 'wajha.template',
+    version: 1,
+    id: templateIdFrom(meta?.id, name),
+    name,
+    author: typeof meta?.author === 'string' ? cleanName(meta.author) : '',
+    description: typeof meta?.description === 'string' ? cleanText(meta.description) : '',
+    category: TEMPLATE_CATEGORIES.includes(meta?.category) ? meta.category : 'minimal',
+    tags,
+    theme,
+    slides,
+    assets,
+  };
+}

package/vendor/wajha/model/mirror.ts

@@ -0,0 +1,43 @@
+/**
+ * Right-to-left mirroring. An Arabic or Hebrew store listing reads from the
+ * right, so a slide whose phone sits on the right in English puts it on the
+ * left: every element moves to the other side of the slide's centre line
+ * and leans the other way. Nothing is stored mirrored; renderers mirror the
+ * one shared layout when they draw a mirrored language, and the editor maps
+ * its edits back. Mirroring twice gives the original back.
+ */
+import { isRtl } from './catalog';
+import type { LangCode, Project, Shadow, SlideElement, SlideLayout } from './types';
+
+/** Whether slides in `lang` are drawn mirrored: right-to-left languages, unless the project turned it off. */
+export function mirrorsLayout(project: Pick<Project, 'mirrorRtl'> | null | undefined, lang: LangCode): boolean {
+  return isRtl(lang) && project?.mirrorRtl !== false;
+}
+
+const flipX = (x: unknown) => (typeof x === 'number' ? 1 - x : x);
+const flipAngle = (a: unknown) => (typeof a === 'number' && a !== 0 ? -a : a);
+const flipShadow = (s: Shadow | null): Shadow | null => (s && typeof s === 'object' && typeof s.x === 'number' && s.x !== 0 ? { ...s, x: -s.x } : s);
+
+/** The element on the other side of the slide: x mirrored, rotation and shadow offsets reversed. */
+export function mirrorElement<T extends SlideElement>(el: T): T {
+  const out = { ...el, x: flipX(el.x), rotation: flipAngle(el.rotation) } as T;
+  if (out.kind === 'text') {
+    if (out.style && typeof out.style === 'object') out.style = { ...out.style, shadow: flipShadow(out.style.shadow) };
+  } else if (out.kind !== 'shape' && 'shadow' in out) {
+    out.shadow = flipShadow(out.shadow);
+  }
+  return out;
+}
+
+/** The layout with every element mirrored (the background is mirrored by the painter). */
+export function mirrorLayout(layout: SlideLayout): SlideLayout {
+  return { ...layout, elements: layout.elements.map(mirrorElement) };
+}
+
+/** Mirrors the position and angle of an element patch, to store an edit made on a mirrored slide. */
+export function mirrorPatch<P extends { x?: number; rotation?: number }>(patch: P): P {
+  const out = { ...patch };
+  if (typeof out.x === 'number') out.x = 1 - out.x;
+  if (typeof out.rotation === 'number' && out.rotation !== 0) out.rotation = -out.rotation;
+  return out;
+}

package/vendor/wajha/model/resolve.ts

@@ -0,0 +1,87 @@
+/**
+ * Read-side helpers that apply fallbacks. `resolveLayout` is owned by the
+ * model/store work package; the text and screenshot fallbacks are final.
+ */
+import { adaptLayout } from './adapt';
+import { FAMILIES, FAMILY_ORDER } from './catalog';
+import { defaultLayout } from './defaults';
+import type { FamilyId, LangCode, Project, Slide, SlideLayout, Theme } from './types';
+
+interface CachedLayout {
+  layout: SlideLayout;
+  /** project.families when computed: the primary family picks the source. */
+  families: string;
+  /** Theme the default layout was built with; null when the layout does not depend on it. */
+  theme: Theme | null;
+}
+
+/**
+ * Derived layouts per slide object. immer gives an edited slide a new
+ * identity and keeps unchanged ones, so entries go stale exactly when they
+ * should and are collected with the slides they belong to.
+ */
+const cache = new WeakMap<Slide, Map<FamilyId, CachedLayout>>();
+
+const EMPTY_LAYOUT: SlideLayout = Object.freeze({ background: null, elements: Object.freeze([]) as unknown as SlideLayout['elements'] });
+
+/** The family whose stored layout `family` derives from: the primary family, else any family with one. */
+export function layoutSource(project: Project, slide: Slide, family: FamilyId): FamilyId | null {
+  const layouts = slide.layouts ?? {};
+  if (layouts[family]) return family;
+  const primary = project.families[0];
+  if (primary && layouts[primary]) return primary;
+  for (const f of project.families) if (layouts[f]) return f;
+  for (const f of FAMILY_ORDER) if (layouts[f]) return f;
+  return null;
+}
+
+/**
+ * The layout for `family`: stored layout, else adapted from the primary
+ * family's layout, else a default layout. The result is shared and cached:
+ * treat it as read-only and copy it before editing. The cache assumes slides
+ * are immutable (an edit makes a new slide object, as immer does).
+ */
+export function resolveLayout(project: Project, slide: Slide, family: FamilyId): SlideLayout {
+  const stored = slide.layouts?.[family];
+  if (stored) return stored;
+  if (!FAMILIES[family]) return EMPTY_LAYOUT;
+
+  const families = project.families.join(',');
+  let byFamily = cache.get(slide);
+  const hit = byFamily?.get(family);
+  if (hit && hit.families === families && (hit.theme === null || hit.theme === project.theme)) return hit.layout;
+
+  const source = layoutSource(project, slide, family);
+  let entry: CachedLayout;
+  if (source && source !== family) {
+    const from = slide.layouts[source] as SlideLayout;
+    entry = { layout: adaptLayout(from, FAMILIES[source].design, FAMILIES[family].design, family), families, theme: null };
+  } else {
+    entry = { layout: defaultLayout(family, project.theme), families, theme: project.theme };
+  }
+  if (!byFamily) {
+    byFamily = new Map();
+    cache.set(slide, byFamily);
+  }
+  byFamily.set(family, entry);
+  return entry.layout;
+}
+
+/** `record[key]` when it is the record's own entry: keys come from data, and a plain object inherits "toString" and friends. */
+function ownEntry<T>(record: Record<string, T> | undefined, key: string): T | undefined {
+  return record && Object.prototype.hasOwnProperty.call(record, key) ? record[key] : undefined;
+}
+
+/** Text for key in `lang`, falling back to the base language, then "". */
+export function resolveText(slide: Slide, key: string, lang: LangCode, baseLang: LangCode): string {
+  const own = ownEntry(ownEntry(slide.texts, lang), key);
+  if (own !== undefined && own !== '') return own;
+  return ownEntry(ownEntry(slide.texts, baseLang), key) ?? '';
+}
+
+/** Asset id for family/slot in `lang`, falling back to the base language, then null. */
+export function resolveShot(slide: Slide, family: FamilyId, slot: string, lang: LangCode, baseLang: LangCode): string | null {
+  const bySlot = ownEntry(ownEntry(slide.shots, family), slot);
+  if (!bySlot) return null;
+  return ownEntry(bySlot, lang) ?? ownEntry(bySlot, baseLang) ?? null;
+}

package/vendor/wajha/model/rules.ts

@@ -0,0 +1,249 @@
+/**
+ * Rules every persisted value follows: identifier patterns, string and array
+ * limits, numeric ranges. The validators enforce them on untrusted files and
+ * the editor store applies the same rules to user edits, so anything the UI
+ * can produce is something the loader accepts.
+ */
+import { FAMILIES } from './catalog';
+import type { FamilyId, LangCode } from './types';
+
+/** Project, slide and element ids (path-safe; project ids name folders). */
+export const ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+/** Template ids: kebab-case, e.g. "sunset-glow" (and no Windows device name, see isTemplateId). */
+export const TEMPLATE_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Names Windows reserves for devices in every folder, whatever the case or extension. */
+const WINDOWS_DEVICE_RE = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])$/i;
+/** "<sha256 hex>.<ext>" */
+export const ASSET_ID_RE = /^[0-9a-f]{64}\.(png|jpg|webp)$/;
+export const COLOR_RE = /^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+/** BCP-47 shaped language codes: "en-US", "zh-Hans", "es-419", "fil". */
+export const LANG_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+/** Text keys ("headline") and screenshot slots ("main"). */
+export const KEY_RE = /^[A-Za-z0-9_.-]{1,40}$/;
+
+/**
+ * Keys that must never become own properties of objects we build: every
+ * member plain objects inherit, because a lookup such as `texts[lang][key]`
+ * would find the inherited one ("toString" reads a function, "__proto__"
+ * swaps the prototype on assignment).
+ */
+const FORBIDDEN_KEYS: ReadonlySet<string> = new Set([...Object.getOwnPropertyNames(Object.prototype), 'prototype']);
+
+export const LIMITS = {
+  /** Project, template, asset, element and author names. */
+  name: 200,
+  /** Slide texts and descriptions. */
+  text: 2000,
+  font: 100,
+  tag: 40,
+  path: 300,
+  date: 64,
+  langCode: 35,
+  id: 64,
+  slides: 100,
+  templateSlides: 10,
+  elements: 200,
+  palette: 32,
+  stops: 16,
+  meshPoints: 16,
+  tags: 20,
+  languages: 100,
+  textKeys: 100,
+  slots: 20,
+  assets: 5000,
+  fonts: 24,
+  galleryTemplates: 1000,
+  galleryAssets: 200,
+} as const;
+
+export interface Range {
+  min: number;
+  max: number;
+  /** Round to an integer after clamping. */
+  int?: boolean;
+}
+
+/** Sane ranges for every number in the model. Lengths are fractions of u. */
+export const RANGES = {
+  position: { min: -2, max: 3 },
+  rotation: { min: -360, max: 360 },
+  unit: { min: 0, max: 1 },
+  deviceWidth: { min: 0.02, max: 4 },
+  textWidth: { min: 0.02, max: 6 },
+  shapeSize: { min: 0.001, max: 8 },
+  imageWidth: { min: 0.01, max: 8 },
+  cornerRadius: { min: 0, max: 0.5 },
+  shapeRadius: { min: 0, max: 1 },
+  stroke: { min: 0, max: 2 },
+  blur: { min: 0, max: 2 },
+  shadowOffset: { min: -2, max: 2 },
+  fontSize: { min: 0.004, max: 1 },
+  fontWeight: { min: 1, max: 1000, int: true },
+  lineHeight: { min: 0.5, max: 4 },
+  /** Per-language factor on every text's line height (model/typography.ts). */
+  lineSpacing: { min: 0.8, max: 2 },
+  letterSpacing: { min: -0.5, max: 2 },
+  maxLines: { min: 0, max: 50, int: true },
+  seed: { min: 0, max: 2147483647, int: true },
+  angle: { min: -360, max: 360 },
+  gradientCenter: { min: -2, max: 3 },
+  gradientRadius: { min: 0.01, max: 4 },
+  patternScale: { min: 0.002, max: 2 },
+  imageBlur: { min: 0, max: 1 },
+  pixels: { min: 1, max: 100000, int: true },
+  bytes: { min: 0, max: Number.MAX_SAFE_INTEGER, int: true },
+  timestamp: { min: 0, max: 8.64e15, int: true },
+  jpegQuality: { min: 0.5, max: 1 },
+  galleryVersion: { min: 0, max: 1e9, int: true },
+} as const satisfies Record<string, Range>;
+
+/** Clamps into the range; NaN becomes the minimum so the result is always usable. */
+export function clampToRange(v: number, r: Range): number {
+  let x = Number.isNaN(v) ? r.min : v < r.min ? r.min : v > r.max ? r.max : v;
+  if (r.int) x = Math.round(x);
+  return x;
+}
+
+/** A catalog family id (own keys of FAMILIES only). */
+export function isFamilyId(v: unknown): v is FamilyId {
+  return typeof v === 'string' && Object.prototype.hasOwnProperty.call(FAMILIES, v);
+}
+
+/** A BCP-47 shaped language code of sane length. */
+export function isLangCode(v: unknown): v is LangCode {
+  return typeof v === 'string' && v.length <= LIMITS.langCode && LANG_RE.test(v);
+}
+
+/** A record key we accept for text keys and screenshot slots. */
+export function isSafeKey(v: unknown): v is string {
+  return typeof v === 'string' && v.length <= 40 && KEY_RE.test(v) && !FORBIDDEN_KEYS.has(v);
+}
+
+/** A project, slide or element id. */
+export function isId(v: unknown): v is string {
+  return typeof v === 'string' && v.length <= LIMITS.id && ID_RE.test(v);
+}
+
+/** "con", "aux", "nul", "prn", "com1", "lpt1"...: Windows cannot create a file or folder with that name. */
+export function isWindowsDeviceName(v: string): boolean {
+  return WINDOWS_DEVICE_RE.test(v);
+}
+
+/**
+ * A kebab-case template id of at most 64 characters. Template ids name their
+ * folder (templates/<id>/), so device names Windows reserves are refused
+ * everywhere: a template made on a Mac must open on Windows too.
+ */
+export function isTemplateId(v: unknown): v is string {
+  return typeof v === 'string' && v.length <= LIMITS.id && TEMPLATE_ID_RE.test(v) && !isWindowsDeviceName(v);
+}
+
+/** A content-addressed asset id, "<sha256 hex>.<png|jpg|webp>". */
+const FONT_FILE = /^[0-9a-f]{64}\.(ttf|otf|woff|woff2)$/;
+
+/** "<64 hex>.<ttf|otf|woff|woff2>", the only file names allowed in fonts folders. */
+export function isFontFile(v: unknown): v is string {
+  return typeof v === 'string' && FONT_FILE.test(v);
+}
+
+export function isAssetId(v: unknown): v is string {
+  return typeof v === 'string' && v.length <= 69 && ASSET_ID_RE.test(v);
+}
+
+/**
+ * "#RRGGBB" / "#RRGGBBAA" in lower case. The short forms "#RGB" and "#RGBA"
+ * are expanded because hand-written gallery JSON uses them; anything else is null.
+ */
+export function normalizeColor(v: unknown): string | null {
+  if (typeof v !== 'string' || v.length > 9) return null;
+  if (COLOR_RE.test(v)) return v.toLowerCase();
+  if (/^#[0-9a-fA-F]{3,4}$/.test(v)) {
+    return `#${[...v.slice(1)].map((c) => c + c).join('')}`.toLowerCase();
+  }
+  return null;
+}
+
+const isHighSurrogate = (c: number) => c >= 0xd800 && c <= 0xdbff;
+const isLowSurrogate = (c: number) => c >= 0xdc00 && c <= 0xdfff;
+
+/**
+ * Keeps at most `max` code points (what storage counts as "characters") and
+ * never splits a surrogate pair, so emoji and astral scripts survive.
+ */
+export function truncate(s: string, max: number): string {
+  if (s.length <= max) return s;
+  let i = 0;
+  let n = 0;
+  while (i < s.length && n < max) {
+    i += isHighSurrogate(s.charCodeAt(i)) && isLowSurrogate(s.charCodeAt(i + 1)) ? 2 : 1;
+    n++;
+  }
+  return s.slice(0, i);
+}
+
+// C0 and C1 controls (incl. DEL); names are single-line.
+// eslint-disable-next-line no-control-regex
+const NAME_CONTROLS = /[\u0000-\u001f\u007f-\u009f]/g;
+// Texts keep line breaks and tabs; bidi marks (U+200E, U+2066...) are not controls and stay.
+// eslint-disable-next-line no-control-regex
+const TEXT_CONTROLS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g;
+// A surrogate pair, or a lone half (no lookbehind: WKWebView before Safari 16.4 cannot parse it).
+const SURROGATES = /[\ud800-\udbff][\udc00-\udfff]|[\ud800-\udfff]/g;
+
+/**
+ * Replaces unpaired surrogates with U+FFFD. They are not text: file names,
+ * URI encoding and the Rust side all refuse them, so a stored name with one
+ * would break every export path built from it.
+ */
+export function wellFormed(s: string): string {
+  return s.replace(SURROGATES, (m) => (m.length === 2 ? m : '\ufffd'));
+}
+
+/** Single-line name: no control characters or unpaired surrogates, trimmed, length-limited. */
+export function cleanName(s: string, max: number = LIMITS.name): string {
+  // Cut before the regex work so a huge hostile string costs nothing.
+  const head = s.length > max * 4 + 64 ? s.slice(0, max * 4 + 64) : s;
+  return truncate(wellFormed(head).replace(NAME_CONTROLS, ' ').replace(/\s+/g, ' ').trim(), max);
+}
+
+/** Slide text: CRLF/CR become LF, other controls and unpaired surrogates are removed or replaced, length-limited. */
+export function cleanText(s: string, max: number = LIMITS.text): string {
+  const head = s.length > max * 2 + 64 ? s.slice(0, max * 2 + 64) : s;
+  return truncate(wellFormed(head).replace(/\r\n?/g, '\n').replace(TEXT_CONTROLS, ''), max);
+}
+
+/**
+ * CSS family name safe to interpolate into a canvas font string
+ * (`800 40px "<font>", ...`): quotes, backslashes and controls removed.
+ */
+export function cleanFontName(s: string, fallback: string): string {
+  const head = s.length > LIMITS.font * 2 ? s.slice(0, LIMITS.font * 2) : s;
+  const out = truncate(wellFormed(head).replace(NAME_CONTROLS, '').replace(/["\\;{}<>]/g, '').replace(/\s+/g, ' ').trim(), LIMITS.font);
+  return out === '' ? fallback : out;
+}
+
+/** Valid catalog families in their given order, without duplicates. */
+export function uniqueFamilies(list: readonly unknown[] | null | undefined): FamilyId[] {
+  const out: FamilyId[] = [];
+  if (!Array.isArray(list)) return out;
+  for (const f of list) if (isFamilyId(f) && !out.includes(f)) out.push(f);
+  return out;
+}
+
+/** Valid language codes in their given order, without duplicates, at most LIMITS.languages. */
+export function uniqueLanguages(list: readonly unknown[] | null | undefined): LangCode[] {
+  const out: LangCode[] = [];
+  if (!Array.isArray(list)) return out;
+  for (const l of list) {
+    if (out.length >= LIMITS.languages) break;
+    if (isLangCode(l) && !out.includes(l)) out.push(l);
+  }
+  return out;
+}
+
+/** Relative gallery path: "templates/sunset-glow/template.json". No "..", no leading "/", no schemes. */
+export function isSafeRelPath(v: unknown): v is string {
+  if (typeof v !== 'string' || v.length === 0 || v.length > LIMITS.path) return false;
+  if (!/^[A-Za-z0-9._\-/]+$/.test(v)) return false;
+  return v.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..');
+}

package/vendor/wajha/model/stub.ts

@@ -0,0 +1,4 @@
+/** Placeholder thrown by functions that are declared but not implemented yet. */
+export function notImplemented(name: string): never {
+  throw new Error(`${name} is not implemented yet`);
+}