@nfcard/validation 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { z } from 'zod';
+import * as _nfcard_types from '@nfcard/types';
 import { CardAsset, CardElement, ElementTransform } from '@nfcard/types';
+import { z } from 'zod';
 
 /**
  * Manufacturing-printability envelope for the free-transform element layer
@@ -49,6 +50,18 @@ declare function obbCorners(t: ElementTransform, wMm: number, hMm: number): Pt[]
 /** Are all corners inside the ID-1 rim minus the safety margin? */
 declare function cornersOnCard(corners: Pt[], margin?: number): boolean;
 type ChipAxis = 0 | 1 | 2;
+/**
+ * The chip PLACEMENT envelope: the region the chip *centre* must stay inside so
+ * the pattern-engine's hole-masking + rim clearance can keep the NFC pocket
+ * enclosed. Sized so the (scaled) Ø27.5·scale chip island clears the rim margin
+ * with a 1 mm buffer. Scale-aware so a grown chip tightens the envelope. Mirrors
+ * cardgen `chip_placement_max_xy`; `chipMaxXY()` is exactly this at scale 1 (the
+ * domain of the legacy 3×3 anchor lattice).
+ */
+declare function chipPlacementMaxXY(scale: number): {
+    maxX: number;
+    maxY: number;
+};
 /** Grid cell → card-local mm centre (matches pattern-engine `chipCentreForAnchor`). */
 declare function chipAnchorToMm(col: ChipAxis, row: ChipAxis): Pt;
 /** Free mm → nearest grid cell (matches pattern-engine `nearestChipAnchor`). The
@@ -66,6 +79,33 @@ interface Violation {
     elementId: string;
     message: string;
 }
+/** Unknown glyphs (outside the tables): reserve a generous em so any realistic exotic
+ *  char OVER-reserves. (Not a mathematical bound — a pathological single-codepoint wide
+ *  ligature can exceed it — but such glyphs aren't in the card font at all, so the print
+ *  pipeline rejects them upstream of this estimate.) */
+declare const ADVANCE_FALLBACK_EM = 1.1;
+/** ITALIC ink overhang: slanted glyphs poke past their advance box (measured against the
+ *  webfont: ≤ 0.20 em at 400, ≤ 0.23 em at 700 — descender tails like "jjj" are the worst
+ *  case; upright overhang is exactly 0). Charged once per text box so the advance-sum
+ *  width stays a true upper bound on the rendered ink for the italic toggle too. */
+declare const ITALIC_OVERHANG_EM = 0.25;
+/** Empty-text width floor — the OLD flat estimate's minimum (1 char × 0.6 em), kept so a
+ *  blank element still has a box. NOT a live glyph metric (blank text is separately gated
+ *  by `textEmpty`); it just anchors degenerate OBBs. */
+declare const EMPTY_TEXT_FLOOR_EM = 0.6;
+/** Baseline-to-baseline line advance for multi-line text (mirrors the render stack's
+ *  TEXT_LINE_FACTOR in nfcard-web pocShared + cardgen text2d). */
+declare const TEXT_LINE_FACTOR_EM = 1.32;
+/** Advance-sum width of ONE line in em, in the weight's metric set (≥600 → SemiBold). */
+declare function textAdvanceEm(line: string, weight: number): number;
+/** Estimated card footprint (w×h, pre-scale) used for the on-card OBB check. Text is the
+ *  per-glyph advance sum of the WIDEST line (untrimmed — spaces cost their real advance)
+ *  with the multi-line stack in the height; a guaranteed upper bound on the rendered ink
+ *  (see the table note above), so the gate can never accept an overflowing placement. */
+declare function footprintOf(el: CardElement): {
+    w: number;
+    h: number;
+};
 /** All hard manufacturing violations for one element. Empty ⇒ printable. */
 declare function elementPrintability(el: CardElement, ctx: PrintabilityCtx): Violation[];
 
@@ -5142,6 +5182,15 @@ declare const ctaButtonsSchema: z.ZodEffects<z.ZodArray<z.ZodObject<{
     url?: string | undefined;
     label?: string | undefined;
 }[]>;
+declare const tipJarSchema: z.ZodEffects<z.ZodUnknown, {
+    provider: _nfcard_types.TipProviderId;
+    handle: string;
+    label: string;
+} | {
+    provider: _nfcard_types.TipProviderId;
+    handle: string;
+    label?: undefined;
+} | undefined, unknown>;
 declare const digitalConfigSchema: z.ZodObject<{
     templateId: z.ZodEnum<["minimal", "bold", "card", "aurora", "classic", "spotlight", "marquee", "riso"]>;
     accentColor: z.ZodString;
@@ -5229,6 +5278,15 @@ declare const digitalConfigSchema: z.ZodObject<{
         url?: string | undefined;
         label?: string | undefined;
     }[]>>;
+    tipJar: z.ZodOptional<z.ZodEffects<z.ZodUnknown, {
+        provider: _nfcard_types.TipProviderId;
+        handle: string;
+        label: string;
+    } | {
+        provider: _nfcard_types.TipProviderId;
+        handle: string;
+        label?: undefined;
+    } | undefined, unknown>>;
 }, "strip", z.ZodTypeAny, {
     fontKey: string;
     templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -5264,6 +5322,15 @@ declare const digitalConfigSchema: z.ZodObject<{
         url: string;
         label: string;
     }[] | undefined;
+    tipJar?: {
+        provider: _nfcard_types.TipProviderId;
+        handle: string;
+        label: string;
+    } | {
+        provider: _nfcard_types.TipProviderId;
+        handle: string;
+        label?: undefined;
+    } | undefined;
 }, {
     fontKey: string;
     templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -5299,6 +5366,7 @@ declare const digitalConfigSchema: z.ZodObject<{
         url?: string | undefined;
         label?: string | undefined;
     }[] | undefined;
+    tipJar?: unknown;
 }>;
 declare const entrySourceSchema: z.ZodObject<{
     output: z.ZodOptional<z.ZodEnum<["with-card", "digital-only"]>>;
@@ -8792,6 +8860,15 @@ declare const configurationCreateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[]>>;
+        tipJar: z.ZodOptional<z.ZodEffects<z.ZodUnknown, {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined, unknown>>;
     }, "strip", z.ZodTypeAny, {
         fontKey: string;
         templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -8827,6 +8904,15 @@ declare const configurationCreateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     }, {
         fontKey: string;
         templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -8862,6 +8948,7 @@ declare const configurationCreateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     }>;
     quantity: z.ZodDefault<z.ZodNumber>;
     existingProfileId: z.ZodOptional<z.ZodString>;
@@ -9246,6 +9333,15 @@ declare const configurationCreateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     };
     quantity: number;
     existingProfileId?: string | undefined;
@@ -9612,6 +9708,7 @@ declare const configurationCreateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     };
     quantity?: number | undefined;
     existingProfileId?: string | undefined;
@@ -13090,6 +13187,15 @@ declare const configurationUpdateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[]>>;
+        tipJar: z.ZodOptional<z.ZodEffects<z.ZodUnknown, {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined, unknown>>;
     }, "strip", z.ZodTypeAny, {
         fontKey: string;
         templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -13125,6 +13231,15 @@ declare const configurationUpdateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     }, {
         fontKey: string;
         templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -13160,6 +13275,7 @@ declare const configurationUpdateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     }>>;
     quantity: z.ZodOptional<z.ZodNumber>;
     existingProfileId: z.ZodOptional<z.ZodString>;
@@ -13515,6 +13631,15 @@ declare const configurationUpdateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     } | undefined;
     quantity?: number | undefined;
     existingProfileId?: string | undefined;
@@ -13870,6 +13995,7 @@ declare const configurationUpdateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     } | undefined;
     quantity?: number | undefined;
     existingProfileId?: string | undefined;
@@ -13976,6 +14102,15 @@ declare const cardUpdateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[]>>>>;
+        tipJar: z.ZodOptional<z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodUnknown, {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined, unknown>>>>;
         profilePhotoUrl: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>>;
         companyLogoUrl: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>>;
     }, "strip", z.ZodTypeAny, {
@@ -14015,6 +14150,15 @@ declare const cardUpdateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     }, {
         profilePhotoUrl?: string | undefined;
         companyLogoUrl?: string | undefined;
@@ -14052,6 +14196,7 @@ declare const cardUpdateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     }>>;
     status: z.ZodOptional<z.ZodEnum<["active", "suspended", "archived"]>>;
 }, "strip", z.ZodTypeAny, {
@@ -14093,6 +14238,15 @@ declare const cardUpdateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     } | undefined;
 }, {
     status?: "active" | "suspended" | "archived" | undefined;
@@ -14133,6 +14287,7 @@ declare const cardUpdateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     } | undefined;
 }>;
 declare const adminCardCreateSchema: z.ZodObject<{
@@ -14312,6 +14467,15 @@ declare const adminCardCreateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[]>>;
+        tipJar: z.ZodOptional<z.ZodEffects<z.ZodUnknown, {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined, unknown>>;
     }, "strip", z.ZodTypeAny, {
         fontKey: string;
         templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -14347,6 +14511,15 @@ declare const adminCardCreateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     }, {
         fontKey: string;
         templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -14382,6 +14555,7 @@ declare const adminCardCreateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     }>;
     physicalConfig: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodObject<{
         material: z.ZodEnum<["plastic", "3dprint_standard", "metal", "bamboo"]>;
@@ -17730,6 +17904,15 @@ declare const adminCardCreateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     };
     targetUserId: string;
     physicalConfig?: {
@@ -18083,6 +18266,7 @@ declare const adminCardCreateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     };
     targetUserId: string;
     physicalConfig?: {
@@ -18647,6 +18831,15 @@ declare const profileCreateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[]>>;
+        tipJar: z.ZodOptional<z.ZodEffects<z.ZodUnknown, {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined, unknown>>;
     }, "strip", z.ZodTypeAny, {
         fontKey: string;
         templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -18682,6 +18875,15 @@ declare const profileCreateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     }, {
         fontKey: string;
         templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -18717,6 +18919,7 @@ declare const profileCreateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     }>;
     visibility: z.ZodDefault<z.ZodEnum<["public", "private", "link_only"]>>;
     accessPin: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
@@ -18781,6 +18984,15 @@ declare const profileCreateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     };
     label?: string | undefined;
     cardId?: string | undefined;
@@ -18846,6 +19058,7 @@ declare const profileCreateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     };
     label?: string | undefined;
     visibility?: "public" | "private" | "link_only" | undefined;
@@ -19038,6 +19251,15 @@ declare const signupWithProfileSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[]>>;
+        tipJar: z.ZodOptional<z.ZodEffects<z.ZodUnknown, {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined, unknown>>;
     }, "strip", z.ZodTypeAny, {
         fontKey: string;
         templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -19073,6 +19295,15 @@ declare const signupWithProfileSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     }, {
         fontKey: string;
         templateId: "minimal" | "bold" | "card" | "aurora" | "classic" | "spotlight" | "marquee" | "riso";
@@ -19108,6 +19339,7 @@ declare const signupWithProfileSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     }>;
 }, "strip", z.ZodTypeAny, {
     email: string;
@@ -19170,6 +19402,15 @@ declare const signupWithProfileSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     };
     password: string;
     acceptedTerms: true;
@@ -19239,6 +19480,7 @@ declare const signupWithProfileSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     };
     password: string;
     acceptedTerms: true;
@@ -19427,6 +19669,15 @@ declare const profileUpdateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[]>>>>;
+        tipJar: z.ZodOptional<z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodUnknown, {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined, unknown>>>>;
         profilePhotoUrl: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>>;
         companyLogoUrl: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>>;
     }, "strip", z.ZodTypeAny, {
@@ -19466,6 +19717,15 @@ declare const profileUpdateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     }, {
         profilePhotoUrl?: string | undefined;
         companyLogoUrl?: string | undefined;
@@ -19503,6 +19763,7 @@ declare const profileUpdateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     }>>;
     visibility: z.ZodOptional<z.ZodEnum<["public", "private", "link_only"]>>;
     accessPin: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
@@ -19570,6 +19831,15 @@ declare const profileUpdateSchema: z.ZodObject<{
             url: string;
             label: string;
         }[] | undefined;
+        tipJar?: {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label: string;
+        } | {
+            provider: _nfcard_types.TipProviderId;
+            handle: string;
+            label?: undefined;
+        } | undefined;
     } | undefined;
     icon?: string | undefined;
     accessPin?: string | undefined;
@@ -19637,6 +19907,7 @@ declare const profileUpdateSchema: z.ZodObject<{
             url?: string | undefined;
             label?: string | undefined;
         }[] | undefined;
+        tipJar?: unknown;
     } | undefined;
     icon?: string | undefined;
     accessPin?: string | undefined;
@@ -19785,4 +20056,4 @@ declare function validatePhysicalConfig(data: unknown): ValidationResult<z.infer
 declare function validateDigitalConfig(data: unknown): ValidationResult<z.infer<typeof digitalConfigSchema>>;
 declare function validateConfiguration(data: unknown): ValidationResult<z.infer<typeof configurationCreateSchema>>;
 
-export { CARD_H_MM, CARD_W_MM, CHIP_RADIUS_MM, CHIP_SCALE_FLOOR, type ChipAxis, EDGE_MARGIN_MM, MAX_CTA_BUTTONS, MIN_WALL_MM, NFC_COIL_DIAMETER_MM, NFC_RADIAL_CLEARANCE_MM, type PrintabilityCtx, type Pt, QR_MATRIX_CELLS, QR_MIN_SIZE_MM, QR_MODULE_MIN_MM, TEXT_MIN_EM_MM, type ValidationResult, type Violation, adminCardCreateSchema, cardAssetSchema, cardDesignMaterialSchema, cardDesignPatternSchema, cardDesignSchema, cardElementSchema, cardElementsSchema, cardProfileUpdateSchema, cardUpdateSchema, chipAnchorToMm, comboIdSchema, configurationCreateSchema, configurationUpdateSchema, contactDetailTogglesSchema, contactExchangeSchema, cornersOnCard, createOrderSchema, ctaButtonSchema, ctaButtonsSchema, digitalConfigSchema, digitalVisibilitySchema, elementPrintability, elementTransformSchema, entrySourceSchema, hubConfigSchema, hubProfilesUpdateSchema, isFiniteTransform, materialSchema, mmToNearestChipAnchor, obbCorners, patternFamilySchema, physicalConfigSchema, physicalContentOverridesSchema, profileAccessTokenCreateSchema, profileCreateSchema, profilePinVerifySchema, profileUpdateSchema, profileUserDataSchema, profileVisibilitySchema, sanitizeHttpUrl, sanitizeText, signupWithProfileSchema, socialLinksSchema, socialOverridesSchema, userDataSchema, validateConfiguration, validateDigitalConfig, validatePhysicalConfig, validateUserData, webAddressSchema };
+export { ADVANCE_FALLBACK_EM, CARD_H_MM, CARD_W_MM, CHIP_RADIUS_MM, CHIP_SCALE_FLOOR, type ChipAxis, EDGE_MARGIN_MM, EMPTY_TEXT_FLOOR_EM, ITALIC_OVERHANG_EM, MAX_CTA_BUTTONS, MIN_WALL_MM, NFC_COIL_DIAMETER_MM, NFC_RADIAL_CLEARANCE_MM, type PrintabilityCtx, type Pt, QR_MATRIX_CELLS, QR_MIN_SIZE_MM, QR_MODULE_MIN_MM, TEXT_LINE_FACTOR_EM, TEXT_MIN_EM_MM, type ValidationResult, type Violation, adminCardCreateSchema, cardAssetSchema, cardDesignMaterialSchema, cardDesignPatternSchema, cardDesignSchema, cardElementSchema, cardElementsSchema, cardProfileUpdateSchema, cardUpdateSchema, chipAnchorToMm, chipPlacementMaxXY, comboIdSchema, configurationCreateSchema, configurationUpdateSchema, contactDetailTogglesSchema, contactExchangeSchema, cornersOnCard, createOrderSchema, ctaButtonSchema, ctaButtonsSchema, digitalConfigSchema, digitalVisibilitySchema, elementPrintability, elementTransformSchema, entrySourceSchema, footprintOf, hubConfigSchema, hubProfilesUpdateSchema, isFiniteTransform, materialSchema, mmToNearestChipAnchor, obbCorners, patternFamilySchema, physicalConfigSchema, physicalContentOverridesSchema, profileAccessTokenCreateSchema, profileCreateSchema, profilePinVerifySchema, profileUpdateSchema, profileUserDataSchema, profileVisibilitySchema, sanitizeHttpUrl, sanitizeText, signupWithProfileSchema, socialLinksSchema, socialOverridesSchema, textAdvanceEm, tipJarSchema, userDataSchema, validateConfiguration, validateDigitalConfig, validatePhysicalConfig, validateUserData, webAddressSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nfcard/validation",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Shared Zod validation schemas for the NFCard product family.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "dependencies": {
     "zod": "^3.24.0",
-    "@nfcard/types": "0.13.2"
+    "@nfcard/types": "0.14.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0"

package/src/elements.test.ts

@@ -163,6 +163,48 @@ describe('cardDesignSchema — free-transform element layer (NFCARD-197/198)', (
     expect(codes(res)).toContain('elementOffCard')
   })
 
+  it('NFCARD-421: rejects a chip nudged past the pattern-engine placement envelope', () => {
+    // The repro design (order 99d2ef93): chip near the top-left corner at
+    // (−24.2, −11.15), scale 1. |y| 11.15 > envelope maxY 10.75, so the pocket
+    // wall gets cut at cardgen batch time. The looser elementOffCard OBB check
+    // (rim 25.5) let it through checkout before this gate.
+    const res = cardDesignSchema.safeParse(
+      withElements([chipEl({ transform: { xMm: -24.2, yMm: -11.15, rotationDeg: 0, scale: 1, z: 0 } })], {
+        layout: { chipAnchor: { col: 0, row: 0 } },
+      }),
+    )
+    expect(res.success).toBe(false)
+    expect(codes(res)).toContain('chipOutsideEnvelope')
+  })
+
+  it('NFCARD-421: accepts a chip sitting exactly at the envelope edge', () => {
+    // maxY at scale 1 = 54/2 − 1.5 − 13.75 − 1 = 10.75.
+    const res = cardDesignSchema.safeParse(
+      withElements([chipEl({ transform: { xMm: 0, yMm: 10.75, rotationDeg: 0, scale: 1, z: 0 } })], {
+        layout: { chipAnchor: { col: 1, row: 2 } },
+      }),
+    )
+    expect(res.success).toBe(true)
+  })
+
+  it('NFCARD-421: the placement envelope tightens as the chip scales up', () => {
+    // A chip at y = 9 is inside the scale-1 envelope (10.75) but a chip scaled to
+    // 1.3 (island Ø35.75) no longer clears the rim there — envelope maxY ≈ 6.63.
+    const ok = cardDesignSchema.safeParse(
+      withElements([chipEl({ transform: { xMm: 0, yMm: 9, rotationDeg: 0, scale: 1, z: 0 } })], {
+        layout: { chipAnchor: { col: 1, row: 2 } },
+      }),
+    )
+    expect(ok.success).toBe(true)
+    const tooBig = cardDesignSchema.safeParse(
+      withElements([chipEl({ transform: { xMm: 0, yMm: 9, rotationDeg: 0, scale: 1.3, z: 0 } })], {
+        layout: { chipAnchor: { col: 1, row: 2 } },
+      }),
+    )
+    expect(tooBig.success).toBe(false)
+    expect(codes(tooBig)).toContain('chipOutsideEnvelope')
+  })
+
   it('rejects duplicate element ids', () => {
     const res = cardDesignSchema.safeParse(withElements([chipEl(), textEl({ id: 'chip1' })]))
     expect(res.success).toBe(false)

package/src/printability.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest'
+import type { CardElement } from '@nfcard/types'
+import {
+  ADVANCE_FALLBACK_EM,
+  ITALIC_OVERHANG_EM,
+  TEXT_LINE_FACTOR_EM,
+  elementPrintability,
+  footprintOf,
+  textAdvanceEm,
+  CARD_W_MM,
+  EDGE_MARGIN_MM,
+} from './printability'
+
+// ── NFCARD-530 — per-glyph advance-table text footprint ──
+// The flat 0.6 em/char estimate over-reserved ~25 % on lowercase strings (false
+// elementOffCard far from the rim) and UNDER-reserved wide glyphs (W = 1.089 em).
+// The tables are generated from the Instrument Sans webfont; sum-of-advances is a
+// verified upper bound on the kerned ink (kerning in this font only subtracts).
+
+const textEl = (over: Partial<Record<string, unknown>> = {}): CardElement =>
+  ({
+    id: 't1',
+    type: 'text',
+    text: 'Anna Kovács',
+    sizeMm: 4,
+    weight: 400,
+    role: 'text',
+    transform: { xMm: 0, yMm: 0, rotationDeg: 0, scale: 1, z: 1 },
+    ...over,
+  }) as unknown as CardElement
+
+const ctx = { assetsById: new Map() }
+
+describe('NFCARD-530 — textAdvanceEm (per-glyph advance tables)', () => {
+  it('sums real glyph advances — narrow and wide glyphs differ (the flat 0.6 could not)', () => {
+    expect(textAdvanceEm('l', 400)).toBeCloseTo(0.24, 6)
+    expect(textAdvanceEm('W', 400)).toBeCloseTo(1.089, 6)
+    expect(textAdvanceEm('Hello', 400)).toBeCloseTo(0.736 + 0.564 + 0.24 + 0.24 + 0.584, 6)
+  })
+
+  it('weight ≥ 600 uses the SemiBold metric set', () => {
+    expect(textAdvanceEm('a', 600)).toBeCloseTo(0.571, 6)
+    expect(textAdvanceEm('a', 700)).toBeCloseTo(0.571, 6)
+    expect(textAdvanceEm('a', 400)).toBeCloseTo(0.533, 6)
+  })
+
+  it('unknown glyphs reserve the generous fallback (over-reserve, never under)', () => {
+    expect(textAdvanceEm('あ', 400)).toBeCloseTo(ADVANCE_FALLBACK_EM, 6)
+    expect(textAdvanceEm('a😀b', 400)).toBeCloseTo(0.533 + ADVANCE_FALLBACK_EM + 0.606, 6)
+  })
+})
+
+describe('NFCARD-530 — footprintOf text branch', () => {
+  it('width = widest line advance sum × sizeMm; spaces cost their real advance (untrimmed)', () => {
+    const el = textEl({ text: 'a a', sizeMm: 4 })
+    expect(footprintOf(el).w).toBeCloseTo((0.533 + 0.2 + 0.533) * 4, 6)
+  })
+
+  it('multi-line: widest line wins the width; height gains the 1.32 em line stack', () => {
+    const el = textEl({ text: 'mmmm\nil', sizeMm: 4 })
+    const wide = textAdvanceEm('mmmm', 400)
+    expect(footprintOf(el).w).toBeCloseTo(wide * 4, 6)
+    expect(footprintOf(el).h).toBeCloseTo(4 * (1.3 + TEXT_LINE_FACTOR_EM), 6)
+  })
+
+  it('ITALIC charges the slant-overhang term — the ink of slanted tails pokes past the advance box', () => {
+    // Measured against the webfont: italic ink exceeds the advance sum by ≤ 0.23 em
+    // ("jjj" descender tails are the worst case); upright overhang is exactly 0. Without
+    // this term the "upper bound on rendered ink" claim silently broke for the italic toggle.
+    const upright = footprintOf(textEl({ text: 'jjj' }))
+    const italic = footprintOf(textEl({ text: 'jjj', italic: true }))
+    expect(italic.w - upright.w).toBeCloseTo(ITALIC_OVERHANG_EM * 4, 6)
+    expect(italic.h).toBeCloseTo(upright.h, 6)
+  })
+
+  it('empty text keeps the historical 0.6 em floor', () => {
+    expect(footprintOf(textEl({ text: '' })).w).toBeCloseTo(0.6 * 4, 6)
+    expect(footprintOf(textEl({ text: '' })).h).toBeCloseTo(4 * 1.3, 6)
+  })
+
+  it('SAFETY: wide-glyph strings now reserve MORE than the old flat 0.6 em/char', () => {
+    const el = textEl({ text: 'WWWW' })
+    const oldFlat = 4 * 4 * 0.6
+    expect(footprintOf(el).w).toBeGreaterThan(oldFlat)
+  })
+})
+
+describe('NFCARD-530 — elementOffCard verdict with the accurate estimate', () => {
+  const rimX = CARD_W_MM / 2 - EDGE_MARGIN_MM
+
+  it('no longer flags a long lowercase string sitting clearly inside the rim', () => {
+    // 18-char lowercase @ 2 mm × scale 2: flat estimate = 43.2 mm wide; advance sum = 38.3 mm.
+    // Place it in the band where the FLAT box crossed the rim but the accurate one does not.
+    const text = 'asdasdqwet4t6 7e56'
+    const el = textEl({ text, sizeMm: 2, transform: { xMm: -21, yMm: 0, rotationDeg: 0, scale: 2, z: 1 } })
+    const accurateHalf = (textAdvanceEm(text, 400) * 2 * 2) / 2
+    const flatHalf = (text.length * 2 * 0.6 * 2) / 2
+    expect(-21 - flatHalf).toBeLessThan(-rimX) // the OLD estimate tripped here…
+    expect(-21 - accurateHalf).toBeGreaterThan(-rimX) // …the accurate one fits…
+    expect(elementPrintability(el, ctx).map((v) => v.code)).toEqual([]) // …and the gate agrees.
+  })
+
+  it('still rejects text genuinely past the rim (the historical xMm 60 case)', () => {
+    const el = textEl({ transform: { xMm: 60, yMm: 0, rotationDeg: 0, scale: 1, z: 1 } })
+    expect(elementPrintability(el, ctx).map((v) => v.code)).toContain('elementOffCard')
+  })
+})

package/src/printability.ts

@@ -98,13 +98,25 @@ export function cornersOnCard(corners: Pt[], margin = EDGE_MARGIN_MM): boolean {
 const ANCHOR_NORM = [-0.85, 0, 0.85] as const
 export type ChipAxis = 0 | 1 | 2
 
-function chipMaxXY(): { maxX: number; maxY: number } {
+/**
+ * The chip PLACEMENT envelope: the region the chip *centre* must stay inside so
+ * the pattern-engine's hole-masking + rim clearance can keep the NFC pocket
+ * enclosed. Sized so the (scaled) Ø27.5·scale chip island clears the rim margin
+ * with a 1 mm buffer. Scale-aware so a grown chip tightens the envelope. Mirrors
+ * cardgen `chip_placement_max_xy`; `chipMaxXY()` is exactly this at scale 1 (the
+ * domain of the legacy 3×3 anchor lattice).
+ */
+export function chipPlacementMaxXY(scale: number): { maxX: number; maxY: number } {
   return {
-    maxX: CARD_W_MM / 2 - EDGE_MARGIN_MM - CHIP_RADIUS_MM - 1,
-    maxY: CARD_H_MM / 2 - EDGE_MARGIN_MM - CHIP_RADIUS_MM - 1,
+    maxX: CARD_W_MM / 2 - EDGE_MARGIN_MM - CHIP_RADIUS_MM * scale - 1,
+    maxY: CARD_H_MM / 2 - EDGE_MARGIN_MM - CHIP_RADIUS_MM * scale - 1,
   }
 }
 
+function chipMaxXY(): { maxX: number; maxY: number } {
+  return chipPlacementMaxXY(1)
+}
+
 /** Grid cell → card-local mm centre (matches pattern-engine `chipCentreForAnchor`). */
 export function chipAnchorToMm(col: ChipAxis, row: ChipAxis): Pt {
   const { maxX, maxY } = chipMaxXY()
@@ -141,9 +153,88 @@ export interface Violation {
   message: string
 }
 
-/** Estimated card footprint (w×h, pre-scale) used for the on-card OBB check. The
- *  editor measures real glyph widths; this is the schema-side backstop. */
-function footprintOf(el: CardElement): { w: number; h: number } {
+// ── Text width estimate: per-glyph advance tables (NFCARD-530) ──
+// GENERATED from the Instrument Sans webfont the card actually renders with (canvas
+// measureText at 100 px → em, Chrome). The font ships two metric sets — <600 maps to the
+// Regular face, ≥600 to the SemiBold face — and italic advances equal the upright ones
+// (the italic INK overhang past the advance box is charged separately, ITALIC_OVERHANG_EM).
+// Kerning in this font only ever SUBTRACTS (verified across mixed-case/HU samples:
+// max real/sum ratio = 1.0), so a plain sum of advances is a guaranteed UPPER bound on
+// the rendered ink, typically within 1–8 %. This replaces the flat 0.6 em/char estimate,
+// which over-reserved ~25 % on lowercase strings (false `elementOffCard` far from the
+// rim — NFCARD-530) while UNDER-reserving wide glyphs (`W` = 1.089 em — a real print
+// overflow hole). cardgen `validate.py` mirrors these tables 1:1 (parity golden).
+const ADVANCE_EM_REGULAR: Record<string, number> = {
+  '0': 0.666, '1': 0.391, '2': 0.545, '3': 0.574, '4': 0.6, '5': 0.574, '6': 0.599, '7': 0.532,
+  '8': 0.582, '9': 0.61, ' ': 0.2, '!': 0.273, '"': 0.384, '#': 0.716, '$': 0.608, '%': 0.786,
+  '&': 0.755, "'": 0.232, '(': 0.406, ')': 0.406, '*': 0.408, '+': 0.531, ',': 0.255, '-': 0.506,
+  '.': 0.255, '/': 0.443, ':': 0.255, ';': 0.255, '<': 0.531, '=': 0.531, '>': 0.531, '?': 0.567,
+  '@': 0.853, 'A': 0.728, 'B': 0.636, 'C': 0.741, 'D': 0.752, 'E': 0.638, 'F': 0.602, 'G': 0.765,
+  'H': 0.736, 'I': 0.254, 'J': 0.455, 'K': 0.692, 'L': 0.588, 'M': 0.906, 'N': 0.736, 'O': 0.786,
+  'P': 0.656, 'Q': 0.787, 'R': 0.656, 'S': 0.608, 'T': 0.648, 'U': 0.712, 'V': 0.728, 'W': 1.089,
+  'X': 0.688, 'Y': 0.676, 'Z': 0.623, '[': 0.406, '\\': 0.443, ']': 0.406, '^': 0.531, '_': 0.426,
+  '`': 0.354, 'a': 0.533, 'b': 0.606, 'c': 0.533, 'd': 0.606, 'e': 0.564, 'f': 0.354, 'g': 0.606,
+  'h': 0.599, 'i': 0.24, 'j': 0.24, 'k': 0.535, 'l': 0.24, 'm': 0.922, 'n': 0.599, 'o': 0.584,
+  'p': 0.606, 'q': 0.606, 'r': 0.375, 's': 0.473, 't': 0.377, 'u': 0.589, 'v': 0.523, 'w': 0.767,
+  'x': 0.551, 'y': 0.523, 'z': 0.496, '{': 0.406, '|': 0.242, '}': 0.406, '~': 0.531, 'Á': 0.728,
+  'É': 0.638, 'Í': 0.254, 'Ó': 0.786, 'Ö': 0.786, 'Ő': 0.786, 'Ú': 0.712, 'Ü': 0.712, 'Ű': 0.712,
+  'á': 0.533, 'é': 0.564, 'í': 0.24, 'ó': 0.584, 'ö': 0.584, 'ő': 0.584, 'ú': 0.589, 'ü': 0.589,
+  'ű': 0.589, 'Ä': 0.728, 'ä': 0.533, 'Ë': 0.638, 'ë': 0.564, 'Ï': 0.254, 'ï': 0.24, 'Ñ': 0.736,
+  'ñ': 0.599, 'Ç': 0.741, 'ç': 0.533, 'ß': 0.612, 'ẞ': 0.713, '€': 0.701, '°': 0.386, '§': 0.498,
+  '·': 0.103, '•': 0.306, '–': 0.586, '—': 0.886, '…': 0.655, '‘': 0.255, '’': 0.255, '“': 0.409,
+  '”': 0.409, '„': 0.398, '±': 0.5488, '×': 0.531, '÷': 0.531,
+}
+const ADVANCE_EM_BOLD: Record<string, number> = {
+  '0': 0.682, '1': 0.385, '2': 0.563, '3': 0.582, '4': 0.622, '5': 0.585, '6': 0.623, '7': 0.575,
+  '8': 0.606, '9': 0.624, ' ': 0.19, '!': 0.306, '"': 0.482, '#': 0.732, '$': 0.652, '%': 0.786,
+  '&': 0.774, "'": 0.268, '(': 0.456, ')': 0.456, '*': 0.441, '+': 0.551, ',': 0.285, '-': 0.486,
+  '.': 0.285, '/': 0.445, ':': 0.285, ';': 0.285, '<': 0.551, '=': 0.551, '>': 0.551, '?': 0.587,
+  '@': 0.874, 'A': 0.736, 'B': 0.649, 'C': 0.75, 'D': 0.756, 'E': 0.626, 'F': 0.59, 'G': 0.763,
+  'H': 0.72, 'I': 0.254, 'J': 0.413, 'K': 0.722, 'L': 0.59, 'M': 0.894, 'N': 0.72, 'O': 0.798,
+  'P': 0.672, 'Q': 0.815, 'R': 0.668, 'S': 0.652, 'T': 0.672, 'U': 0.7, 'V': 0.736, 'W': 1.086,
+  'X': 0.716, 'Y': 0.712, 'Z': 0.635, '[': 0.456, '\\': 0.445, ']': 0.456, '^': 0.551, '_': 0.486,
+  '`': 0.354, 'a': 0.571, 'b': 0.628, 'c': 0.562, 'd': 0.628, 'e': 0.574, 'f': 0.378, 'g': 0.628,
+  'h': 0.619, 'i': 0.27, 'j': 0.27, 'k': 0.569, 'l': 0.27, 'm': 0.95, 'n': 0.619, 'o': 0.604,
+  'p': 0.628, 'q': 0.628, 'r': 0.398, 's': 0.504, 't': 0.421, 'u': 0.611, 'v': 0.543, 'w': 0.816,
+  'x': 0.605, 'y': 0.543, 'z': 0.522, '{': 0.456, '|': 0.23, '}': 0.456, '~': 0.551, 'Á': 0.736,
+  'É': 0.626, 'Í': 0.254, 'Ó': 0.798, 'Ö': 0.798, 'Ő': 0.798, 'Ú': 0.7, 'Ü': 0.7, 'Ű': 0.7,
+  'á': 0.571, 'é': 0.574, 'í': 0.27, 'ó': 0.604, 'ö': 0.604, 'ő': 0.604, 'ú': 0.611, 'ü': 0.611,
+  'ű': 0.611, 'Ä': 0.736, 'ä': 0.571, 'Ë': 0.626, 'ë': 0.574, 'Ï': 0.254, 'ï': 0.27, 'Ñ': 0.72,
+  'ñ': 0.619, 'Ç': 0.75, 'ç': 0.562, 'ß': 0.64, 'ẞ': 0.717, '€': 0.722, '°': 0.366, '§': 0.53,
+  '·': 0.165, '•': 0.351, '–': 0.606, '—': 0.906, '…': 0.765, '‘': 0.285, '’': 0.285, '“': 0.502,
+  '”': 0.502, '„': 0.497, '±': 0.5488, '×': 0.551, '÷': 0.551,
+}
+/** Unknown glyphs (outside the tables): reserve a generous em so any realistic exotic
+ *  char OVER-reserves. (Not a mathematical bound — a pathological single-codepoint wide
+ *  ligature can exceed it — but such glyphs aren't in the card font at all, so the print
+ *  pipeline rejects them upstream of this estimate.) */
+export const ADVANCE_FALLBACK_EM = 1.1
+/** ITALIC ink overhang: slanted glyphs poke past their advance box (measured against the
+ *  webfont: ≤ 0.20 em at 400, ≤ 0.23 em at 700 — descender tails like "jjj" are the worst
+ *  case; upright overhang is exactly 0). Charged once per text box so the advance-sum
+ *  width stays a true upper bound on the rendered ink for the italic toggle too. */
+export const ITALIC_OVERHANG_EM = 0.25
+/** Empty-text width floor — the OLD flat estimate's minimum (1 char × 0.6 em), kept so a
+ *  blank element still has a box. NOT a live glyph metric (blank text is separately gated
+ *  by `textEmpty`); it just anchors degenerate OBBs. */
+export const EMPTY_TEXT_FLOOR_EM = 0.6
+/** Baseline-to-baseline line advance for multi-line text (mirrors the render stack's
+ *  TEXT_LINE_FACTOR in nfcard-web pocShared + cardgen text2d). */
+export const TEXT_LINE_FACTOR_EM = 1.32
+
+/** Advance-sum width of ONE line in em, in the weight's metric set (≥600 → SemiBold). */
+export function textAdvanceEm(line: string, weight: number): number {
+  const table = weight >= 600 ? ADVANCE_EM_BOLD : ADVANCE_EM_REGULAR
+  let em = 0
+  for (const ch of line) em += table[ch] ?? ADVANCE_FALLBACK_EM
+  return em
+}
+
+/** Estimated card footprint (w×h, pre-scale) used for the on-card OBB check. Text is the
+ *  per-glyph advance sum of the WIDEST line (untrimmed — spaces cost their real advance)
+ *  with the multi-line stack in the height; a guaranteed upper bound on the rendered ink
+ *  (see the table note above), so the gate can never accept an overflowing placement. */
+export function footprintOf(el: CardElement): { w: number; h: number } {
   switch (el.type) {
     case 'chip':
       return { w: 2 * CHIP_RADIUS_MM, h: 2 * CHIP_RADIUS_MM }
@@ -153,9 +244,14 @@ function footprintOf(el: CardElement): { w: number; h: number } {
     case 'logo':
       return { w: el.widthMm, h: el.heightMm }
     case 'text': {
-      // Coarse: ~0.6 em per glyph wide, ~1.3 em tall. Editor does the precise check.
-      const w = Math.max(1, el.text.length) * el.sizeMm * 0.6
-      return { w, h: el.sizeMm * 1.3 }
+      const lines = el.text.split('\n')
+      let maxEm = 0
+      for (const line of lines) maxEm = Math.max(maxEm, textAdvanceEm(line, el.weight))
+      const widthEm = Math.max(EMPTY_TEXT_FLOOR_EM, maxEm) + (el.italic ? ITALIC_OVERHANG_EM : 0)
+      return {
+        w: widthEm * el.sizeMm,
+        h: el.sizeMm * (1.3 + (lines.length - 1) * TEXT_LINE_FACTOR_EM),
+      }
     }
   }
 }
@@ -171,11 +267,29 @@ export function elementPrintability(el: CardElement, ctx: PrintabilityCtx): Viol
   }
 
   switch (el.type) {
-    case 'chip':
+    case 'chip': {
       if (el.transform.scale < CHIP_SCALE_FLOOR - EPS) {
         push('chipScaleBelowCoil', 'The chip cannot shrink below the 25 mm NFC coil.')
       }
+      // NFCARD-421: the NFC pocket is only guaranteed enclosable when the chip
+      // island sits inside the pattern-engine PLACEMENT envelope — the domain
+      // under which hole-masking + rim clearance keep the perforation off the
+      // pocket wall. The generic `elementOffCard` OBB check is far looser (it lets
+      // the island edge reach the rim), so a chip nudged just past the envelope
+      // passes checkout yet fails cardgen's pocket-enclosure invariant at batch
+      // time — the buyer paid for an un-manufacturable card.
+      const env = chipPlacementMaxXY(el.transform.scale)
+      if (
+        Math.abs(el.transform.xMm) > env.maxX + EPS ||
+        Math.abs(el.transform.yMm) > env.maxY + EPS
+      ) {
+        push(
+          'chipOutsideEnvelope',
+          'The NFC chip is too close to the card edge — the pocket cannot be sealed.',
+        )
+      }
       break
+    }
     case 'qr':
       if (el.sizeMm * el.transform.scale < QR_MIN_SIZE_MM - EPS) {
         push('qrTooSmall', 'The QR code is below the scannable size floor.')

package/src/tipJar.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { tipJarSchema, digitalConfigSchema } from './index'
+
+const baseConfig = {
+  templateId: 'classic' as const,
+  accentColor: '#123456',
+  fontKey: 'inter',
+  showAvatar: true,
+}
+
+describe('tipJarSchema', () => {
+  it('accepts a valid provider + handle and stores only { provider, handle }', () => {
+    expect(tipJarSchema.parse({ provider: 'kofi', handle: 'ricsi' })).toEqual({
+      provider: 'kofi',
+      handle: 'ricsi',
+    })
+  })
+
+  it('normalizes a pasted full URL down to the handle', () => {
+    expect(tipJarSchema.parse({ provider: 'kofi', handle: 'https://ko-fi.com/ricsi?x=1' })).toEqual(
+      { provider: 'kofi', handle: 'ricsi' },
+    )
+  })
+
+  it('lowercases revolut handles', () => {
+    expect(tipJarSchema.parse({ provider: 'revolut', handle: 'RicSi' })).toEqual({
+      provider: 'revolut',
+      handle: 'ricsi',
+    })
+  })
+
+  it('keeps a sanitized custom label, capped at 40 chars', () => {
+    const out = tipJarSchema.parse({
+      provider: 'kofi',
+      handle: 'ricsi',
+      label: '<b>Támogass</b> ' + 'x'.repeat(60),
+    })
+    expect(out?.provider).toBe('kofi')
+    expect(out?.label).not.toContain('<')
+    expect((out?.label ?? '').length).toBeLessThanOrEqual(40)
+  })
+
+  it('drops everything invalid to undefined instead of throwing (never 400)', () => {
+    expect(tipJarSchema.parse(undefined)).toBeUndefined()
+    expect(tipJarSchema.parse(null)).toBeUndefined()
+    expect(tipJarSchema.parse('nonsense')).toBeUndefined()
+    expect(tipJarSchema.parse({})).toBeUndefined()
+    expect(tipJarSchema.parse({ provider: 'stripe', handle: 'ricsi' })).toBeUndefined()
+    expect(tipJarSchema.parse({ provider: 'kofi', handle: 'x' })).toBeUndefined() // too short
+    expect(tipJarSchema.parse({ provider: 'kofi', handle: 'https://evil.com/ricsi' })).toBeUndefined()
+    expect(tipJarSchema.parse({ provider: 'kofi', handle: 'javascript:alert(1)' })).toBeUndefined()
+    expect(tipJarSchema.parse({ provider: 'kofi', handle: 123 })).toBeUndefined()
+  })
+})
+
+describe('digitalConfigSchema — tipJar field', () => {
+  it('round-trips a valid tipJar', () => {
+    const parsed = digitalConfigSchema.parse({
+      ...baseConfig,
+      tipJar: { provider: 'revolut', handle: 'ricsi' },
+    })
+    expect(parsed.tipJar).toEqual({ provider: 'revolut', handle: 'ricsi' })
+  })
+
+  it('drops an invalid tipJar without failing the whole config save', () => {
+    const parsed = digitalConfigSchema.parse({
+      ...baseConfig,
+      tipJar: { provider: 'kofi', handle: 'https://evil.com/x' },
+    })
+    expect(parsed.tipJar).toBeUndefined()
+  })
+
+  it('is optional — a config without a tipJar parses fine', () => {
+    const parsed = digitalConfigSchema.parse(baseConfig)
+    expect(parsed.tipJar).toBeUndefined()
+  })
+})