@7365admin1/layer-common 4.96.0 → 4.97.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @iservice365/layer-common
 
+## 4.97.0
+
+### Minor Changes
+
+- e3ade83: Vehicle QR stickers: nine cut-out shapes (circle, heart, star badge, hexagon, octagon, shield, speech bubble, rounded square, car) with a live picture of each, a "Show cut lines" switch, "Scan me" wording, and a cutting layout - 12 shapes or 16 cards per A4 sheet with 4 / 3 mm cutting gaps, + cut marks and a 5 mm printer margin. The QR inside every shape is unchanged (same content, 32 mm, error correction Q, 4-module quiet zone); the rest of the shape is a dot pattern that is decode-tested not to confuse scanners. Round-dot codes now draw the small alignment square solid and rounded-square codes join neighbouring modules, which makes both easier to scan.
+
 ## 4.96.0
 
 ### Minor Changes
@@ -2076,11 +2082,11 @@
   `utils/console-tier.ts` + `composables/useConsoleTier.ts` mirror the server's
   own rule from two endpoints the console already calls, unprojected:
 
-                                                                                                                                                                                                                                                                                                                                                                                      GET /api/members/user/:user/app/admin    the Seven365 staff membership
-                                                                                                                                                                                                                                                                                                                                                                                      GET /api/roles/id/:role                  that membership's role document
+                                                                                                                                                                                                                                                                                                                                                                                        GET /api/members/user/:user/app/admin    the Seven365 staff membership
+                                                                                                                                                                                                                                                                                                                                                                                        GET /api/roles/id/:role                  that membership's role document
 
-                                                                                                                                                                                                                                                                                                                                                                                      owner  = member.type === "admin" && role.type === "admin" && role.default === true
-                                                                                                                                                                                                                                                                                                                                                                                      staff  = member.type === "admin" && role.type === "admin"
+                                                                                                                                                                                                                                                                                                                                                                                        owner  = member.type === "admin" && role.type === "admin" && role.default === true
+                                                                                                                                                                                                                                                                                                                                                                                        staff  = member.type === "admin" && role.type === "admin"
 
   `role.default` is the marker because it is the only property of a platform
   staff role no API caller can set - `role.controller.ts` validates create and

package/components/VehicleQrStickerDialog.vue

@@ -92,9 +92,6 @@
               <v-select v-model="design.theme" :items="STICKER_THEMES" item-value="id" label="Colours" density="compact"
                 hide-details />
             </v-col>
-            <v-col cols="12" sm="6" md="4" lg>
-              <v-select v-model="design.frame" :items="FRAME_OPTIONS" label="Sticker shape" density="compact" hide-details />
-            </v-col>
             <v-col cols="12" sm="6" md="4" lg>
               <v-select v-model="design.label" :items="LABEL_OPTIONS" label="Words under the plate" density="compact"
                 hide-details />
@@ -103,6 +100,26 @@
               <v-btn variant="text" size="small" class="text-none" @click="resetDesign">Back to the standard look</v-btn>
             </v-col>
           </v-row>
+          <div class="text-body-2 mt-3 mb-1">Sticker shape</div>
+          <div class="shape-picker" role="radiogroup" aria-label="Sticker shape" data-test="vehicle-qr-shapes">
+            <button v-for="s in shapeThumbs" :key="s.value" type="button" role="radio" class="shape-option"
+              :class="{ 'shape-option--on': design.frame === s.value }" :aria-checked="design.frame === s.value"
+              :data-shape="s.value" @click="design.frame = s.value">
+              <img class="shape-thumb" :src="s.src" alt="" />
+              <span class="text-caption">{{ s.title }}</span>
+            </button>
+          </div>
+          <v-switch v-model="design.cutLines" label="Show cut lines" color="primary" density="compact" hide-details inset
+            class="mt-1" data-test="vehicle-qr-cut-lines" />
+          <v-alert type="info" variant="tonal" density="compact" class="mt-1" data-test="vehicle-qr-cut-guide">
+            <div class="font-weight-medium">{{ sheetSummary(design.frame) }}.</div>
+            <div>Print at 100% ("Actual size" in the print window), not "Fit to page", so the QR code stays full size.</div>
+            <div>
+              How to cut: first cut the sheet into pieces through the middle of the gaps (the small + marks show where),
+              then cut round each sticker {{ design.cutLines ? "on the light-grey line" : "along its edge" }} - with scissors
+              or a cutting machine. Cut off the strip with the unit and owner before pasting.
+            </div>
+          </v-alert>
           <iframe ref="frame" title="Sticker sheet preview" :srcdoc="docHtml" class="sticker-preview mt-3" />
         </template>
       </v-card-text>
@@ -136,6 +153,7 @@ import {
   idsForRequest,
   installerLine,
   setIds,
+  sheetSummary,
   stickerPlateRows,
   stickerWarning,
   type StickerItem,
@@ -145,8 +163,8 @@ import {
   DEFAULT_STICKER_DESIGN,
   DOT_OPTIONS,
   EYE_OPTIONS,
-  FRAME_OPTIONS,
   LABEL_OPTIONS,
+  SHAPE_OPTIONS,
   QR_ECC,
   STICKER_THEMES,
   normalizeDesign,
@@ -206,6 +224,18 @@ function resetDesign() {
   Object.assign(design, DEFAULT_STICKER_DESIGN);
 }
 
+// A small live picture of every shape in the current dots / corners / colours.
+const sampleCode = QRCode.create("S365V:SamplePreviewToken0000", {
+  errorCorrectionLevel: QR_ECC as QRCode.QRCodeErrorCorrectionLevel,
+}).modules;
+const shapeThumbs = computed(() => {
+  const look = normalizeDesign(design);
+  return SHAPE_OPTIONS.map((o) => ({
+    ...o,
+    src: `data:image/svg+xml;charset=utf-8,${encodeURIComponent(stickerFaceSvg(sampleCode, { ...look, frame: o.value, cutLines: false }))}`,
+  }));
+});
+
 const allOnPageTicked = computed(() => plates.value.length > 0 && plates.value.every((p) => selected.value.includes(p.id)));
 const someOnPageTicked = computed(() => plates.value.some((p) => selected.value.includes(p.id)));
 
@@ -306,6 +336,36 @@ function print() {
 </script>
 
 <style scoped>
+.shape-picker {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(92px, 1fr));
+  gap: 8px;
+}
+.shape-option {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 2px;
+  padding: 6px 4px;
+  border: 1px solid rgba(var(--v-border-color), var(--v-border-opacity));
+  border-radius: 8px;
+  background: #f4f4f4;
+  cursor: pointer;
+}
+.shape-option--on {
+  border: 2px solid rgb(var(--v-theme-primary));
+  background: rgba(var(--v-theme-primary), 0.08);
+}
+.shape-option:focus-visible {
+  outline: 2px solid rgb(var(--v-theme-primary));
+  outline-offset: 2px;
+}
+.shape-thumb {
+  display: block;
+  width: 64px;
+  height: 64px;
+  object-fit: contain;
+}
 .sticker-preview {
   width: 100%;
   height: 460px;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "4.96.0",
+  "version": "4.97.0",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "//files": "What a consumer extending this layer actually loads. Without this npm ships the whole working tree - the changesets, the CI workflows, the render harness in tools/ and any scratch directory that happened to exist at publish time. Nuxt resolves a layer by directory, so every runtime directory below has to stay listed; adding a new top-level runtime directory means adding it here too.",

package/utils/vehicle-qr-design.ts

@@ -13,12 +13,31 @@ export type QrMatrix = { size: number; get(row: number, col: number): number | b
 
 export type DotShape = "square" | "rounded" | "dots";
 export type EyeShape = "square" | "rounded" | "circle";
-export type FrameShape = "rounded" | "square" | "soft" | "arch" | "ticket";
-export type LabelChoice = "app" | "verify" | "site" | "none";
+/** Cut-out shapes: the QR sits whole inside, the rest of the shape is a dot pattern. */
+export type SilhouetteShape =
+  | "circle"
+  | "heart"
+  | "star"
+  | "hexagon"
+  | "octagon"
+  | "shield"
+  | "bubble"
+  | "roundsquare"
+  | "car";
+export type FrameShape = "rounded" | "square" | "soft" | "arch" | "ticket" | SilhouetteShape;
+export type LabelChoice = "app" | "verify" | "scanme" | "site" | "none";
 
 export type StickerTheme = { id: string; title: string; ink: string; eye: string; paper: string };
 
-export type StickerDesign = { dots: DotShape; eyes: EyeShape; theme: string; frame: FrameShape; label: LabelChoice };
+export type StickerDesign = {
+  dots: DotShape;
+  eyes: EyeShape;
+  theme: string;
+  frame: FrameShape;
+  label: LabelChoice;
+  /** A thin grey line around each sticker to cut along. */
+  cutLines?: boolean;
+};
 
 export const DOT_OPTIONS: { value: DotShape; title: string }[] = [
   { value: "square", title: "Squares (classic)" },
@@ -40,9 +59,29 @@ export const FRAME_OPTIONS: { value: FrameShape; title: string }[] = [
   { value: "ticket", title: "Ticket (cut corners)" },
 ];
 
+export const SILHOUETTE_OPTIONS: { value: SilhouetteShape; title: string }[] = [
+  { value: "circle", title: "Circle" },
+  { value: "heart", title: "Heart" },
+  { value: "star", title: "Star badge" },
+  { value: "hexagon", title: "Hexagon" },
+  { value: "octagon", title: "Octagon" },
+  { value: "shield", title: "Shield" },
+  { value: "bubble", title: "Speech bubble" },
+  { value: "roundsquare", title: "Rounded square" },
+  { value: "car", title: "Car" },
+];
+
+/** Every shape the user can pick: the cards first, then the cut-out shapes. */
+export const SHAPE_OPTIONS: { value: FrameShape; title: string }[] = [...FRAME_OPTIONS, ...SILHOUETTE_OPTIONS];
+
+export function isSilhouette(frame: unknown): frame is SilhouetteShape {
+  return SILHOUETTE_OPTIONS.some((o) => o.value === frame);
+}
+
 export const LABEL_OPTIONS: { value: LabelChoice; title: string }[] = [
   { value: "app", title: "Scan with iSecure365 / iMA365" },
   { value: "verify", title: "Scan to verify vehicle" },
+  { value: "scanme", title: "Scan me" },
   { value: "site", title: "Site name" },
   { value: "none", title: "No extra words" },
 ];
@@ -64,6 +103,7 @@ export const DEFAULT_STICKER_DESIGN: StickerDesign = {
   theme: "black",
   frame: "rounded",
   label: "app",
+  cutLines: true,
 };
 
 /** A saved or typed-in design with anything unknown replaced by the default. */
@@ -76,8 +116,9 @@ export function normalizeDesign(raw: unknown): StickerDesign {
     dots: pick(r.dots, DOT_OPTIONS, d.dots),
     eyes: pick(r.eyes, EYE_OPTIONS, d.eyes),
     theme: STICKER_THEMES.some((t) => t.id === r.theme) ? String(r.theme) : d.theme,
-    frame: pick(r.frame, FRAME_OPTIONS, d.frame),
+    frame: pick(r.frame, SHAPE_OPTIONS, d.frame),
     label: pick(r.label, LABEL_OPTIONS, d.label),
+    cutLines: typeof r.cutLines === "boolean" ? r.cutLines : true,
   };
 }
 
@@ -110,15 +151,203 @@ const STROKE = 0.35;
 /** A rectangle with per-corner radii [tl, tr, br, bl], or concave cut corners. */
 export type Box = { t: "box"; x: number; y: number; w: number; h: number; r?: number[]; notch?: number };
 export type Circle = { t: "circle"; cx: number; cy: number; r: number };
-export type Shape = Box | Circle;
+/** A closed outline, points in mm (the cut-out shapes). */
+export type Poly = { t: "poly"; pts: [number, number][] };
+export type Shape = Box | Circle | Poly;
 /** A filled shape; `hole` is cut out of it (rings, the frame line). */
 export type Paint = { shape: Shape; hole?: Shape; fill: string };
 
 /** Top of the QR on the card: lower on the badge so the round top keeps clear of the code. */
 export function qrTop(frame: FrameShape): number {
+  if (isSilhouette(frame)) return silhouetteLayout(frame).qrTop;
   return frame === "arch" ? 7 : 2.5;
 }
 
+/** Size of the sticker face in mm. */
+export function cardSize(frame: FrameShape): { w: number; h: number } {
+  return isSilhouette(frame) ? { w: SHAPE_W, h: SHAPE_H } : { w: CARD_W, h: CARD_H };
+}
+
+// ---- cut-out shapes (all in mm; each fits a 62 x 58 box) ---------------------
+
+export const SHAPE_W = 62;
+export const SHAPE_H = 58;
+/** The 32 mm QR square keeps at least this much paper to the shape's edge, so a slightly-off cut never eats the quiet zone. */
+export const SHAPE_EDGE_MARGIN = 1;
+/** The box under the QR for the plate number (and the optional words). */
+export const BAND_H = 8.5;
+const BAND_MIN_W = 24;
+const BAND_MAX_W = 36;
+/** Share of the allowed (chessboard) pattern cells that get a dot. */
+const PATTERN_DENSITY = 0.7;
+
+type Pt = [number, number];
+const MID = SHAPE_W / 2;
+
+function arcPts(cx: number, cy: number, r: number, a0: number, a1: number, steps = 24): Pt[] {
+  return Array.from({ length: steps + 1 }, (_, i) => {
+    const a = a0 + ((a1 - a0) * i) / steps;
+    return [cx + r * Math.cos(a), cy + r * Math.sin(a)] as Pt;
+  });
+}
+
+/** Right half (top middle -> bottom middle, clockwise) plus its mirror image = the whole outline. */
+const mirror = (half: Pt[]): Pt[] => [...half, ...half.slice().reverse().map(([x, y]) => [SHAPE_W - x, y] as Pt)];
+
+function roundRectPts(x: number, y: number, w: number, h: number, r: number): Pt[] {
+  const q = Math.PI / 2;
+  return [
+    ...arcPts(x + r, y + r, r, 2 * q, 3 * q, 8),
+    ...arcPts(x + w - r, y + r, r, 3 * q, 4 * q, 8),
+    ...arcPts(x + w - r, y + h - r, r, 0, q, 8),
+    ...arcPts(x + r, y + h - r, r, q, 2 * q, 8),
+  ];
+}
+
+function regularPts(sides: number, r: number, cx: number, cy: number, start: number): Pt[] {
+  return Array.from({ length: sides }, (_, i) => {
+    const a = start + (i * 2 * Math.PI) / sides;
+    return [cx + r * Math.cos(a), cy + r * Math.sin(a)] as Pt;
+  });
+}
+
+function bezierPts(p0: Pt, c: Pt, p1: Pt, steps = 20): Pt[] {
+  return Array.from({ length: steps + 1 }, (_, i) => {
+    const t = i / steps;
+    const u = 1 - t;
+    return [u * u * p0[0] + 2 * u * t * c[0] + t * t * p1[0], u * u * p0[1] + 2 * u * t * c[1] + t * t * p1[1]] as Pt;
+  });
+}
+
+function heartPts(): Pt[] {
+  // Two round lobes and a point; lobes wide enough that the 32 mm QR fits between them.
+  const c = 11;
+  const r = 20;
+  const cx = MID + c;
+  const tip: Pt = [MID, SHAPE_H];
+  const base = Math.atan2(tip[1] - r, tip[0] - cx);
+  const tangent = base - Math.acos(r / Math.hypot(tip[0] - cx, tip[1] - r));
+  const dip = Math.atan2(-Math.sqrt(r * r - c * c), -c);
+  return mirror([...arcPts(cx, r, r, dip, tangent, 48), tip]);
+}
+
+function starPts(): Pt[] {
+  // A star badge (seal): 14 short points round a circle. A thin five-point
+  // star has no room for a whole 32 mm code at this size.
+  const R = SHAPE_H / 2;
+  return Array.from({ length: 28 }, (_, i) => {
+    const a = -Math.PI / 2 + (i * Math.PI) / 14;
+    const k = i % 2 ? 0.88 * R : R;
+    return [MID + k * Math.cos(a), R + k * Math.sin(a)] as Pt;
+  });
+}
+
+function bubblePts(): Pt[] {
+  // Rounded box with a tail at the bottom left.
+  const [x, y, w, h, r] = [1, 1, 60, 47, 9];
+  const box = roundRectPts(x, y, w, h, r);
+  const split = 27; // first point of the bottom-left corner arc
+  const tail: Pt[] = [[25, y + h], [12, SHAPE_H], [17, y + h]];
+  return [...box.slice(0, split), ...tail, ...box.slice(split)];
+}
+
+function carPts(): Pt[] {
+  // Front view: roof, windscreen, wing mirrors, body and the two front wheels.
+  return mirror([
+    [MID, 2.5], [44.5, 2.5], [46.8, 3.2], [47.8, 4.6], [54, 20.5],
+    [56, 20.2], [60.6, 19.2], [61.6, 21], [61.4, 23], [59.4, 24.2],
+    [60.6, 26], [61.5, 29.5], [61.5, 47], [60.2, 49],
+    [58.5, 49], [58.5, 56.2], [57.6, 57.4], [49.4, 57.4], [48.5, 56.2], [48.5, 49.8], [MID, 49.8],
+  ]);
+}
+
+const SILHOUETTE_BUILDERS: Record<SilhouetteShape, () => Pt[]> = {
+  circle: () => arcPts(MID, SHAPE_H / 2, SHAPE_H / 2, 0, 2 * Math.PI, 144).slice(0, -1),
+  heart: heartPts,
+  star: starPts,
+  hexagon: () => regularPts(6, MID, MID, SHAPE_H / 2, 0),
+  octagon: () => regularPts(8, SHAPE_H / 2 / Math.cos(Math.PI / 8), MID, SHAPE_H / 2, Math.PI / 8),
+  shield: () =>
+    mirror([
+      [MID, 1],
+      [56, 1],
+      ...arcPts(56, 5, 4, -Math.PI / 2, 0, 6).slice(1),
+      [60, 28],
+      ...bezierPts([60, 28], [60, 48], [MID, SHAPE_H]).slice(1),
+    ]),
+  bubble: bubblePts,
+  roundsquare: () => roundRectPts(2, 0, 58, 58, 14),
+  car: carPts,
+};
+
+export function pointInPoly(pts: Pt[], x: number, y: number): boolean {
+  let inside = false;
+  for (let i = 0, j = pts.length - 1; i < pts.length; j = i++) {
+    const [xi, yi] = pts[i];
+    const [xj, yj] = pts[j];
+    if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+}
+
+/** True when the rectangle (edge sampled every 0.5 mm) is inside the outline and no point of the outline pokes into it. */
+export function rectInside(pts: Pt[], x: number, y: number, w: number, h: number): boolean {
+  if (pts.some(([px, py]) => px > x && px < x + w && py > y && py < y + h)) return false;
+  const steps = Math.ceil(Math.max(w, h) / 0.5);
+  for (let i = 0; i <= steps; i++) {
+    const tx = x + (w * i) / steps;
+    const ty = y + (h * i) / steps;
+    if (!pointInPoly(pts, tx, y) || !pointInPoly(pts, tx, y + h) || !pointInPoly(pts, x, ty) || !pointInPoly(pts, x + w, ty)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export type SilhouetteLayout = { pts: Pt[]; qrTop: number; band: { x: number; y: number; w: number; h: number } };
+const layoutCache = new Map<SilhouetteShape, SilhouetteLayout>();
+
+/**
+ * Where the 32 mm QR and the plate box go inside a cut-out shape: the widest
+ * plate box that fits, then the middle of the heights where both fit. The QR
+ * keeps SHAPE_EDGE_MARGIN of paper to the edge; the plate box 0.5 mm.
+ */
+export function silhouetteLayout(shape: SilhouetteShape): SilhouetteLayout {
+  const cached = layoutCache.get(shape);
+  if (cached) return cached;
+  const pts = SILHOUETTE_BUILDERS[shape]();
+  const e = SHAPE_EDGE_MARGIN;
+  const x0 = (SHAPE_W - QR_MM) / 2;
+  let best = { w: 0, tops: [] as number[] };
+  for (let top = e; top + QR_MM + BAND_H <= SHAPE_H; top += 0.25) {
+    if (!rectInside(pts, x0 - e, top - e, QR_MM + 2 * e, QR_MM + 2 * e)) continue;
+    let w = BAND_MAX_W;
+    while (w >= BAND_MIN_W && !rectInside(pts, MID - w / 2 - 0.5, top + QR_MM - 0.5, w + 1, BAND_H + 1)) w -= 1;
+    if (w < BAND_MIN_W || w < best.w) continue;
+    if (w > best.w) best = { w, tops: [] };
+    best.tops.push(top);
+  }
+  if (!best.tops.length) throw new Error(`QR does not fit the ${shape} shape`);
+  const top = best.tops[Math.floor(best.tops.length / 2)];
+  const layout = { pts, qrTop: top, band: { x: MID - best.w / 2, y: top + QR_MM, w: best.w, h: BAND_H } };
+  layoutCache.set(shape, layout);
+  return layout;
+}
+
+/**
+ * Same dots every time for a cell (a fixed hash, no randomness between prints).
+ * Dots only sit on every other cell, like a chessboard, so no two ever touch
+ * side by side: even blurred, a row of them never joins into the solid bars a
+ * scanner takes for a QR corner.
+ */
+function patternDot(row: number, col: number): boolean {
+  if ((row + col) % 2 !== 0) return false;
+  let h = Math.imul(row + 1000, 73856093) ^ Math.imul(col + 1000, 19349663);
+  h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
+  h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+  return ((h ^ (h >>> 16)) >>> 0) / 4294967296 < PATTERN_DENSITY;
+}
+
 function cardBox(frame: FrameShape, inset: number): Box {
   const x = inset;
   const w = CARD_W - inset * 2;
@@ -147,28 +376,58 @@ export function stickerFacePaints(matrix: QrMatrix, design: StickerDesign): Pain
   const theme = stickerTheme(design.theme);
   const n = matrix.size;
   const m = QR_MM / (n + QUIET_MODULES * 2);
-  const ox = (CARD_W - QR_MM) / 2 + QUIET_MODULES * m;
+  const ox = (cardSize(design.frame).w - QR_MM) / 2 + QUIET_MODULES * m;
   const oy = qrTop(design.frame) + QUIET_MODULES * m;
-  const paints: Paint[] = [
-    { shape: cardBox(design.frame, 0), fill: theme.paper },
-    { shape: cardBox(design.frame, 0), hole: cardBox(design.frame, STROKE), fill: theme.ink },
-  ];
+  const paints: Paint[] = [];
+  if (isSilhouette(design.frame)) {
+    const { pts, band } = silhouetteLayout(design.frame);
+    paints.push({ shape: { t: "poly", pts }, fill: theme.paper });
+    // The rest of the shape: small round dots on the QR's grid, kept off the
+    // quiet zone, the plate box and the edge. Small separate dots never join
+    // into the solid bars a scanner looks for in a QR corner.
+    const near = 0.4; // mm of paper kept inside the edge
+    const clear = 1.2; // mm of paper kept round the plate box
+    const clearRing = QUIET_MODULES + 3; // pattern starts three modules beyond the quiet zone
+    for (let row = Math.floor(-oy / m) - 1; oy + row * m < SHAPE_H; row++) {
+      for (let col = Math.floor(-ox / m) - 1; ox + col * m < SHAPE_W; col++) {
+        if (row >= -clearRing && row < n + clearRing && col >= -clearRing && col < n + clearRing) continue;
+        if (!patternDot(row, col)) continue;
+        const x = ox + col * m;
+        const y = oy + row * m;
+        if (x + m > band.x - clear && x < band.x + band.w + clear && y + m > band.y - clear && y < band.y + band.h + clear) continue;
+        const corners: Pt[] = [[x - near, y - near], [x + m + near, y - near], [x - near, y + m + near], [x + m + near, y + m + near]];
+        if (!corners.every(([px, py]) => pointInPoly(pts, px, py))) continue;
+        paints.push({ shape: { t: "circle", cx: x + m / 2, cy: y + m / 2, r: m * 0.28 }, fill: theme.ink });
+      }
+    }
+  } else {
+    paints.push(
+      { shape: cardBox(design.frame, 0), fill: theme.paper },
+      { shape: cardBox(design.frame, 0), hole: cardBox(design.frame, STROKE), fill: theme.ink },
+    );
+  }
   const box = (x: number, y: number, w: number, h: number, rad = 0): Box => ({ t: "box", x, y, w, h, r: [rad, rad, rad, rad] });
 
+  // Round dots break the small alignment square (bottom right) into a ring of
+  // separate dots that some readers miss, so with dots it is drawn solid.
+  // ponytail: versions 2-6 only (one alignment square); the sticker payload is version 3.
+  const version = (n - 17) / 4;
+  const align = design.dots === "dots" && version >= 2 && version <= 6 ? n - 7 : -1;
+  const inAlign = (row: number, col: number) => align > 0 && Math.abs(row - align) <= 2 && Math.abs(col - align) <= 2;
+
   for (let row = 0; row < n; row++) {
     for (let col = 0; col < n; col++) {
-      if (!matrix.get(row, col) || isFinder(n, row, col)) continue;
+      if (!matrix.get(row, col) || isFinder(n, row, col) || inAlign(row, col)) continue;
       const x = ox + col * m;
       const y = oy + row * m;
       if (design.dots === "dots") {
-        paints.push({ shape: { t: "circle", cx: x + m / 2, cy: y + m / 2, r: m * 0.45 }, fill: theme.ink });
-      } else if (design.dots === "rounded") {
-        paints.push({ shape: box(x, y, m, m, m * 0.3), fill: theme.ink });
+        paints.push({ shape: { t: "circle", cx: x + m / 2, cy: y + m / 2, r: m * 0.48 }, fill: theme.ink });
       } else {
         // ponytail: one rect per horizontal run, so adjacent squares never show a hairline seam
+        // (rounded: a run is one pill, no notches between neighbours for a camera to trip on)
         let end = col;
-        while (end + 1 < n && matrix.get(row, end + 1) && !isFinder(n, row, end + 1)) end++;
-        paints.push({ shape: box(x, y, (end - col + 1) * m, m), fill: theme.ink });
+        while (end + 1 < n && matrix.get(row, end + 1) && !isFinder(n, row, end + 1) && !inAlign(row, end + 1)) end++;
+        paints.push({ shape: box(x, y, (end - col + 1) * m, m, design.dots === "rounded" ? m * 0.3 : 0), fill: theme.ink });
         col = end;
       }
     }
@@ -192,6 +451,12 @@ export function stickerFacePaints(matrix: QrMatrix, design: StickerDesign): Pain
       paints.push({ shape: box(x + 2 * m, y + 2 * m, 3 * m, 3 * m, round ? 0.9 * m : 0), fill: theme.eye });
     }
   }
+  if (align > 0) {
+    const x = ox + (align - 2) * m;
+    const y = oy + (align - 2) * m;
+    paints.push({ shape: box(x, y, 5 * m, 5 * m, 1.2 * m), hole: box(x + m, y + m, 3 * m, 3 * m, 0.6 * m), fill: theme.ink });
+    paints.push({ shape: { t: "circle", cx: x + 2.5 * m, cy: y + 2.5 * m, r: 0.55 * m }, fill: theme.ink });
+  }
   return paints;
 }
 
@@ -222,13 +487,31 @@ function boxPath(b: Box): string {
 
 function shapePath(s: Shape): string {
   if (s.t === "box") return boxPath(s);
+  if (s.t === "poly") return `M${s.pts.map(([x, y]) => `${f(x)} ${f(y)}`).join("L")}Z`;
   const { cx, cy, r } = s;
   return `M${f(cx - r)} ${f(cy)}A${f(r)} ${f(r)} 0 1 0 ${f(cx + r)} ${f(cy)}A${f(r)} ${f(r)} 0 1 0 ${f(cx - r)} ${f(cy)}Z`;
 }
 
-/** The face as one SVG, 47 x 58 mm. Runs of same-colour shapes share one path. */
-export function paintsToSvg(paints: Paint[]): string {
+/** Gap between the sticker's edge and its grey cut line, mm. */
+export const CUT_LINE_GAP = 1;
+
+/**
+ * The face as one SVG (47 x 58 mm card, 62 x 58 mm cut-out shape). Runs of
+ * same-colour shapes share one path. `cutLine` adds a thin grey line
+ * CUT_LINE_GAP outside the edge: a wide grey stroke under a white one, so it
+ * follows any outline, with rounded corners that are easy to cut.
+ */
+export function paintsToSvg(paints: Paint[], opts: { w?: number; h?: number; cutLine?: boolean } = {}): string {
+  const w = opts.w ?? CARD_W;
+  const h = opts.h ?? CARD_H;
   const out: string[] = [];
+  if (opts.cutLine && paints[0]) {
+    const edge = shapePath(paints[0].shape);
+    out.push(
+      `<path fill="none" stroke="#8c8c8c" stroke-linejoin="round" stroke-width="${f(CUT_LINE_GAP * 2 + 0.5)}" d="${edge}"/>`,
+      `<path fill="none" stroke="#ffffff" stroke-linejoin="round" stroke-width="${f(CUT_LINE_GAP * 2)}" d="${edge}"/>`,
+    );
+  }
   let fill = "";
   let d = "";
   const flush = () => d && out.push(`<path fill="${fill}" d="${d}"/>`);
@@ -249,20 +532,21 @@ export function paintsToSvg(paints: Paint[]): string {
   }
   flush();
   return (
-    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${CARD_W} ${CARD_H}" width="${CARD_W}mm" height="${CARD_H}mm">` +
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}" width="${w}mm" height="${h}mm" overflow="visible">` +
     out.join("") +
     `</svg>`
   );
 }
 
 export function stickerFaceSvg(matrix: QrMatrix, design: StickerDesign): string {
-  return paintsToSvg(stickerFacePaints(matrix, design));
+  return paintsToSvg(stickerFacePaints(matrix, design), { ...cardSize(design.frame), cutLine: design.cutLines !== false });
 }
 
 /** The words under the plate for this design ("" = none). */
 export function stickerLabel(design: StickerDesign, siteName = ""): string {
   if (design.label === "none") return "";
   if (design.label === "verify") return "Scan to verify vehicle";
+  if (design.label === "scanme") return "Scan me";
   if (design.label === "site") return String(siteName ?? "").trim();
   return "Scan with iSecure365 / iMA365";
 }

package/utils/vehicle-qr-sticker.ts

@@ -8,16 +8,97 @@
  * pasted on the car.
  */
 
-import { DEFAULT_STICKER_DESIGN, QR_MM, qrTop, stickerLabel, stickerTheme, type StickerDesign } from "./vehicle-qr-design.ts";
+import {
+  DEFAULT_STICKER_DESIGN,
+  QR_MM,
+  cardSize,
+  isSilhouette,
+  qrTop,
+  silhouetteLayout,
+  stickerLabel,
+  stickerTheme,
+  type FrameShape,
+  type StickerDesign,
+} from "./vehicle-qr-design.ts";
 
 /** The server's most vehicles per request (POST /api/vehicles/qr/stickers). */
 export const STICKER_MAX_PER_REQUEST = 500;
 
-/** A4 sheet: 4 columns x 4 rows of 47 mm cells. */
+/** A4 sheet with the classic cards: 4 columns x 4 rows of 47 mm cells. */
 export const STICKER_COLUMNS = 4;
 export const STICKER_ROWS = 4;
 export const STICKERS_PER_PAGE = STICKER_COLUMNS * STICKER_ROWS;
 
+/** Printer margin on every side of the A4 sheet, mm. */
+export const SHEET_MARGIN = 5;
+const PAGE_W = 210 - SHEET_MARGIN * 2;
+const PAGE_H = 297 - SHEET_MARGIN * 2;
+
+/**
+ * How stickers sit on the A4 sheet. A cell = the sticker + the installer strip
+ * under it; `gap` is the empty cutting gap between cells (no ink in it except
+ * the small + cut marks in its middle).
+ */
+export type SheetLayout = { cols: number; rows: number; cellW: number; cardH: number; stripH: number; gap: number };
+
+export function sheetLayout(frame: FrameShape): SheetLayout {
+  // Cut-out shapes are 62 mm wide: 3 across. Cards stay 4 x 4 = 16.
+  return isSilhouette(frame)
+    ? { cols: 3, rows: 4, cellW: cardSize(frame).w, cardH: cardSize(frame).h, stripH: 10, gap: 4 }
+    : { cols: STICKER_COLUMNS, rows: STICKER_ROWS, cellW: cardSize(frame).w, cardH: cardSize(frame).h, stripH: 11, gap: 3 };
+}
+
+export const perSheet = (l: SheetLayout) => l.cols * l.rows;
+
+/** "12 stickers per A4 sheet with 4 mm cutting gaps" */
+export function sheetSummary(frame: FrameShape): string {
+  const l = sheetLayout(frame);
+  return `${perSheet(l)} stickers per A4 sheet with ${l.gap} mm cutting gaps`;
+}
+
+/** Top-left of the sticker grid inside the printable area, so it sits in the middle of the sheet. */
+function gridOrigin(l: SheetLayout): { x: number; y: number; w: number; h: number } {
+  const w = l.cols * l.cellW + (l.cols - 1) * l.gap;
+  const h = l.rows * (l.cardH + l.stripH) + (l.rows - 1) * l.gap;
+  return { x: (PAGE_W - w) / 2, y: (PAGE_H - h) / 2, w, h };
+}
+
+/**
+ * Cut marks for one sheet, as SVG over the printable area: a small + in the
+ * middle of every cutting gap crossing, and short ticks just outside the grid
+ * where each gap meets its edge - line a ruler up on them to cut the sheet
+ * into pieces.
+ */
+export function cropMarksSvg(l: SheetLayout): string {
+  const g = gridOrigin(l);
+  const cellH = l.cardH + l.stripH;
+  const xs = Array.from({ length: l.cols - 1 }, (_, i) => g.x + (i + 1) * l.cellW + i * l.gap + l.gap / 2);
+  const ys = Array.from({ length: l.rows - 1 }, (_, i) => g.y + (i + 1) * cellH + i * l.gap + l.gap / 2);
+  const r = (v: number) => Math.round(v * 100) / 100;
+  const arm = Math.min(1.2, l.gap / 2 - 0.3);
+  const tickX = Math.max(0.6, g.y - 0.4);
+  const tickY = Math.max(0.6, g.x - 0.4);
+  const lines: string[] = [];
+  const line = (x1: number, y1: number, x2: number, y2: number) =>
+    lines.push(`<line x1="${r(x1)}" y1="${r(y1)}" x2="${r(x2)}" y2="${r(y2)}"/>`);
+  for (const x of xs) {
+    line(x, g.y - tickX, x, g.y - 0.2);
+    line(x, g.y + g.h + 0.2, x, g.y + g.h + tickX);
+    for (const y of ys) {
+      line(x - arm, y, x + arm, y);
+      line(x, y - arm, x, y + arm);
+    }
+  }
+  for (const y of ys) {
+    line(g.x - tickY, y, g.x - 0.2, y);
+    line(g.x + g.w + 0.2, y, g.x + g.w + tickY, y);
+  }
+  return (
+    `<svg class="marks" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${PAGE_W} ${PAGE_H}" width="${PAGE_W}mm" height="${PAGE_H}mm">` +
+    `<g stroke="#555" stroke-width="0.15">${lines.join("")}</g></svg>`
+  );
+}
+
 export type StickerItem = {
   vehicleId: string;
   qr: string;
@@ -141,25 +222,38 @@ export function escapeHtml(value: unknown): string {
     .replace(/'/g, "&#39;");
 }
 
-const PRINT_CSS = `
-@page { size: A4; margin: 6mm; }
+// Printed at 100% ("Actual size"): every size below is real millimetres on paper.
+function printCss(l: SheetLayout): string {
+  const g = gridOrigin(l);
+  return `
+@page { size: A4; margin: ${SHEET_MARGIN}mm; }
 * { box-sizing: border-box; }
 html, body { margin: 0; padding: 0; background: #fff; color: #111; font-family: Arial, Helvetica, sans-serif; -webkit-print-color-adjust: exact; print-color-adjust: exact; }
-.page { display: grid; grid-template-columns: repeat(${STICKER_COLUMNS}, 47mm); gap: 2mm; justify-content: center; align-content: start; width: 198mm; height: 285mm; margin: 0 auto; break-after: page; }
+.page { position: relative; display: grid; grid-template-columns: repeat(${l.cols}, ${l.cellW}mm); grid-auto-rows: ${l.cardH + l.stripH}mm; gap: ${l.gap}mm; justify-content: start; align-content: start; padding: ${g.y}mm 0 0 ${g.x}mm; width: ${PAGE_W}mm; height: ${PAGE_H}mm; margin: 0 auto; overflow: hidden; break-after: page; }
 .page:last-child { break-after: auto; }
-.cell { width: 47mm; break-inside: avoid; }
-.card { position: relative; width: 47mm; height: 58mm; }
-.face, .face svg { position: absolute; inset: 0; width: 47mm; height: 58mm; display: block; }
+.marks { position: absolute; left: 0; top: 0; width: ${PAGE_W}mm; height: ${PAGE_H}mm; pointer-events: none; }
+.cell { width: ${l.cellW}mm; break-inside: avoid; }
+.card { position: relative; width: ${l.cellW}mm; height: ${l.cardH}mm; }
+.face, .face svg { position: absolute; inset: 0; width: ${l.cellW}mm; height: ${l.cardH}mm; display: block; overflow: visible; }
 .words { position: absolute; left: 3mm; right: 3mm; bottom: 2mm; display: flex; flex-direction: column; align-items: center; justify-content: space-between; text-align: center; }
-.plate { font-size: 13pt; font-weight: 800; letter-spacing: 0.3mm; line-height: 1.1; }
+.words.band { bottom: auto; justify-content: center; gap: 0.6mm; }
+.plate { font-size: 13pt; font-weight: 800; letter-spacing: 0.3mm; line-height: 1.1; white-space: nowrap; }
 .hint { font-size: 5.8pt; line-height: 1.2; opacity: 0.85; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 100%; }
 .brand { display: flex; align-items: center; justify-content: center; gap: 1mm; font-size: 6pt; border-top: 0.2mm solid #ccc; width: 100%; padding-top: 1mm; }
 .mark { width: 3.2mm; height: 3.2mm; border-radius: 0.8mm; color: #fff; font-weight: 800; font-size: 5pt; line-height: 3.2mm; text-align: center; }
-.cut { margin-top: 1.2mm; border-top: 0.3mm dashed #666; padding-top: 1mm; font-size: 6.5pt; line-height: 1.25; color: #111; min-height: 8mm; }
+.cut { margin-top: 1.2mm; border-top: 0.3mm dashed #666; padding-top: 1mm; font-size: 6.5pt; line-height: 1.25; color: #111; height: ${l.stripH - 1.2}mm; overflow: hidden; }
+.cut.free { margin-top: 1.6mm; border-top: 0; padding-top: 0; height: ${l.stripH - 1.6}mm; }
 .cut .owner { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .cut .note { color: #666; font-size: 5.5pt; }
-@media screen { body { background: #e9e9e9; zoom: 0.75; padding: 4mm 0; } .page { background: #fff; margin-bottom: 4mm; height: auto; min-height: 285mm; box-shadow: 0 0 2mm rgba(0,0,0,.25); } }
+@media screen { body { background: #e9e9e9; zoom: 0.75; padding: 4mm 0; } .page { background: #fff; margin-bottom: 4mm; box-shadow: 0 0 2mm rgba(0,0,0,.25); } }
 `;
+}
+
+/** Plate font size (mm) that fits the cut-out shape's plate box. */
+function plateSizeMm(plate: string, boxW: number): number {
+  // bold capitals are about 0.74 em wide, plus 0.3 mm letter spacing each
+  return Math.round(Math.min(4.6, (boxW / Math.max(plate.length, 1) - 0.3) / 0.74) * 100) / 100;
+}
 
 /**
  * One full HTML document: A4 sheets of stickers. `faceSvgs` is parallel to
@@ -174,22 +268,34 @@ export function buildStickerDocument(
   const design = opts.design ?? DEFAULT_STICKER_DESIGN;
   const { ink } = stickerTheme(design.theme);
   const label = stickerLabel(design, opts.siteName);
+  const layout = sheetLayout(design.frame);
+  const shape = isSilhouette(design.frame) ? silhouetteLayout(design.frame) : null;
   const wordsTop = qrTop(design.frame) + QR_MM + 0.8;
   const cells = items.map((item, i) => {
     const { place, owner } = installerLine(item);
+    const plate = escapeHtml(item.plateNumber);
+    // Cut-out shapes: plate (and words) in the box under the QR; no brand line - there is no room.
+    const words = shape
+      ? `<div class="words band" style="left:${shape.band.x}mm;right:auto;top:${shape.band.y}mm;width:${shape.band.w}mm;height:${shape.band.h}mm">` +
+        `<div class="plate" style="font-size:${plateSizeMm(text(item.plateNumber), shape.band.w)}mm">${plate}</div>` +
+        (label ? `<div class="hint">${escapeHtml(label)}</div>` : "") +
+        `</div>`
+      : `<div class="words" style="top:${wordsTop}mm">` +
+        `<div class="plate">${plate}</div>` +
+        (label ? `<div class="hint">${escapeHtml(label)}</div>` : "") +
+        `<div class="brand"><span class="mark" style="background:${ink}">7</span>Powered by Seven365</div>` +
+        `</div>`;
     return (
       `<div class="cell"><div class="card" style="color:${ink}">` +
       `<div class="face">${faceSvgs[i] ?? ""}</div>` +
-      `<div class="words" style="top:${wordsTop}mm">` +
-      `<div class="plate">${escapeHtml(item.plateNumber)}</div>` +
-      (label ? `<div class="hint">${escapeHtml(label)}</div>` : "") +
-      `<div class="brand"><span class="mark" style="background:${ink}">7</span>Powered by Seven365</div>` +
-      `</div></div>` +
-      `<div class="cut"><div><b>${escapeHtml(place || "-")}</b></div>` +
+      words +
+      `</div>` +
+      `<div class="cut${shape ? " free" : ""}"><div><b>${escapeHtml(place || "-")}</b></div>` +
       `<div class="owner">Owner: ${escapeHtml(owner || "-")}</div>` +
-      `<div class="note">Installer: cut here, then paste on this car</div></div></div>`
+      `<div class="note">${shape ? "Installer: cut out the sticker, then paste on this car" : "Installer: cut here, then paste on this car"}</div></div></div>`
     );
   });
-  const pages = stickerPages(cells).map((p) => `<div class="page">${p.join("")}</div>`);
-  return `<!doctype html><html><head><meta charset="utf-8"><title>Vehicle QR stickers</title><style>${PRINT_CSS}</style></head><body>${pages.join("")}</body></html>`;
+  const marks = cropMarksSvg(layout);
+  const pages = stickerPages(cells, perSheet(layout)).map((p) => `<div class="page">${marks}${p.join("")}</div>`);
+  return `<!doctype html><html><head><meta charset="utf-8"><title>Vehicle QR stickers</title><style>${printCss(layout)}</style></head><body>${pages.join("")}</body></html>`;
 }