@nfcard/validation 0.25.1 → 0.26.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _nfcard_types from '@nfcard/types';
-import { CardAsset, CardElement, ElementTransform, ProfileObjectKind, ProfileLayout } from '@nfcard/types';
+import { CardAsset, ElementTransform, CardElement, ProfileObjectKind, ProfileLayout } from '@nfcard/types';
 import { z } from 'zod';
 
 /**
@@ -47,6 +47,21 @@ interface Pt {
 declare function isFiniteTransform(t: ElementTransform): boolean;
 /** The 4 corners of a `wMm × hMm` box (centre-origin local) under a transform. */
 declare function obbCorners(t: ElementTransform, wMm: number, hMm: number): Pt[];
+/** Is a DISC of radius `rMm` centred at `t` inside the ID-1 rim minus the safety margin?
+ *
+ *  NFCARD-841 — the chip is physically a DISC, but {@link footprintOf} gives it the 27.5 mm
+ *  bounding SQUARE, so running it through {@link cornersOnCard} + {@link obbCorners} made its
+ *  on-card verdict ROTATION-SENSITIVE. A circle covers the same area at every angle, so that is
+ *  wrong in principle; it was also wrong in practice, because past scale ≈1.31 the square's
+ *  half-diagonal (13.75·s·√2) exceeds the 25.5 mm rim and a 45°-rotated chip was rejected at
+ *  EVERY position on the card — unorderable with no placement that could save it.
+ *
+ *  ⚠ At rotation 0 this is EXACTLY the old bound (the square's half-height IS the radius), so no
+ *  previously-legal design changes verdict and no previously-illegal one is let through. The only
+ *  behaviour that moves is the rotation artifact.
+ *
+ *  Rotation-invariant by construction — it takes no angle. Mirrors cardgen `disc_on_card`. */
+declare function discOnCard(t: ElementTransform, rMm: number, margin?: number): boolean;
 /** 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;
@@ -22722,5 +22737,63 @@ declare function validateUserData(data: unknown): ValidationResult<z.infer<typeo
 declare function validatePhysicalConfig(data: unknown): ValidationResult<z.infer<typeof physicalConfigSchema>>;
 declare function validateDigitalConfig(data: unknown): ValidationResult<z.infer<typeof digitalConfigSchema>>;
 declare function validateConfiguration(data: unknown): ValidationResult<z.infer<typeof configurationCreateSchema>>;
+/** What physical thing carries the code. Fulfilment dispatch, never routing. */
+declare const productTypeSchema: z.ZodEnum<["card", "qr_sticker", "keychain", "board"]>;
+/** Where a tap goes. */
+declare const linkDestinationTypeSchema: z.ZodEnum<["auto", "profile", "hub_chooser", "external", "board"]>;
+/** The lifecycle of the code itself, independent of where it points. */
+declare const linkStatusSchema: z.ZodEnum<["minted", "unclaimed", "claimed", "active", "void"]>;
+/** Which touchpoint of one physical object a row is. */
+declare const linkRoleSchema: z.ZodEnum<["chip", "qr"]>;
+/**
+ * The three destination columns, as a request body carries them.
+ *
+ * SHAPE ONLY. Which types a given caller may actually SET is a tier question,
+ * answered server-side against a tier the server derives itself — putting it
+ * here would mean a client could read the gate off the schema, and a schema
+ * cannot see who is asking.
+ *
+ * `destUrl` is capped but not URL-validated on purpose: the single gate is the
+ * server's external-URL parser, and a second, looser check here would only
+ * teach a client that a URL it will later refuse was accepted.
+ */
+declare const MAX_LINK_DEST_URL_LENGTH = 2048;
+declare const linkDestinationInputSchema: z.ZodObject<{
+    destinationType: z.ZodEnum<["auto", "profile", "hub_chooser", "external", "board"]>;
+    destProfileId: z.ZodOptional<z.ZodString>;
+    destUrl: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    destinationType: "auto" | "board" | "profile" | "hub_chooser" | "external";
+    destProfileId?: string | undefined;
+    destUrl?: string | undefined;
+}, {
+    destinationType: "auto" | "board" | "profile" | "hub_chooser" | "external";
+    destProfileId?: string | undefined;
+    destUrl?: string | undefined;
+}>;
+type LinkDestinationInput = z.infer<typeof linkDestinationInputSchema>;
+/**
+ * A destination the buyer chose BEFORE the object existed.
+ *
+ * Every field optional, including the discriminator, because "the buyer never
+ * opened the picker" is the overwhelmingly common state and has to be storable
+ * as silence rather than as an explicit default. Consumed once at fulfilment,
+ * where it may only ever SOFTEN — a routing preference must not fail a paid
+ * order.
+ */
+declare const linkDestinationIntentSchema: z.ZodObject<{
+    destinationType: z.ZodOptional<z.ZodEnum<["auto", "profile", "hub_chooser", "external", "board"]>>;
+    destProfileId: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    destUrl: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    destinationType?: "auto" | "board" | "profile" | "hub_chooser" | "external" | undefined;
+    destProfileId?: string | undefined;
+    destUrl?: string | undefined;
+}, {
+    destinationType?: "auto" | "board" | "profile" | "hub_chooser" | "external" | undefined;
+    destProfileId?: string | undefined;
+    destUrl?: string | undefined;
+}>;
+type LinkDestinationIntent = z.infer<typeof linkDestinationIntentSchema>;
 
-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, STYLE_SCHEMA_FOR_KIND, TEXT_LINE_FACTOR_EM, TEXT_MIN_EM_MM, type ValidationResult, type Violation, adminCardCreateSchema, bookingSchema, buttonObjectStyleSchema, 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, imageObjectStyleSchema, isFiniteTransform, materialSchema, mmToNearestChipAnchor, obbCorners, patternFamilySchema, physicalConfigSchema, physicalContentOverridesSchema, profileAccessTokenCreateSchema, profileBackgroundSchema, profileCreateSchema, profileLayoutSchema, profilePinVerifySchema, profileUpdateSchema, profileUserDataSchema, profileVisibilitySchema, qrModeSchema, rowTextStyleSchema, safeProfileLayout, sanitizeHttpUrl, sanitizeText, signupWithProfileSchema, socialLinksSchema, socialOverridesSchema, textAdvanceEm, textObjectStyleSchema, tipJarSchema, 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, type LinkDestinationInput, type LinkDestinationIntent, MAX_CTA_BUTTONS, MAX_LINK_DEST_URL_LENGTH, 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, STYLE_SCHEMA_FOR_KIND, TEXT_LINE_FACTOR_EM, TEXT_MIN_EM_MM, type ValidationResult, type Violation, adminCardCreateSchema, bookingSchema, buttonObjectStyleSchema, cardAssetSchema, cardDesignMaterialSchema, cardDesignPatternSchema, cardDesignSchema, cardElementSchema, cardElementsSchema, cardProfileUpdateSchema, cardUpdateSchema, chipAnchorToMm, chipPlacementMaxXY, comboIdSchema, configurationCreateSchema, configurationUpdateSchema, contactDetailTogglesSchema, contactExchangeSchema, cornersOnCard, createOrderSchema, ctaButtonSchema, ctaButtonsSchema, digitalConfigSchema, digitalVisibilitySchema, discOnCard, elementPrintability, elementTransformSchema, entrySourceSchema, footprintOf, hubConfigSchema, hubProfilesUpdateSchema, imageObjectStyleSchema, isFiniteTransform, linkDestinationInputSchema, linkDestinationIntentSchema, linkDestinationTypeSchema, linkRoleSchema, linkStatusSchema, materialSchema, mmToNearestChipAnchor, obbCorners, patternFamilySchema, physicalConfigSchema, physicalContentOverridesSchema, productTypeSchema, profileAccessTokenCreateSchema, profileBackgroundSchema, profileCreateSchema, profileLayoutSchema, profilePinVerifySchema, profileUpdateSchema, profileUserDataSchema, profileVisibilitySchema, qrModeSchema, rowTextStyleSchema, safeProfileLayout, sanitizeHttpUrl, sanitizeText, signupWithProfileSchema, socialLinksSchema, socialOverridesSchema, textAdvanceEm, textObjectStyleSchema, tipJarSchema, userDataSchema, validateConfiguration, validateDigitalConfig, validatePhysicalConfig, validateUserData, webAddressSchema };

package/dist/index.js

@@ -4,7 +4,11 @@ import {
   isTipProviderId,
   normalizeTipHandle,
   isBookingProviderId,
-  normalizeBookingHandle
+  normalizeBookingHandle,
+  PRODUCT_TYPES,
+  LINK_DESTINATION_TYPES,
+  LINK_STATUSES,
+  LINK_ROLES
 } from "@nfcard/types";
 
 // src/printability.ts
@@ -41,6 +45,9 @@ function obbCorners(t, wMm, hMm) {
   ];
   return local.map(([x, y]) => ({ x: t.xMm + x * c - y * s, y: t.yMm + x * s + y * c }));
 }
+function discOnCard(t, rMm, margin = EDGE_MARGIN_MM) {
+  return Math.abs(t.xMm) + rMm <= CARD_W_MM / 2 - margin + EPS && Math.abs(t.yMm) + rMm <= CARD_H_MM / 2 - margin + EPS;
+}
 function cornersOnCard(corners, margin = EDGE_MARGIN_MM) {
   const maxX = CARD_W_MM / 2 - margin;
   const maxY = CARD_H_MM / 2 - margin;
@@ -441,8 +448,8 @@ function elementPrintability(el, ctx) {
       break;
     }
   }
-  const fp = footprintOf(el);
-  if (!cornersOnCard(obbCorners(el.transform, fp.w, fp.h))) {
+  const onCard = el.type === "chip" ? discOnCard(el.transform, CHIP_RADIUS_MM * el.transform.scale) : cornersOnCard(obbCorners(el.transform, footprintOf(el).w, footprintOf(el).h));
+  if (!onCard) {
     push("elementOffCard", "The element extends past the printable card area.");
   }
   return out;
@@ -1173,6 +1180,17 @@ function validateConfiguration(data) {
   if (result.success) return { success: true, data: result.data };
   return { success: false, errors: formatZodErrors(result.error) };
 }
+var productTypeSchema = z2.enum(PRODUCT_TYPES);
+var linkDestinationTypeSchema = z2.enum(LINK_DESTINATION_TYPES);
+var linkStatusSchema = z2.enum(LINK_STATUSES);
+var linkRoleSchema = z2.enum(LINK_ROLES);
+var MAX_LINK_DEST_URL_LENGTH = 2048;
+var linkDestinationInputSchema = z2.object({
+  destinationType: linkDestinationTypeSchema,
+  destProfileId: z2.string().trim().min(1).max(64).optional(),
+  destUrl: z2.string().trim().max(MAX_LINK_DEST_URL_LENGTH).optional()
+});
+var linkDestinationIntentSchema = linkDestinationInputSchema.partial();
 export {
   ADVANCE_FALLBACK_EM,
   CARD_H_MM,
@@ -1183,6 +1201,7 @@ export {
   EMPTY_TEXT_FLOOR_EM,
   ITALIC_OVERHANG_EM,
   MAX_CTA_BUTTONS,
+  MAX_LINK_DEST_URL_LENGTH,
   MIN_WALL_MM,
   NFC_COIL_DIAMETER_MM,
   NFC_RADIAL_CLEARANCE_MM,
@@ -1216,6 +1235,7 @@ export {
   ctaButtonsSchema,
   digitalConfigSchema,
   digitalVisibilitySchema,
+  discOnCard,
   elementPrintability,
   elementTransformSchema,
   entrySourceSchema,
@@ -1224,12 +1244,18 @@ export {
   hubProfilesUpdateSchema,
   imageObjectStyleSchema,
   isFiniteTransform,
+  linkDestinationInputSchema,
+  linkDestinationIntentSchema,
+  linkDestinationTypeSchema,
+  linkRoleSchema,
+  linkStatusSchema,
   materialSchema,
   mmToNearestChipAnchor,
   obbCorners,
   patternFamilySchema,
   physicalConfigSchema,
   physicalContentOverridesSchema,
+  productTypeSchema,
   profileAccessTokenCreateSchema,
   profileBackgroundSchema,
   profileCreateSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nfcard/validation",
-  "version": "0.25.1",
+  "version": "0.26.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.20.0"
+    "@nfcard/types": "0.24.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0"

package/src/controlChars.test.ts

@@ -1,71 +1,71 @@
-import { describe, expect, it } from 'vitest';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { sanitizeHttpUrl, sanitizeText } from './index';
-
-/**
- * The character classes in `stripUnsafeChars` and `sanitizeText` used to be
- * written with LITERAL 0x00 / 0x1f / 0x7f bytes in the source.
- *
- * That was not a style problem. It made this file read as BINARY to ripgrep
- * ("found \0 byte around offset 2873"), so `grep`/`Grep` silently skipped it
- * and anyone searching for `sanitizeHttpUrl` concluded it did not exist. Worse,
- * a Prettier run, an editor "strip control characters" save, or a
- * `.gitattributes` filter would rewrite those classes without anyone noticing —
- * and `sanitizeHttpUrl` is the SECOND-OPINION gate that `parseExternalUrl` in
- * nfcard-api cross-checks itself against. The two disagreeing turns into a
- * blanket refusal of every external URL: an outage, from a formatter.
- *
- * The bytes are now `\x00` / `\x1f` / `\x7f` escapes — same semantics, plain
- * ASCII, greppable, formatter-proof. These tests keep it that way.
- */
-
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const SOURCE = fs.readFileSync(path.join(HERE, 'index.ts'));
-
-describe('the source file stays plain ASCII', () => {
-  it('contains NO literal control bytes — that is what made it read as binary', () => {
-    const offenders: string[] = [];
-    for (let i = 0; i < SOURCE.length; i++) {
-      const byte = SOURCE[i];
-      const isControl = byte === 0 || byte < 9 || (byte > 13 && byte < 32) || byte === 127;
-      if (isControl) offenders.push(`0x${byte.toString(16)} @ ${i}`);
-    }
-    expect(offenders).toEqual([]);
-  });
-
-  it('still declares the classes it always did, as escapes', () => {
-    const text = SOURCE.toString('utf8');
-    // ⚠️ Not a cosmetic assertion. `[ -<...]` — which is what these look like
-    // once the control bytes are eaten — is a RANGE over U+0020–U+003C that
-    // swallows `.` `/` `:` and every digit. That exact bug is on the record in
-    // this codebase; this pins the intended form so it cannot come back.
-    expect(text).toContain('/[\\x00-\\x1f\\x7f<>"\'`\\\\]/g');
-    expect(text).toContain('/[\\x00-\\x1f\\x7f]/g');
-  });
-});
-
-describe('the classes behave exactly as before the escape rewrite', () => {
-  const CONTROLS = ['\x00', '\x01', '\x1f', '\x7f'];
-
-  it.each(CONTROLS)('sanitizeHttpUrl strips %j out of a host', (ch) => {
-    expect(sanitizeHttpUrl(`https://exam${ch}ple.com/x`)).toBe('https://example.com/x');
-  });
-
-  it.each(CONTROLS)('sanitizeText strips %j', (ch) => {
-    expect(sanitizeText(`Ri${ch}csi`)).toBe('Ricsi');
-  });
-
-  it('still strips the HTML-ish characters beside them', () => {
-    expect(sanitizeHttpUrl('https://example.com/<script>')).toBe('https://example.com/script');
-  });
-
-  it('does NOT strip the printable characters a URL needs', () => {
-    // The guard against re-introducing the U+0020–U+003C range bug: every one
-    // of these sits inside that range and must survive.
-    expect(sanitizeHttpUrl('https://example.com/a.b/c-1?d=2&e=3')).toBe(
-      'https://example.com/a.b/c-1?d=2&e=3',
-    );
-  });
-});
+import { describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { sanitizeHttpUrl, sanitizeText } from './index';
+
+/**
+ * The character classes in `stripUnsafeChars` and `sanitizeText` used to be
+ * written with LITERAL 0x00 / 0x1f / 0x7f bytes in the source.
+ *
+ * That was not a style problem. It made this file read as BINARY to ripgrep
+ * ("found \0 byte around offset 2873"), so `grep`/`Grep` silently skipped it
+ * and anyone searching for `sanitizeHttpUrl` concluded it did not exist. Worse,
+ * a Prettier run, an editor "strip control characters" save, or a
+ * `.gitattributes` filter would rewrite those classes without anyone noticing —
+ * and `sanitizeHttpUrl` is the SECOND-OPINION gate that `parseExternalUrl` in
+ * nfcard-api cross-checks itself against. The two disagreeing turns into a
+ * blanket refusal of every external URL: an outage, from a formatter.
+ *
+ * The bytes are now `\x00` / `\x1f` / `\x7f` escapes — same semantics, plain
+ * ASCII, greppable, formatter-proof. These tests keep it that way.
+ */
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SOURCE = fs.readFileSync(path.join(HERE, 'index.ts'));
+
+describe('the source file stays plain ASCII', () => {
+  it('contains NO literal control bytes — that is what made it read as binary', () => {
+    const offenders: string[] = [];
+    for (let i = 0; i < SOURCE.length; i++) {
+      const byte = SOURCE[i];
+      const isControl = byte === 0 || byte < 9 || (byte > 13 && byte < 32) || byte === 127;
+      if (isControl) offenders.push(`0x${byte.toString(16)} @ ${i}`);
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it('still declares the classes it always did, as escapes', () => {
+    const text = SOURCE.toString('utf8');
+    // ⚠️ Not a cosmetic assertion. `[ -<...]` — which is what these look like
+    // once the control bytes are eaten — is a RANGE over U+0020–U+003C that
+    // swallows `.` `/` `:` and every digit. That exact bug is on the record in
+    // this codebase; this pins the intended form so it cannot come back.
+    expect(text).toContain('/[\\x00-\\x1f\\x7f<>"\'`\\\\]/g');
+    expect(text).toContain('/[\\x00-\\x1f\\x7f]/g');
+  });
+});
+
+describe('the classes behave exactly as before the escape rewrite', () => {
+  const CONTROLS = ['\x00', '\x01', '\x1f', '\x7f'];
+
+  it.each(CONTROLS)('sanitizeHttpUrl strips %j out of a host', (ch) => {
+    expect(sanitizeHttpUrl(`https://exam${ch}ple.com/x`)).toBe('https://example.com/x');
+  });
+
+  it.each(CONTROLS)('sanitizeText strips %j', (ch) => {
+    expect(sanitizeText(`Ri${ch}csi`)).toBe('Ricsi');
+  });
+
+  it('still strips the HTML-ish characters beside them', () => {
+    expect(sanitizeHttpUrl('https://example.com/<script>')).toBe('https://example.com/script');
+  });
+
+  it('does NOT strip the printable characters a URL needs', () => {
+    // The guard against re-introducing the U+0020–U+003C range bug: every one
+    // of these sits inside that range and must survive.
+    expect(sanitizeHttpUrl('https://example.com/a.b/c-1?d=2&e=3')).toBe(
+      'https://example.com/a.b/c-1?d=2&e=3',
+    );
+  });
+});

package/src/index.ts

@@ -4,6 +4,11 @@ import {
   normalizeTipHandle,
   isBookingProviderId,
   normalizeBookingHandle,
+  // NFCARD-330 - the Link vocabularies, derived rather than re-spelled.
+  PRODUCT_TYPES,
+  LINK_DESTINATION_TYPES,
+  LINK_STATUSES,
+  LINK_ROLES,
 } from '@nfcard/types'
 import { elementPrintability, mmToNearestChipAnchor } from './printability'
 import { profileLayoutSchema } from './profileLayout'
@@ -898,3 +903,64 @@ export function validateConfiguration(
   if (result.success) return { success: true, data: result.data }
   return { success: false, errors: formatZodErrors(result.error) }
 }
+
+// -- Link contracts (NFCARD-330, epic 307) ---------------------------------
+//
+// DELIBERATE DEPARTURE FROM THE HOUSE STYLE, and worth the paragraph. Every
+// other enum schema in this file spells its strings out literally
+// (`materialSchema`, `qrModeSchema`, `profileVisibilitySchema`), so each
+// vocabulary is written twice: once as a type in `@nfcard/types` and once here.
+// These derive from the const arrays instead.
+//
+// The whole reason NFCARD-330 exists is that the Link vocabularies had drifted
+// across three hand-copies. Landing them here as a fourth and fifth would be
+// re-creating the problem inside its own fix. `z.enum` accepts the readonly
+// tuples directly because they are declared `as const` and non-empty, so this
+// costs nothing and makes a new destination a one-line change in one file.
+
+/** What physical thing carries the code. Fulfilment dispatch, never routing. */
+export const productTypeSchema = z.enum(PRODUCT_TYPES)
+
+/** Where a tap goes. */
+export const linkDestinationTypeSchema = z.enum(LINK_DESTINATION_TYPES)
+
+/** The lifecycle of the code itself, independent of where it points. */
+export const linkStatusSchema = z.enum(LINK_STATUSES)
+
+/** Which touchpoint of one physical object a row is. */
+export const linkRoleSchema = z.enum(LINK_ROLES)
+
+/**
+ * The three destination columns, as a request body carries them.
+ *
+ * SHAPE ONLY. Which types a given caller may actually SET is a tier question,
+ * answered server-side against a tier the server derives itself — putting it
+ * here would mean a client could read the gate off the schema, and a schema
+ * cannot see who is asking.
+ *
+ * `destUrl` is capped but not URL-validated on purpose: the single gate is the
+ * server's external-URL parser, and a second, looser check here would only
+ * teach a client that a URL it will later refuse was accepted.
+ */
+export const MAX_LINK_DEST_URL_LENGTH = 2048
+
+export const linkDestinationInputSchema = z.object({
+  destinationType: linkDestinationTypeSchema,
+  destProfileId: z.string().trim().min(1).max(64).optional(),
+  destUrl: z.string().trim().max(MAX_LINK_DEST_URL_LENGTH).optional(),
+})
+
+export type LinkDestinationInput = z.infer<typeof linkDestinationInputSchema>
+
+/**
+ * A destination the buyer chose BEFORE the object existed.
+ *
+ * Every field optional, including the discriminator, because "the buyer never
+ * opened the picker" is the overwhelmingly common state and has to be storable
+ * as silence rather than as an explicit default. Consumed once at fulfilment,
+ * where it may only ever SOFTEN — a routing preference must not fail a paid
+ * order.
+ */
+export const linkDestinationIntentSchema = linkDestinationInputSchema.partial()
+
+export type LinkDestinationIntent = z.infer<typeof linkDestinationIntentSchema>

package/src/link.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import { LINK_DESTINATION_TYPES, PRODUCT_TYPES } from '@nfcard/types'
+import {
+  MAX_LINK_DEST_URL_LENGTH,
+  linkDestinationIntentSchema,
+  linkDestinationTypeSchema,
+  linkRoleSchema,
+  linkStatusSchema,
+  productTypeSchema,
+} from './index'
+
+/**
+ * NFCARD-330 — the Zod half of the Link contracts.
+ *
+ * The assertion that matters most is the DERIVATION one: these schemas are
+ * built from the `@nfcard/types` const arrays rather than re-spelling the
+ * strings, which is a deliberate departure from this package's house style and
+ * the whole reason the ticket exists.
+ */
+
+describe('the enum schemas', () => {
+  it('accept exactly the vocabulary and nothing else', () => {
+    for (const type of PRODUCT_TYPES) {
+      expect(productTypeSchema.safeParse(type).success).toBe(true)
+    }
+    expect(productTypeSchema.safeParse('poster').success).toBe(false)
+
+    for (const type of LINK_DESTINATION_TYPES) {
+      expect(linkDestinationTypeSchema.safeParse(type).success).toBe(true)
+    }
+    expect(linkDestinationTypeSchema.safeParse('hub').success).toBe(false)
+
+    expect(linkStatusSchema.safeParse('minted').success).toBe(true)
+    expect(linkStatusSchema.safeParse('dormant').success).toBe(false)
+    expect(linkRoleSchema.safeParse('qr').success).toBe(true)
+    expect(linkRoleSchema.safeParse('sticker').success).toBe(false)
+  })
+
+  // ⭐ THE DERIVATION. If someone "helpfully" rewrites these as literal
+  // z.enum(['card', …]) lists, the schema and the type can drift — which is the
+  // exact failure NFCARD-330 was filed to end. This asserts the two are the
+  // same set, so a one-sided edit fails here.
+  it('stay derived from the types package, not hand-copied', () => {
+    expect(productTypeSchema.options).toEqual([...PRODUCT_TYPES])
+    expect(linkDestinationTypeSchema.options).toEqual([...LINK_DESTINATION_TYPES])
+  })
+})
+
+describe('linkDestinationInputSchema / intent', () => {
+  it('accepts a destination with its matching target', () => {
+    expect(
+      linkDestinationIntentSchema.safeParse({ destinationType: 'profile', destProfileId: 'p1' })
+        .success,
+    ).toBe(true)
+    expect(
+      linkDestinationIntentSchema.safeParse({
+        destinationType: 'external',
+        destUrl: 'https://barberbros.hu/foglalas',
+      }).success,
+    ).toBe(true)
+  })
+
+  // "The buyer never opened the picker" is the overwhelmingly common state and
+  // has to be storable as silence, not as an explicit default.
+  it('accepts an entirely empty intent', () => {
+    expect(linkDestinationIntentSchema.safeParse({}).success).toBe(true)
+  })
+
+  it('refuses a destination type that does not exist', () => {
+    expect(linkDestinationIntentSchema.safeParse({ destinationType: 'hub' }).success).toBe(false)
+  })
+
+  // Capped, but NOT URL-validated: the one gate is the server's external-URL
+  // parser, and a second looser check here would teach a client that a URL the
+  // server will refuse was accepted.
+  it('caps the URL length without judging the URL', () => {
+    expect(
+      linkDestinationIntentSchema.safeParse({ destinationType: 'external', destUrl: 'not-a-url' })
+        .success,
+    ).toBe(true)
+    expect(
+      linkDestinationIntentSchema.safeParse({
+        destinationType: 'external',
+        destUrl: 'h'.repeat(MAX_LINK_DEST_URL_LENGTH + 1),
+      }).success,
+    ).toBe(false)
+  })
+
+  it('trims the targets so a padded value is stored clean', () => {
+    const parsed = linkDestinationIntentSchema.parse({
+      destinationType: 'profile',
+      destProfileId: '  p1  ',
+    })
+    expect(parsed.destProfileId).toBe('p1')
+  })
+})

package/src/parity.test.ts

@@ -26,14 +26,33 @@ import {
  * Regenerate (both sides together):
  *   node ../../nfcard-cardgen/tests/parity/gen_printability_parity.mjs
  *
- * Skips cleanly if nfcard-cardgen isn't checked out alongside (shared-only CI).
+ * Skips cleanly if nfcard-cardgen isn't checked out alongside (shared-only CI) — but says so
+ * out loud. A silent skip is the worst outcome here: the guard reads as green while the two
+ * implementations drift. Set `NFCARD_CARDGEN_DIR` when the sibling layout does not apply (a
+ * git worktree sits two levels deeper, so the relative guess misses).
  */
-const GOLDEN = fileURLToPath(
-  new URL('../../../nfcard-cardgen/tests/parity/printability_parity.json', import.meta.url),
-)
-const present = existsSync(GOLDEN)
+function resolveGolden(): string | null {
+  const rel = 'tests/parity/printability_parity.json'
+  const env = process.env.NFCARD_CARDGEN_DIR
+  const candidates = env
+    ? [`${env.replace(/[\\/]+$/, '')}/${rel}`]
+    : [
+        fileURLToPath(new URL(`../../../nfcard-cardgen/${rel}`, import.meta.url)),
+        fileURLToPath(new URL(`../../../../../nfcard-cardgen/${rel}`, import.meta.url)),
+      ]
+  return candidates.find((p) => existsSync(p)) ?? null
+}
+
+const GOLDEN = resolveGolden()
+const present = GOLDEN !== null
+if (!present) {
+  console.warn(
+    '[parity] SKIPPED — nfcard-cardgen/tests/parity/printability_parity.json not found. ' +
+      'Set NFCARD_CARDGEN_DIR to run the cross-language guard.',
+  )
+}
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const golden: any = present ? JSON.parse(readFileSync(GOLDEN, 'utf-8')) : { elementCases: [] }
+const golden: any = GOLDEN ? JSON.parse(readFileSync(GOLDEN, 'utf-8')) : { elementCases: [] }
 const TOL = 1e-9
 
 // Mirror cardgen `validate_elements`: per-element printability + the graph-level

package/src/printability.test.ts

@@ -5,6 +5,9 @@ import {
   ITALIC_OVERHANG_EM,
   TEXT_LINE_FACTOR_EM,
   elementPrintability,
+  discOnCard,
+  CHIP_RADIUS_MM,
+  chipPlacementMaxXY,
   footprintOf,
   textAdvanceEm,
   CARD_W_MM,
@@ -105,3 +108,47 @@ describe('NFCARD-530 — elementOffCard verdict with the accurate estimate', ()
     expect(elementPrintability(el, ctx).map((v) => v.code)).toContain('elementOffCard')
   })
 })
+
+// ── NFCARD-841 — the chip is a DISC, so its on-card verdict is rotation-invariant ──
+describe('chip on-card check (NFCARD-841)', () => {
+  const chip = (xMm: number, yMm: number, rotationDeg = 0, scale = 1): CardElement =>
+    ({ id: 'c1', type: 'chip', shape: 0, transform: { xMm, yMm, rotationDeg, scale, z: 0 } }) as unknown as CardElement
+  const codes = (el: CardElement) => elementPrintability(el, { assetsById: new Map() }).map((v) => v.code)
+
+  it('rotation NEVER changes a chip verdict — it used to, at every angle past scale 1.31', () => {
+    for (const scale of [1, 1.2, 1.4, 1.6]) {
+      for (const [x, y] of [[0, 0], [10, 2], [-18, -2], [26.55, 2.5]] as const) {
+        const at0 = codes(chip(x, y, 0, scale))
+        for (const rot of [15, 30, 45, 60, 90, 180, 275]) {
+          expect(codes(chip(x, y, rot, scale)), `x${x} y${y} s${scale} rot${rot}`).toEqual(at0)
+        }
+      }
+    }
+  })
+
+  it('the case that had NO legal position: 45° at scale 1.6, anywhere on the card', () => {
+    // Before the fix the square's half-diagonal (13.75·1.6·√2 = 31.1 mm) exceeded the 25.5 mm
+    // rim, so elementOffCard fired at EVERY centre — a design no placement could rescue.
+    expect(codes(chip(0, 0, 45, 1.6))).toEqual([])
+    expect(codes(chip(0, 0, 0, 1.6))).toEqual([]) // …and it always agreed with the unrotated twin
+  })
+
+  it('at rotation 0 the new bound is EXACTLY the old one — no design changes verdict', () => {
+    // The square's half-height IS the disc radius, so this is a pure no-op where it used to be
+    // correct. Walk the y axis across the boundary and check the flip lands on the same value.
+    const rimMaxY = 54 / 2 - 1.5 - CHIP_RADIUS_MM // the old square bound at scale 1 = 11.75
+    expect(discOnCard(chip(0, rimMaxY).transform, CHIP_RADIUS_MM)).toBe(true)
+    expect(discOnCard(chip(0, rimMaxY + 0.01).transform, CHIP_RADIUS_MM)).toBe(false)
+  })
+
+  it('the ENVELOPE still binds first, so this did not loosen the pocket rule', () => {
+    // chipPlacementMaxXY is the disc bound minus the 1 mm pocket buffer, at every scale — so a
+    // chip that clears the envelope can never trip elementOffCard, and NFCARD-421 stays fixed.
+    for (const scale of [1, 1.3, 1.6]) {
+      const env = chipPlacementMaxXY(scale)
+      expect(env.maxY).toBeCloseTo(54 / 2 - 1.5 - CHIP_RADIUS_MM * scale - 1, 6)
+      expect(codes(chip(0, env.maxY, 45, scale))).toEqual([]) // on the envelope edge: legal
+      expect(codes(chip(0, env.maxY + 0.02, 45, scale))).toEqual(['chipOutsideEnvelope']) // just past: ONLY the envelope
+    }
+  })
+})

package/src/printability.ts

@@ -86,6 +86,27 @@ export function obbCorners(t: ElementTransform, wMm: number, hMm: number): Pt[]
   return local.map(([x, y]) => ({ x: t.xMm + x * c - y * s, y: t.yMm + x * s + y * c }))
 }
 
+/** Is a DISC of radius `rMm` centred at `t` inside the ID-1 rim minus the safety margin?
+ *
+ *  NFCARD-841 — the chip is physically a DISC, but {@link footprintOf} gives it the 27.5 mm
+ *  bounding SQUARE, so running it through {@link cornersOnCard} + {@link obbCorners} made its
+ *  on-card verdict ROTATION-SENSITIVE. A circle covers the same area at every angle, so that is
+ *  wrong in principle; it was also wrong in practice, because past scale ≈1.31 the square's
+ *  half-diagonal (13.75·s·√2) exceeds the 25.5 mm rim and a 45°-rotated chip was rejected at
+ *  EVERY position on the card — unorderable with no placement that could save it.
+ *
+ *  ⚠ At rotation 0 this is EXACTLY the old bound (the square's half-height IS the radius), so no
+ *  previously-legal design changes verdict and no previously-illegal one is let through. The only
+ *  behaviour that moves is the rotation artifact.
+ *
+ *  Rotation-invariant by construction — it takes no angle. Mirrors cardgen `disc_on_card`. */
+export function discOnCard(t: ElementTransform, rMm: number, margin = EDGE_MARGIN_MM): boolean {
+  return (
+    Math.abs(t.xMm) + rMm <= CARD_W_MM / 2 - margin + EPS &&
+    Math.abs(t.yMm) + rMm <= CARD_H_MM / 2 - margin + EPS
+  )
+}
+
 /** Are all corners inside the ID-1 rim minus the safety margin? */
 export function cornersOnCard(corners: Pt[], margin = EDGE_MARGIN_MM): boolean {
   const maxX = CARD_W_MM / 2 - margin
@@ -323,8 +344,14 @@ export function elementPrintability(el: CardElement, ctx: PrintabilityCtx): Viol
     }
   }
 
-  const fp = footprintOf(el)
-  if (!cornersOnCard(obbCorners(el.transform, fp.w, fp.h))) {
+  // NFCARD-841 — the CHIP is judged as the disc it is, not as its bounding square, so the
+  // verdict cannot depend on an angle a circle does not have. Every other element keeps the OBB
+  // check: their footprints really are rectangles and rotation really does move their corners.
+  const onCard =
+    el.type === 'chip'
+      ? discOnCard(el.transform, CHIP_RADIUS_MM * el.transform.scale)
+      : cornersOnCard(obbCorners(el.transform, footprintOf(el).w, footprintOf(el).h))
+  if (!onCard) {
     push('elementOffCard', 'The element extends past the printable card area.')
   }
   return out