@feedmepos/mf-order-setting 0.0.84 → 0.0.85

package/src/locales/ja-JP.json

@@ -100,6 +100,12 @@
     "autoIntegrationCountryNotSupport": "プラットフォームは現在の国での自動連携をサポートしていません。",
     "autoSendKitchen": "キッチンに自動送信",
     "autoSendKitchenSublabel": "POSバージョン7以上が必要です",
+    "followAutoAccept": "自動受注に従う",
+    "autoSendKitchenChannelSublabel": "注文を受け付けたときにキッチンへ送信します。「自動受注に従う」は現在の動作を維持し、自動受注のときのみキッチンに通知します。",
+    "autoCloseBillRequiresAutoSend": "請求書の自動締めは、注文が自動受注されキッチンに送信された場合にのみ適用されます。それ以外は請求書は開いたままになります。締めた請求書はキッチンに送信できなくなるためです。",
+    "autoCloseBillEnableKitchenTitle": "「キッチンに自動送信」も有効にしますか？",
+    "autoCloseBillEnableKitchenMessage": "このチャネルの注文はキッチンへ自動送信されないため、支払い済みの請求書がキッチンに届く前に締められます。締めた請求書はキッチンに送信できません。「キッチンに自動送信」も有効にすると、受け付けたすべての注文が先にキッチンへ届きます。",
+    "autoCloseBillEnableKitchenConfirm": "両方を有効にする",
     "presetRemarks": "プリセット備考",
     "editPresetRemarks": "プリセット備考を編集",
     "addNewRemark": "新しい備考を追加",
@@ -238,6 +244,11 @@
     "coverImageLandscapeHint": "推奨サイズ: 1920 x 1080",
     "coverImagePortraitHint": "推奨サイズ: 1080 x 1920",
     "coverImageFallbackHint": "未設定の場合、レストラン設定のカバー画像が使用されます",
+    "coverCarouselHint": "向きごとに最大 {max} 枚まで追加できます。2 枚以上ある場合、キオスクのトップ画面が表示順にフェードで切り替わります。",
+    "coverCarouselInterval": "1 枚あたりの表示秒数",
+    "coverCarouselIntervalHint": "次の画像に切り替わるまでの表示時間です。空欄の場合は既定の {seconds} 秒になります。",
+    "coverCarouselMoveEarlier": "前に移動",
+    "coverCarouselMoveLater": "後に移動",
     "uploadImage": "画像をアップロード",
     "imageUrl": "画像URL",
     "imageUrlPlaceholder": "画像URLを入力",
@@ -294,7 +305,7 @@
     "printReceiptAfterClose": "自動締め後にレシートを印刷",
     "printReceiptAfterCloseSublabel": "請求書が自動締めされた後にレシートを印刷します",
     "autoCloseBill": "請求書を自動締め",
-    "autoCloseBillSublabel": "注文を受け付けると請求書を自動で締めます",
+    "autoCloseBillSublabel": "注文を受け付けると請求書を自動で締めます。未払いの請求書は、支払いが完了するまで開いたままになります。",
     "prefix": "プレフィックス",
     "preOrder": "事前注文",
     "preOrderHint": "{today}に注文、お客様は{start}から{end}の間で注文可能です。最大{maxDays}日間（本日含む）。",

package/src/locales/th-TH.json

@@ -193,6 +193,12 @@
     "autoIntegrationCountryNotSupport": "แพลตฟอร์มไม่รองรับการเชื่อมต่อการจัดส่งแบบไดนามิกในประเทศ/ภูมิภาคปัจจุบัน",
     "autoSendKitchen": "ส่งเข้าครัวอัตโนมัติ",
     "autoSendKitchenSublabel": "ต้องใช้ POS เวอร์ชัน 7 ขึ้นไป",
+    "followAutoAccept": "ใช้การตั้งค่าตามการรับออเดอร์อัตโนมัติ",
+    "autoSendKitchenChannelSublabel": "ส่งออเดอร์เข้าครัวเมื่อรับออเดอร์แล้ว เลือก “ใช้การตั้งค่าตามการรับออเดอร์อัตโนมัติ” เพื่อคงพฤติกรรมเดิม คือแจ้งครัวเฉพาะเมื่อรับออเดอร์อัตโนมัติเท่านั้น",
+    "autoCloseBillRequiresAutoSend": "การปิดบิลอัตโนมัติจะทำงานเฉพาะเมื่อออเดอร์ถูกรับอัตโนมัติและส่งเข้าครัวแล้วเท่านั้น มิฉะนั้นบิลจะยังเปิดอยู่ เพราะบิลที่ปิดแล้วไม่สามารถส่งเข้าครัวได้อีก",
+    "autoCloseBillEnableKitchenTitle": "เปิด “ส่งเข้าครัวอัตโนมัติ” ด้วยหรือไม่?",
+    "autoCloseBillEnableKitchenMessage": "ออเดอร์ของช่องทางนี้ไม่ถูกส่งเข้าครัวอัตโนมัติ บิลที่ชำระเงินแล้วจึงถูกปิดก่อนที่ครัวจะเห็น และบิลที่ปิดแล้วไม่สามารถส่งเข้าครัวได้อีก การเปิด “ส่งเข้าครัวอัตโนมัติ” ด้วยจะทำให้ทุกออเดอร์ที่รับแล้วถึงครัวก่อนเสมอ",
+    "autoCloseBillEnableKitchenConfirm": "เปิดทั้งสองอย่าง",
     "presetRemarks": "หมายเหตุที่ตั้งไว้ล่วงหน้า",
     "editPresetRemarks": "แก้ไขหมายเหตุที่ตั้งไว้ล่วงหน้า",
     "addNewRemark": "เพิ่มหมายเหตุใหม่",
@@ -336,6 +342,11 @@
     "coverImageLandscapeHint": "ขนาดที่แนะนำ: 1920 x 1080",
     "coverImagePortraitHint": "ขนาดที่แนะนำ: 1080 x 1920",
     "coverImageFallbackHint": "หากไม่ตั้งค่า ระบบจะใช้ Cover Image จากการตั้งค่าร้านอาหารโดยอัตโนมัติ",
+    "coverCarouselHint": "เพิ่มได้สูงสุด {max} รูปต่อการวางแนว หากมีตั้งแต่ 2 รูปขึ้นไป หน้าแรกของตู้คีออสก์จะค่อย ๆ เปลี่ยนภาพตามลำดับที่แสดง",
+    "coverCarouselInterval": "จำนวนวินาทีต่อรูป",
+    "coverCarouselIntervalHint": "แสดงแต่ละรูปนานเท่าใดก่อนเปลี่ยนเป็นรูปถัดไป เว้นว่างไว้เพื่อใช้ค่าเริ่มต้น {seconds} วินาที",
+    "coverCarouselMoveEarlier": "เลื่อนขึ้นก่อน",
+    "coverCarouselMoveLater": "เลื่อนไปหลัง",
     "uploadImage": "อัปโหลดรูปภาพ",
     "imageUrl": "ลิงก์รูปภาพ",
     "imageUrlPlaceholder": "กรอกลิงก์รูปภาพ",
@@ -403,7 +414,7 @@
     "printReceiptAfterClose": "พิมพ์ใบเสร็จหลังจากปิดบิลอัตโนมัติ",
     "printReceiptAfterCloseSublabel": "พิมพ์ใบเสร็จหลังจากปิดบิลอัตโนมัติแล้ว",
     "autoCloseBill": "ปิดบิลอัตโนมัติ",
-    "autoCloseBillSublabel": "ปิดบิลโดยอัตโนมัติเมื่อรับออเดอร์แล้ว",
+    "autoCloseBillSublabel": "ปิดบิลโดยอัตโนมัติเมื่อรับออเดอร์แล้ว บิลที่ยังไม่ชำระเงินจะยังเปิดอยู่จนกว่าจะชำระเงินครบ",
     "processing": "กำลังประมวลผล",
     "productSelected": "ผลิตภัณฑ์ที่เลือก",
     "promptAnonymousLoginDialog": "แสดงหน้าต่างให้เข้าสู่ระบบเมื่อสั่งอาหารโดยไม่เข้าสู่ระบบ",

package/src/locales/zh-CN.json

@@ -193,6 +193,12 @@
     "autoIntegrationCountryNotSupport": "平台不支持当前国家/地区的自动配送对接。",
     "autoSendKitchen": "自动发送至厨房",
     "autoSendKitchenSublabel": "需要POS版本7或以上",
+    "followAutoAccept": "跟随自动接单",
+    "autoSendKitchenChannelSublabel": "接受订单时自动发送至厨房。选择「跟随自动接单」维持现有行为：仅在订单自动接单时通知厨房。",
+    "autoCloseBillRequiresAutoSend": "仅当订单自动接单并已发送至厨房时，才会自动关闭账单。否则账单保持开启，因为已关闭的账单无法再发送至厨房。",
+    "autoCloseBillEnableKitchenTitle": "同时开启「自动发送至厨房」？",
+    "autoCloseBillEnableKitchenMessage": "此渠道的订单不会自动发送至厨房，已付款的账单会在厨房看到之前被关闭，而已关闭的账单无法再发送至厨房。同时开启「自动发送至厨房」可确保每笔已接受的订单先送达厨房。",
+    "autoCloseBillEnableKitchenConfirm": "同时开启",
     "presetRemarks": "预设备注",
     "editPresetRemarks": "编辑预设备注",
     "addNewRemark": "添加新备注",
@@ -338,6 +344,11 @@
     "coverImageLandscapeHint": "推荐尺寸：1920 x 1080",
     "coverImagePortraitHint": "推荐尺寸：1080 x 1920",
     "coverImageFallbackHint": "若不设置，将默认使用餐厅设置中的 Cover Image",
+    "coverCarouselHint": "每个方向最多可添加 {max} 张图片。有两张或以上时，自助点餐机首页会按显示顺序淡入淡出切换。",
+    "coverCarouselInterval": "每张图片显示秒数",
+    "coverCarouselIntervalHint": "每张图片显示多久后切换到下一张。留空则使用默认的 {seconds} 秒。",
+    "coverCarouselMoveEarlier": "往前移",
+    "coverCarouselMoveLater": "往后移",
     "uploadImage": "上传图片",
     "imageUrl": "图片链接",
     "imageUrlPlaceholder": "请输入图片链接",
@@ -404,7 +415,7 @@
     "printReceiptAfterClose": "自动关闭账单后打印收据",
     "printReceiptAfterCloseSublabel": "账单自动关闭后打印收据",
     "autoCloseBill": "自动关闭账单",
-    "autoCloseBillSublabel": "订单接受后自动关闭账单",
+    "autoCloseBillSublabel": "订单接受后自动关闭账单。尚未付款的账单会保持开启，直到结清为止。",
     "pricePerMessage": "每条短信的价格",
     "processing": "处理中",
     "productSelected": "已选择商品",
@@ -584,6 +595,7 @@
           "queueBandBoard": "排队叫号板",
           "mediaCarousel": "轮播",
           "mediaImage": "图片",
+          "mediaVideo": "视频",
           "infoText": "文字"
         },
         "fields": {
@@ -610,7 +622,8 @@
           "title": "标题",
           "subtitle": "副标题",
           "text": "文字",
-          "image": "图片"
+          "image": "图片",
+          "video": "视频"
         },
         "values": {
           "horizontal": "左右并排",
@@ -684,6 +697,11 @@
           "replaceImage": "更换",
           "clearImage": "移除",
           "noImage": "未设置",
+          "chooseVideo": "选择视频",
+          "replaceVideo": "更换",
+          "clearVideo": "移除",
+          "noVideo": "未设置",
+          "videoUndecodable": "可能无法在屏幕上播放，建议改用 MP4",
           "modules": "该区域的模块",
           "addModule": "添加模块",
           "addModulePlaceholder": "选择要添加的模块",
@@ -724,6 +742,8 @@
       "allRestaurants": "所有餐厅",
       "online": "在线",
       "offline": "离线",
+      "unlicensed": "未授权",
+      "unlicensedNote": "超出屏幕授权数量，POS 会在这块屏上标记未授权。可以再买一块，或停用其中一块。",
       "deviceId": "设备 ID",
       "lastSeen": "最后在线",
       "appVersion": "应用版本",

package/src/modules/display-system/interface.spec.ts

@@ -2,24 +2,7 @@ import { DISPLAY_BLOCK_DEFINITIONS } from '@entity'
 import { reactive } from 'vue'
 import { describe, expect, it } from 'vitest'
 
-import {
-  addArea,
-  clearBlock,
-  crossDirection,
-  defaultBlock,
-  defaultDisplayTemplateDraft,
-  displayTemplatePayload,
-  mergeGroup,
-  removeArea,
-  setBlock,
-  splitArea,
-  swapBlocks,
-  templateCapabilities,
-  walkZones,
-  zoneFitsMinimum,
-  zoneParent,
-  type DisplaySplitDraft
-} from './interface'
+import { addArea, clearBlock, crossDirection, defaultBlock, defaultDisplayTemplateDraft, displayTemplatePayload, mergeGroup, removeArea, setBlock, splitArea, swapBlocks, templateCapabilities, type DisplaySplitDraft, unlicensedScreenIds, walkZones, zoneFitsMinimum, zoneParent } from './interface'
 
 describe('display template drafts', () => {
   it('serializes a reactive editor draft into an API payload', () => {
@@ -145,3 +128,34 @@ describe('display template drafts', () => {
     expect(zoneFitsMinimum(draft.root, queueZone.id, minimum, 0.5)).toBe(true)
   })
 })
+
+describe('unlicensedScreenIds', () => {
+  const screen = (id: string, createdAt: string, status = 'ACTIVE') =>
+    ({ _id: id, createdAt, status }) as never
+
+  // Mirrors rebuildSnapshotsLocked: oldest first, everything past the limit
+  // loses its licence.
+  it('takes the licence from the newest screens', () => {
+    const screens = [
+      screen('new', '2026-08-26T07:11:30.064Z'),
+      screen('old', '2026-08-24T14:08:46.632Z')
+    ]
+    expect([...unlicensedScreenIds(screens, 1)]).toEqual(['new'])
+    expect([...unlicensedScreenIds(screens, 2)]).toEqual([])
+    expect([...unlicensedScreenIds(screens, 0)].sort()).toEqual(['new', 'old'])
+  })
+
+  // A paused screen frees its slot, so it must not consume one here either.
+  it('ignores disabled screens', () => {
+    const screens = [
+      screen('paused', '2026-08-20T00:00:00.000Z', 'DISABLED'),
+      screen('live', '2026-08-24T00:00:00.000Z')
+    ]
+    expect([...unlicensedScreenIds(screens, 1)]).toEqual([])
+  })
+
+  it('breaks a createdAt tie by id, the way the host does', () => {
+    const screens = [screen('b', 'same'), screen('a', 'same')]
+    expect([...unlicensedScreenIds(screens, 1)]).toEqual(['b'])
+  })
+})

package/src/modules/display-system/interface.ts

@@ -74,11 +74,43 @@ function cloneJsonValue<T>(value: T): T {
   return JSON.parse(JSON.stringify(value)) as T
 }
 
+/**
+ * Screens the POS will watermark as unlicensed.
+ *
+ * Mirrors `rebuildSnapshotsLocked` in
+ * `go/packages/display_host/runtime/source.go` — that is the authority, because
+ * the POS decides this offline from its own cached entitlement. Kept as one
+ * function so the duplicate is in a single place: DISABLED screens do not
+ * count, the rest are ordered oldest first, and everything past the limit
+ * loses its licence.
+ */
+export function unlicensedScreenIds(
+  screens: Pick<DisplayScreen, '_id' | 'status' | 'createdAt'>[],
+  screenLimit: number
+): Set<string> {
+  const ordered = screens
+    .filter((screen) => screen.status !== 'DISABLED')
+    .sort((left, right) =>
+      left.createdAt === right.createdAt
+        ? left._id.localeCompare(right._id)
+        : (left.createdAt ?? '').localeCompare(right.createdAt ?? '')
+    )
+  return new Set(ordered.slice(Math.max(0, screenLimit)).map((screen) => screen._id))
+}
+
+/** Where a media pick lands, and which kind the picker should offer. Absent
+ * mediaKind means image: a zone background and every carousel item render as
+ * one. */
+export type DisplayMediaTarget =
+  | { kind: 'background' }
+  | { kind: 'block'; path: string; mediaKind?: 'image' | 'video' }
+
 const blockDefaults: Record<string, Record<string, unknown>> = {
   'pickup.categoryBoard': { rotateMs: 10000, showProgressBar: false, showDeliveryIcons: true, showCurrentOrder: true, announce: true },
   'pickup.statusBoard': { layout: 'HORIZONTAL', columns: 2, rotateMs: 10000, showDeliveryIcons: true, showOrderCount: false, showEstimatedTime: false, showCurrentOrder: true, announce: true },
   'queue.bandBoard': { showWaitingCount: true, upcomingCount: 3, rotateMs: 10000, showHeader: true, announce: true },
   'media.image': { url: '', objectFit: 'COVER' },
+  'media.video': { url: '', objectFit: 'COVER' },
   'media.carousel': { items: [{ kind: 'IMAGE', url: '', objectFit: 'COVER' }], intervalMs: 8000, transition: 'FADE' },
   'info.text': { text: 'Welcome', size: 'MD', align: 'CENTER' }
 }

package/src/modules/order-setting/kiosk/coverCarousel.spec.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it } from 'vitest'
+import {
+  applyCoverImages,
+  applyIntervalSeconds,
+  MAX_COVER_IMAGES,
+  readCoverImages,
+  readIntervalSeconds,
+  reorderCoverImages,
+  type CoverImageFields
+} from './coverCarousel'
+
+const empty: CoverImageFields = {
+  coverImageLandscape: null,
+  coverImagePortrait: null
+}
+
+function fields(over: Partial<CoverImageFields>): CoverImageFields {
+  return { ...empty, ...over }
+}
+
+describe('readCoverImages', () => {
+  it('is empty when nothing is set', () => {
+    expect(readCoverImages(empty, 'portrait')).toEqual([])
+  })
+
+  it('reads the single image as a one-entry list', () => {
+    expect(readCoverImages(fields({ coverImagePortrait: 'p.jpg' }), 'portrait')).toEqual(['p.jpg'])
+  })
+
+  it('prefers the carousel list over the single image', () => {
+    const f = fields({
+      coverImagePortrait: 'old.jpg',
+      coverCarousel: { portrait: ['a.jpg', 'b.jpg'] }
+    })
+    expect(readCoverImages(f, 'portrait')).toEqual(['a.jpg', 'b.jpg'])
+  })
+
+  it('falls back to the single image when the list for that orientation is empty', () => {
+    const f = fields({
+      coverImagePortrait: 'p.jpg',
+      coverCarousel: { landscape: ['a.jpg', 'b.jpg'] }
+    })
+    expect(readCoverImages(f, 'portrait')).toEqual(['p.jpg'])
+    expect(readCoverImages(f, 'landscape')).toEqual(['a.jpg', 'b.jpg'])
+  })
+
+  it('drops blanks and duplicates', () => {
+    const f = fields({ coverCarousel: { portrait: ['a.jpg', '  ', 'a.jpg', ' b.jpg '] } })
+    expect(readCoverImages(f, 'portrait')).toEqual(['a.jpg', 'b.jpg'])
+  })
+
+  it('treats a whitespace-only single image as unset', () => {
+    expect(readCoverImages(fields({ coverImagePortrait: '   ' }), 'portrait')).toEqual([])
+  })
+})
+
+describe('applyCoverImages', () => {
+  it('stores one image on the single field only, leaving no carousel behind', () => {
+    const next = applyCoverImages(empty, 'portrait', ['p.jpg'])
+    expect(next.coverImagePortrait).toBe('p.jpg')
+    expect(next.coverCarousel).toBeNull()
+  })
+
+  it('stores two or more on the carousel list and mirrors the first to the single field', () => {
+    const next = applyCoverImages(empty, 'portrait', ['a.jpg', 'b.jpg', 'c.jpg'])
+    expect(next.coverCarousel?.portrait).toEqual(['a.jpg', 'b.jpg', 'c.jpg'])
+    // An older kiosk build knows only this field.
+    expect(next.coverImagePortrait).toBe('a.jpg')
+  })
+
+  it('clearing goes back to the pre-feature document', () => {
+    const f = fields({
+      coverImagePortrait: 'a.jpg',
+      coverCarousel: { portrait: ['a.jpg', 'b.jpg'] }
+    })
+    const next = applyCoverImages(f, 'portrait', [])
+    expect(next.coverImagePortrait).toBeNull()
+    expect(next.coverCarousel).toBeNull()
+  })
+
+  it('dropping back to one image clears that orientation list', () => {
+    const f = fields({
+      coverImagePortrait: 'a.jpg',
+      coverCarousel: { portrait: ['a.jpg', 'b.jpg'] }
+    })
+    const next = applyCoverImages(f, 'portrait', ['b.jpg'])
+    expect(next.coverImagePortrait).toBe('b.jpg')
+    expect(next.coverCarousel).toBeNull()
+  })
+
+  it('does not touch the other orientation', () => {
+    const f = fields({
+      coverImageLandscape: 'l.jpg',
+      coverCarousel: { landscape: ['l.jpg', 'l2.jpg'], intervalMs: 8000 }
+    })
+    const next = applyCoverImages(f, 'portrait', ['p1.jpg', 'p2.jpg'])
+    expect(next.coverImageLandscape).toBe('l.jpg')
+    expect(next.coverCarousel?.landscape).toEqual(['l.jpg', 'l2.jpg'])
+    expect(next.coverCarousel?.intervalMs).toBe(8000)
+  })
+
+  it('does not promote the other orientation single image into a list', () => {
+    const f = fields({ coverImagePortrait: 'p.jpg' })
+    const next = applyCoverImages(f, 'landscape', ['a.jpg', 'b.jpg'])
+    expect(next.coverImagePortrait).toBe('p.jpg')
+    expect(next.coverCarousel?.portrait).toBeUndefined()
+  })
+
+  it('caps the list', () => {
+    const many = Array.from({ length: MAX_COVER_IMAGES + 3 }, (_, i) => `i${i}.jpg`)
+    const next = applyCoverImages(empty, 'portrait', many)
+    expect(next.coverCarousel?.portrait).toHaveLength(MAX_COVER_IMAGES)
+  })
+
+  it('does not mutate the input', () => {
+    const f = fields({ coverCarousel: { portrait: ['a.jpg', 'b.jpg'] } })
+    applyCoverImages(f, 'portrait', ['c.jpg'])
+    expect(f.coverCarousel?.portrait).toEqual(['a.jpg', 'b.jpg'])
+  })
+})
+
+describe('interval', () => {
+  it('reads nothing when unset', () => {
+    expect(readIntervalSeconds(empty)).toBeNull()
+    expect(readIntervalSeconds(fields({ coverCarousel: { portrait: ['a.jpg'] } }))).toBeNull()
+  })
+
+  it('reads milliseconds back as seconds', () => {
+    expect(readIntervalSeconds(fields({ coverCarousel: { intervalMs: 9000 } }))).toBe(9)
+  })
+
+  it('stores seconds as milliseconds when a carousel exists', () => {
+    const f = fields({ coverCarousel: { portrait: ['a.jpg', 'b.jpg'] } })
+    expect(applyIntervalSeconds(f, 10).coverCarousel?.intervalMs).toBe(10_000)
+  })
+
+  it('clamps below the kiosk fade floor and above the ceiling', () => {
+    const f = fields({ coverCarousel: { portrait: ['a.jpg', 'b.jpg'] } })
+    expect(applyIntervalSeconds(f, 0).coverCarousel?.intervalMs).toBe(2000)
+    expect(applyIntervalSeconds(f, 999).coverCarousel?.intervalMs).toBe(60_000)
+  })
+
+  it('clearing it drops the field so the kiosk default applies', () => {
+    const f = fields({ coverCarousel: { portrait: ['a.jpg', 'b.jpg'], intervalMs: 9000 } })
+    const next = applyIntervalSeconds(f, null)
+    expect(next.coverCarousel?.intervalMs).toBeUndefined()
+    expect(next.coverCarousel?.portrait).toEqual(['a.jpg', 'b.jpg'])
+  })
+
+  it('is a no-op sub-object when there is nothing to animate', () => {
+    expect(applyIntervalSeconds(empty, 10).coverCarousel).toBeNull()
+  })
+})
+
+describe('reorderCoverImages', () => {
+  it('moves an image', () => {
+    expect(reorderCoverImages(['a', 'b', 'c'], 2, 0)).toEqual(['c', 'a', 'b'])
+    expect(reorderCoverImages(['a', 'b', 'c'], 0, 1)).toEqual(['b', 'a', 'c'])
+  })
+
+  it('is a no-op out of range or in place', () => {
+    expect(reorderCoverImages(['a', 'b'], 0, 0)).toEqual(['a', 'b'])
+    expect(reorderCoverImages(['a', 'b'], -1, 1)).toEqual(['a', 'b'])
+    expect(reorderCoverImages(['a', 'b'], 0, 5)).toEqual(['a', 'b'])
+  })
+
+  it('does not mutate the input', () => {
+    const list = ['a', 'b', 'c']
+    reorderCoverImages(list, 0, 2)
+    expect(list).toEqual(['a', 'b', 'c'])
+  })
+})

package/src/modules/order-setting/kiosk/coverCarousel.ts

@@ -0,0 +1,186 @@
+import type { OrderKioskSettings } from '@entity'
+
+/**
+ * Landing-screen background images for the kiosk, as the settings form sees
+ * them: ONE ordered list per orientation.
+ *
+ * The stored shape is two fields, not one, and that is deliberate — see
+ * FdoOrderKioskCoverCarousel in package/entity. `coverImage{Landscape,Portrait}`
+ * is the original single image; `coverCarousel.{landscape,portrait}` is the
+ * multi-image list that wins whenever it has entries. Keeping both means no
+ * migration and no behaviour change for merchants who never open this editor.
+ *
+ * These helpers are the only place that knows how one list maps onto those two
+ * fields, so the view never has to reason about it:
+ *
+ *  - 0 or 1 image  -> written to the single field, carousel list cleared. A
+ *    merchant who uploads one picture ends up with exactly the document they
+ *    would have had before this feature existed.
+ *  - 2 or more     -> written to the carousel list, AND the first image is
+ *    mirrored into the single field. Kiosks update over the air, so some
+ *    devices are still running a build that has never heard of `coverCarousel`;
+ *    the mirror leaves them showing the first image instead of silently falling
+ *    back to the restaurant profile photo.
+ */
+
+export type CoverOrientation = 'landscape' | 'portrait'
+
+type CoverCarousel = NonNullable<OrderKioskSettings['coverCarousel']>
+
+/** The subset of the kiosk form these helpers read and rewrite. */
+export interface CoverImageFields {
+  coverImageLandscape: string | null
+  coverImagePortrait: string | null
+  coverCarousel?: CoverCarousel | null
+}
+
+/**
+ * Enough for a landing loop, few enough that the merchant is not uploading a
+ * slideshow into a document the kiosk fetches on every boot.
+ */
+export const MAX_COVER_IMAGES = 8
+
+/**
+ * Kept in step with kiosk-v2's HomeCoverBackground.vue: it defaults to 6000ms
+ * and clamps anything below FADE_MS + 400 = 1600ms, so offering less than 2s
+ * here would just be a number the kiosk ignores.
+ */
+export const DEFAULT_COVER_INTERVAL_SECONDS = 6
+export const MIN_COVER_INTERVAL_SECONDS = 2
+export const MAX_COVER_INTERVAL_SECONDS = 60
+
+const SINGLE_FIELD = {
+  landscape: 'coverImageLandscape',
+  portrait: 'coverImagePortrait'
+} as const
+
+function cleanList(list?: string[] | null): string[] {
+  if (!Array.isArray(list)) return []
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const entry of list) {
+    const url = typeof entry === 'string' ? entry.trim() : ''
+    // A duplicate URL is invisible on the kiosk anyway: HomeCoverBackground
+    // de-duplicates because a repeated url collides as a `:key`.
+    if (!url || seen.has(url)) continue
+    seen.add(url)
+    out.push(url)
+  }
+  return out
+}
+
+function storedList(fields: CoverImageFields, orientation: CoverOrientation): string[] {
+  return cleanList(fields.coverCarousel?.[orientation])
+}
+
+function storedSingle(fields: CoverImageFields, orientation: CoverOrientation): string | null {
+  const value = fields[SINGLE_FIELD[orientation]]
+  const trimmed = typeof value === 'string' ? value.trim() : ''
+  return trimmed.length > 0 ? trimmed : null
+}
+
+/**
+ * The images to show in the editor for one orientation, in display order.
+ * Mirrors the kiosk's own resolution order, so what the merchant sees here is
+ * what the kiosk will render.
+ */
+export function readCoverImages(
+  fields: CoverImageFields,
+  orientation: CoverOrientation
+): string[] {
+  const list = storedList(fields, orientation)
+  if (list.length > 0) return list
+  const single = storedSingle(fields, orientation)
+  return single ? [single] : []
+}
+
+/** The stored hold time as whole seconds, or null when the merchant never set one. */
+export function readIntervalSeconds(fields: CoverImageFields): number | null {
+  const ms = fields.coverCarousel?.intervalMs
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms <= 0) return null
+  return Math.round(ms / 1000)
+}
+
+function buildCarousel(
+  landscape: string[],
+  portrait: string[],
+  intervalMs: number | null | undefined
+): CoverCarousel | null {
+  // Nothing is animating, so the whole sub-object is noise — and dropping it
+  // keeps a merchant who deleted their extra images back at the exact document
+  // they had before.
+  if (landscape.length === 0 && portrait.length === 0) return null
+  return {
+    landscape: landscape.length > 0 ? landscape : undefined,
+    portrait: portrait.length > 0 ? portrait : undefined,
+    intervalMs: typeof intervalMs === 'number' && intervalMs > 0 ? intervalMs : undefined
+  }
+}
+
+/**
+ * The cover fields to store for a new list on one orientation. Pure: returns a
+ * patch, never mutates `fields`.
+ *
+ * The other orientation is carried across from what is STORED, not from what
+ * `readCoverImages` would show. Reading would promote that side's single image
+ * into a one-entry carousel list, which changes its document for no reason.
+ */
+export function applyCoverImages(
+  fields: CoverImageFields,
+  orientation: CoverOrientation,
+  images: string[]
+): CoverImageFields {
+  const next = cleanList(images).slice(0, MAX_COVER_IMAGES)
+  const other: CoverOrientation = orientation === 'landscape' ? 'portrait' : 'landscape'
+
+  const lists: Record<CoverOrientation, string[]> = {
+    [orientation]: next.length > 1 ? next : [],
+    [other]: storedList(fields, other)
+  } as Record<CoverOrientation, string[]>
+
+  return {
+    coverImageLandscape:
+      orientation === 'landscape' ? (next[0] ?? null) : fields.coverImageLandscape,
+    coverImagePortrait:
+      orientation === 'portrait' ? (next[0] ?? null) : fields.coverImagePortrait,
+    coverCarousel: buildCarousel(
+      lists.landscape,
+      lists.portrait,
+      fields.coverCarousel?.intervalMs
+    )
+  }
+}
+
+/**
+ * The cover fields to store for a new hold time. `null` clears it, which puts
+ * the kiosk back on its own default rather than pinning a number.
+ */
+export function applyIntervalSeconds(
+  fields: CoverImageFields,
+  seconds: number | null
+): CoverImageFields {
+  const clamped =
+    seconds == null || !Number.isFinite(seconds)
+      ? null
+      : Math.min(MAX_COVER_INTERVAL_SECONDS, Math.max(MIN_COVER_INTERVAL_SECONDS, Math.round(seconds)))
+
+  return {
+    coverImageLandscape: fields.coverImageLandscape,
+    coverImagePortrait: fields.coverImagePortrait,
+    coverCarousel: buildCarousel(
+      storedList(fields, 'landscape'),
+      storedList(fields, 'portrait'),
+      clamped == null ? null : clamped * 1000
+    )
+  }
+}
+
+/** Move the image at `from` to `to`, returning a new list. Out-of-range is a no-op. */
+export function reorderCoverImages(images: string[], from: number, to: number): string[] {
+  if (from === to) return [...images]
+  if (from < 0 || to < 0 || from >= images.length || to >= images.length) return [...images]
+  const next = [...images]
+  const [moved] = next.splice(from, 1)
+  next.splice(to, 0, moved)
+  return next
+}