Merge pull request 'Refactor stock API to replace numeric flags with boolean values, add getItemLabel endpoint, and update tests/documentation' (#10) from codex/update-rest-api-integration into main

Reviewed-on: #10

AGENTS.md

@@ -82,16 +82,20 @@ These are current project assumptions and should not be casually changed.
 - `/{database}/user/application/`
 - `/{database}/kitchen/kitchens`
 - `/{database}/kitchen/items`
+- `/{database}/kitchen/items/upsert`
 - `/{database}/kitchen/items/grouped`
 - `/{database}/kitchen/items/{uuid_b64}`
 - `/{database}/kitchen/items/{uuid_b64}/stock`
+- `/{database}/kitchen/items/{uuid_b64}/use`
+- `/{database}/kitchen/changes`
 - `/{database}/kitchen/locations`
 
 ### Labels
 
 - Preview uses label-preview flags
-- Create uses label-generation flags
+- Submit/create flow uses upsert apply (`/kitchen/items/upsert?mode=apply`)
-- Actual create currently also needs `print=1`
+- UI exposes a `Print` checkbox next to save (default on for current page session)
+- If `Print` is enabled and save succeeds, label printing uses `/kitchen/items/{uuid_b64}/print-label`
 
 ### Item-definition search for label creation
 
@@ -106,17 +110,29 @@ Reason:
 - grouped result is a better template for “new item from existing definition”
 - not expanding children keeps the query lighter
 
+### List pagination
+
+- `GET /{database}/kitchen/items` and `GET /{database}/kitchen/items/grouped` are paginated (`limit`/`offset`, backend default `limit=100`)
+- frontend API helpers aggregate pages when no explicit `limit`/`offset` is requested
+
 ### Grouped stock view
 
 Grouped stock view uses:
 
-- `GET /{database}/kitchen/items/grouped?expanded=1`
+- `GET /{database}/kitchen/items/grouped?expanded=0` for summary
+- `GET /{database}/kitchen/items/grouped?expanded=1` for hydrated child details
 
 Important:
 
 - group-level fields are meaningful and should be used
 - group expiration status should follow the backend-provided “first item expires” semantics
-- do not assume grouped child records are always returned unless `expanded=1`
+- with `expanded=0`, grouped child `items` may be ID-only stubs (`{ id }`)
+- do not assume grouped child records are fully returned unless `expanded=1`
+
+### Stock updates
+
+- `POST /{database}/kitchen/items/{uuid_b64}/stock` creates a stock event and returns `{ status, stock }`
+- frontend refreshes item details with `GET /{database}/kitchen/items/{uuid_b64}` after stock updates
 
 ## UX rules that should be preserved
 

README.md

@@ -93,6 +93,7 @@ For installability and service worker support:
 
 - serve `manifest.webmanifest` with an appropriate web manifest content type
 - make sure `service-worker.js` is reachable from the deployed site root
+- make sure `version.json` is reachable from the deployed site root for app update checks
 - avoid aggressive caching on `index.html` during upgrades so new builds are picked up reliably
 
 ### Smoke test after deployment
@@ -113,6 +114,7 @@ public/
   manifest.webmanifest
   offline.html
   service-worker.js
+  version.json
 src/
   api/
   app/
@@ -135,7 +137,7 @@ Project-specific operating conventions for future contributors and coding agents
 - Active kitchen selection and switching
 - Dashboard with quick actions
 - Label creation flow with item lookup, location loading, preview, and stock entry creation
-- Stock list with search and filters
+- Grouped-first stock review with search and overview filters
 - Stock detail page with stock adjustment workflow
 - PWA manifest, icons, service worker, and offline fallback
 
@@ -147,8 +149,8 @@ Default endpoint placeholders live in [`src/app/config.js`](/Users/blaz/PycharmP
 
 Expected shapes today:
 
-- Kitchen-scoped application resources use:
+- Kitchen application resources use database-scoped routes:
-  `/{database}/kitchen/{kitchen_id}/{resource}`
+  `/{database}/kitchen/{resource}`
 - User application key management uses:
   `/{database}/user/application/`
 
@@ -161,24 +163,48 @@ Expected shapes today:
   Returns `{ data: [...] }` or `{ kitchens: [...] }`.
 - `GET /{database}/kitchen/items?search_name=...`
   Returns item definitions for autocomplete.
+  Item payloads now expose category links via `categories` (array of IDs).
 - `GET /{database}/kitchen/items`
-  Returns the current stock review list.
+  Returns the current stock review list. Endpoint is paginated (`limit`/`offset`, backend default `limit=100`); frontend helpers aggregate pages by default unless explicit pagination is passed.
+- `GET /{database}/kitchen/items/grouped?expanded=true|false`
+  Returns grouped stock data; grouped review uses summary-first loading (`expanded=false`) and hydrates item children in background (`expanded=true`).
+  With `expanded=false`, child `items` can be ID-only stubs (`{ id }`) instead of full item payloads.
 - `GET /{database}/kitchen/items/{uuid_b64}`
   Returns one item detail payload.
-- `POST /{database}/kitchen/items?label=1`
+  Supports `allow_inactive=true|false` query filtering when needed.
-  Creates a stock item plus label-related output on the backend side.
+- `GET /{database}/kitchen/changes`
-- `POST /{database}/kitchen/items?label=1&preview=1`
+  Returns `{ since, next_cursor, changes }` feed payload for item/stock updates.
+- `POST /{database}/kitchen/items/upsert?mode=preview|apply`
+  Used by label submit flow for create-or-update behavior and conflict-safe matching.
+- `POST /{database}/kitchen/items/lookup`
+  Identifier lookup response includes source/freshness metadata (`source`, `cache_hit`, `stale_cache`, `payload_fetched_at`, `retry_after_seconds`) used for richer user feedback.
+- `POST /{database}/kitchen/items/{uuid_b64}/lookup?update=true|false`
+  Item-scoped OpenFoodFacts lookup used by stock detail to preview (`update=false`) or apply missing fields (`update=true`).
+- `POST /{database}/kitchen/items?label=true&preview=true`
   Returns an image blob, `{ imageUrl }`, or `{ imageSvg }` for in-browser preview.
+- `GET /{database}/kitchen/items/{uuid_b64}/label`
+  Returns rendered label PNG for an existing item.
 - `POST /{database}/kitchen/items/{uuid_b64}/stock`
-  Updates measured or descriptive stock state using `{ quantity }` or `{ level }`.
+  Creates a stock event for measured or descriptive updates using `{ quantity }` or `{ level }`,
-- `DELETE /{database}/kitchen/items/{uuid_b64}`
+  and for non-consumed gone transitions (for example `{ level: "gone", gone_reason: "spoiled" }`).
-  Marks an individual stock item gone.
+  Response shape is `{ status, stock }`; frontend re-fetches the item detail after successful update.
+- `POST /{database}/kitchen/items/{uuid_b64}/use`
+  Marks an item consumed/used up (`gone`) via stock-event semantics.
+- `POST /{database}/kitchen/items/{uuid_b64}/print-label`
+  Prints label for an existing item; called from the save flow when `Print` is enabled.
+- `PATCH /{database}/kitchen/items/{uuid_b64}`
+  Used for item-level edits from stock detail (for example identifier code updates).
 - `GET /{database}/kitchen/locations`
   Returns a nested location tree.
+- `GET /{database}/kitchen/categories`
+  Returns categories (paged). Frontend now resolves category labels from
+  `categories_detail` when present, and falls back to this endpoint by ID.
 
 ## Notes
 
 - Hash-based routing is used to keep static deployment simple.
 - Local storage only keeps non-sensitive app config, session payload, active kitchen, and label draft state.
 - Kitchen context now lives in the URL path instead of a custom header.
-- `includeKitchen: false` in the API client only removes the kitchen path segment; it does not disable bearer authentication.
+- The API client now builds database-scoped kitchen routes by default; it always keeps bearer authentication handling separate from URL shaping.
+- Label submit uses upsert-first apply semantics and an optional `Print` checkbox (default on for the current page session).
+- Stock detail supports inline identifier editing and OpenFoodFacts refresh/apply actions with rate-limit and cache-freshness hints.

package-lock.json

@@ -1,13 +1,14 @@
 {
   "name": "lonc-web",
-  "version": "0.1.0",
+  "version": "0.2.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "lonc-web",
-      "version": "0.1.0",
+      "version": "0.2.6",
       "dependencies": {
+        "@zxing/browser": "^0.1.5",
         "alpinejs": "^3.14.9",
         "bootstrap": "^5.3.3"
       },
@@ -1099,6 +1100,41 @@
       "integrity": "sha512-oJ4F3TnvpXaQwZJNF3ZK+kLPHKarDmJjJ6jyzVNDKH9md1dptjC7lWR//jrGuLdek/U6iltWxqAnYOu8gCiOvA==",
       "license": "MIT"
     },
+    "node_modules/@zxing/browser": {
+      "version": "0.1.5",
+      "resolved": "https://registry.npmjs.org/@zxing/browser/-/browser-0.1.5.tgz",
+      "integrity": "sha512-4Lmrn/il4+UNb87Gk8h1iWnhj39TASEHpd91CwwSJtY5u+wa0iH9qS0wNLAWbNVYXR66WmT5uiMhZ7oVTrKfxw==",
+      "license": "MIT",
+      "optionalDependencies": {
+        "@zxing/text-encoding": "^0.9.0"
+      },
+      "peerDependencies": {
+        "@zxing/library": "^0.21.0"
+      }
+    },
+    "node_modules/@zxing/library": {
+      "version": "0.21.3",
+      "resolved": "https://registry.npmjs.org/@zxing/library/-/library-0.21.3.tgz",
+      "integrity": "sha512-hZHqFe2JyH/ZxviJZosZjV+2s6EDSY0O24R+FQmlWZBZXP9IqMo7S3nb3+2LBWxodJQkSurdQGnqE7KXqrYgow==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "ts-custom-error": "^3.2.1"
+      },
+      "engines": {
+        "node": ">= 10.4.0"
+      },
+      "optionalDependencies": {
+        "@zxing/text-encoding": "~0.9.0"
+      }
+    },
+    "node_modules/@zxing/text-encoding": {
+      "version": "0.9.0",
+      "resolved": "https://registry.npmjs.org/@zxing/text-encoding/-/text-encoding-0.9.0.tgz",
+      "integrity": "sha512-U/4aVJ2mxI0aDNI8Uq0wEhMgY+u4CNtEb0om3+y3+niDAsoTCOB33UF0sxpzqzdqXLqmvc+vZyAt4O8pPdfkwA==",
+      "license": "(Unlicense OR Apache-2.0)",
+      "optional": true
+    },
     "node_modules/alpinejs": {
       "version": "3.15.11",
       "resolved": "https://registry.npmjs.org/alpinejs/-/alpinejs-3.15.11.tgz",
@@ -1601,6 +1637,16 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/ts-custom-error": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/ts-custom-error/-/ts-custom-error-3.3.1.tgz",
+      "integrity": "sha512-5OX1tzOjxWEgsr/YEUWSuPrQ00deKLh6D7OTWcvNHm12/7QPyRh8SYpyWvA4IZv8H/+GQWQEh/kwo95Q9OVW1A==",
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
     "node_modules/vite": {
       "version": "7.3.1",
       "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.1.tgz",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "lonc-web",
-  "version": "0.1.0",
+  "version": "0.2.6",
   "private": true,
   "type": "module",
   "scripts": {
@@ -12,6 +12,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "@zxing/browser": "^0.1.5",
     "alpinejs": "^3.14.9",
     "bootstrap": "^5.3.3"
   },

public/service-worker.js

@@ -3,7 +3,6 @@ const APP_SHELL = ['/', '/index.html', '/manifest.webmanifest', '/offline.html',
 
 self.addEventListener('install', (event) => {
   event.waitUntil(caches.open(CACHE_NAME).then((cache) => cache.addAll(APP_SHELL)));
-  self.skipWaiting();
 });
 
 self.addEventListener('activate', (event) => {
@@ -19,6 +18,12 @@ self.addEventListener('activate', (event) => {
   self.clients.claim();
 });
 
+self.addEventListener('message', (event) => {
+  if (event?.data?.type === 'SKIP_WAITING') {
+    self.skipWaiting();
+  }
+});
+
 self.addEventListener('fetch', (event) => {
   if (event.request.method !== 'GET') {
     return;
@@ -40,6 +45,11 @@ self.addEventListener('fetch', (event) => {
     return;
   }
 
+  if (requestUrl.pathname === '/version.json') {
+    event.respondWith(fetch(event.request, { cache: 'no-store' }));
+    return;
+  }
+
   const destination = event.request.destination;
   if (
     destination === 'script' ||

src/api/auth.js

@@ -22,7 +22,6 @@ export async function login(store, credentials) {
       user: credentials.userLogin,
       application: TRYTON_APPLICATION,
     },
-    includeKitchen: false,
   });
 
   const applicationKey = extractKey(payload);
@@ -66,7 +65,6 @@ export async function logout(store) {
           key: store.session.applicationKey,
           application: TRYTON_APPLICATION,
         },
-        includeKitchen: false,
         skipAuthFailureHandler: true,
       });
     }

src/api/categories.js

@@ -0,0 +1,90 @@
+import { apiRequest, getPath } from './client.js';
+
+const DEFAULT_LIST_PAGE_LIMIT = 100;
+
+function unwrapListPayload(payload) {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  return payload?.data || payload?.entries || payload?.items || payload?.categories || [];
+}
+
+function hasExplicitPagination(filters = {}) {
+  return (
+    (filters.limit !== undefined && filters.limit !== null)
+    || (filters.offset !== undefined && filters.offset !== null)
+  );
+}
+
+function buildCategoryQuery(filters = {}) {
+  const query = {};
+  const searchName = filters.searchName || filters.search_name;
+  if (searchName) {
+    query.search_name = searchName;
+  }
+
+  if (filters.active !== undefined && filters.active !== null && filters.active !== '') {
+    query.active = Boolean(filters.active);
+  }
+
+  if (filters.orderBy || filters.order_by) {
+    query.order_by = filters.orderBy || filters.order_by;
+  }
+
+  if (filters.orderDir || filters.order_dir) {
+    query.order_dir = filters.orderDir || filters.order_dir;
+  }
+
+  if (filters.expanded !== undefined && filters.expanded !== null && filters.expanded !== '') {
+    query.expanded = Boolean(filters.expanded);
+  }
+
+  return query;
+}
+
+async function fetchAllCategoryPages(store, baseQuery = {}) {
+  const items = [];
+  let offset = 0;
+
+  while (true) {
+    const payload = await apiRequest(store, getPath('categories'), {
+      query: {
+        ...baseQuery,
+        limit: DEFAULT_LIST_PAGE_LIMIT,
+        offset,
+      },
+    });
+    const pageItems = unwrapListPayload(payload);
+    items.push(...pageItems);
+
+    if (pageItems.length < DEFAULT_LIST_PAGE_LIMIT) {
+      break;
+    }
+
+    offset += DEFAULT_LIST_PAGE_LIMIT;
+  }
+
+  return items;
+}
+
+export async function listCategories(store, filters = {}) {
+  const baseQuery = buildCategoryQuery(filters);
+
+  if (hasExplicitPagination(filters)) {
+    const query = { ...baseQuery };
+    if (filters.limit !== undefined && filters.limit !== null) {
+      query.limit = filters.limit;
+    }
+    if (filters.offset !== undefined && filters.offset !== null) {
+      query.offset = filters.offset;
+    }
+
+    const payload = await apiRequest(store, getPath('categories'), {
+      query,
+    });
+    return unwrapListPayload(payload);
+  }
+
+  return fetchAllCategoryPages(store, baseQuery);
+}

src/api/client.js

@@ -20,7 +20,7 @@ function isSameOriginBaseUrl(baseUrl) {
   }
 }
 
-function buildPathname({ database, kitchenId, path, includeKitchen = true }) {
+function buildPathname({ database, path }) {
   const encodedDatabase = encodeURIComponent(database);
   const rawPath = String(path || '').replace(/^\/+/, '');
   const keepTrailingSlash = rawPath.endsWith('/');
@@ -30,23 +30,17 @@ function buildPathname({ database, kitchenId, path, includeKitchen = true }) {
     .map((segment) => encodeURIComponent(segment));
   const segments = [encodedDatabase];
 
-  if (includeKitchen && kitchenId) {
-    segments.push('kitchen', encodeURIComponent(String(kitchenId)));
-  }
-
   segments.push(...encodedPathSegments);
 
   const pathname = `/${segments.join('/')}`;
   return keepTrailingSlash ? `${pathname}/` : pathname;
 }
 
-function buildUrl({ baseUrl, database, kitchenId, path, query = {}, includeKitchen = true }) {
+function buildUrl({ baseUrl, database, path, query = {} }) {
   const cleanBaseUrl = normalizeBaseUrl(baseUrl);
   const pathname = buildPathname({
     database,
-    kitchenId,
     path,
-    includeKitchen,
   });
   const searchParams = new URLSearchParams();
 
@@ -191,6 +185,10 @@ function isKitchensPath(path) {
   return String(path || '').replace(/^\/+/, '').replace(/\/+$/, '') === API_PATHS.kitchens;
 }
 
+function isKitchenApiPath(path) {
+  return String(path || '').replace(/^\/+/, '').startsWith('kitchen/');
+}
+
 function shouldInvalidateValidatedSession(store, path, options = {}) {
   if (options.skipAuthFailureHandler) {
     return false;
@@ -202,15 +200,16 @@ function shouldInvalidateValidatedSession(store, path, options = {}) {
 
   return (
     isKitchensPath(path) ||
-    options.includeKitchen !== false ||
+    isKitchenApiPath(path) ||
     path === API_PATHS.items ||
     path === API_PATHS.locations ||
+    path === API_PATHS.changes ||
     String(path || '').startsWith(`${API_PATHS.items}/`)
   );
 }
 
 export async function apiRequest(store, path, options = {}) {
-  const { config, session, activeKitchen } = store;
+  const { config, session } = store;
 
   if (!config.database) {
     throw new Error('Database name is required.');
@@ -220,10 +219,8 @@ export async function apiRequest(store, path, options = {}) {
   const url = buildUrl({
     baseUrl: config.baseUrl,
     database: config.database,
-    kitchenId: activeKitchen?.id,
     path,
     query: options.query,
-    includeKitchen: options.includeKitchen !== false,
   });
   const headers = new Headers(options.headers || {});
   headers.set('Accept', options.accept || 'application/json');
@@ -304,9 +301,7 @@ export function buildKitchenApiUrl(store, path, query = {}) {
   return buildUrl({
     baseUrl: store.config.baseUrl,
     database: store.config.database,
-    kitchenId: store.activeKitchen?.id,
     path,
     query,
-    includeKitchen: true,
   });
 }

src/api/kitchens.js

@@ -1,9 +1,7 @@
 import { apiRequest, getPath } from './client.js';
 
 export async function listKitchens(store) {
-  const payload = await apiRequest(store, getPath('kitchens'), {
+  const payload = await apiRequest(store, getPath('kitchens'));
-    includeKitchen: false,
-  });
   if (Array.isArray(payload)) {
     return payload;
   }

src/api/labels.js

@@ -42,8 +42,7 @@ export async function previewLabel(store, body) {
     method: 'POST',
     body,
     accept: 'image/svg+xml, image/png, application/json',
-    includeKitchen: false,
+    query: { label: true, preview: true },
-    query: { label: 1, preview: 1 },
   });
 
   const image = normalizeLabelImagePayload(payload);
@@ -53,3 +52,70 @@ export async function previewLabel(store, body) {
 
   throw new Error('Label preview response did not include an image.');
 }
+
+export async function getItemLabel(store, uuidB64) {
+  const payload = await apiRequest(store, `${getPath('items')}/${uuidB64}/label`, {
+    method: 'GET',
+    accept: 'image/png, application/json',
+  });
+  const image = normalizeLabelImagePayload(payload);
+  if (image) {
+    return image;
+  }
+
+  throw new Error('Item label response did not include an image.');
+}
+
+export async function printItemLabel(store, uuidB64) {
+  return apiRequest(store, `${getPath('items')}/${uuidB64}/print-label`, {
+    method: 'POST',
+  });
+}
+
+function flattenDetails(details) {
+  if (!details) {
+    return '';
+  }
+
+  if (typeof details === 'string') {
+    return details;
+  }
+
+  if (Array.isArray(details)) {
+    return details
+      .map((entry) => (typeof entry === 'string' ? entry : JSON.stringify(entry)))
+      .join(' | ');
+  }
+
+  if (typeof details === 'object') {
+    return Object.entries(details)
+      .map(([key, value]) => `${key}: ${value}`)
+      .join(' | ');
+  }
+
+  return String(details);
+}
+
+export function formatPrintErrorMessage(error) {
+  const status = error?.status || error?.cause?.status;
+  const payload = error?.payload || error?.cause?.payload || {};
+  const code = String(payload?.code || '').toLowerCase();
+  const detailsText = flattenDetails(payload?.details || error?.details || error?.cause?.details);
+
+  let message;
+  if (code === 'printer_unavailable') {
+    message = 'Printer is unavailable.';
+  } else if (code === 'print_failed') {
+    message = 'Label printing failed.';
+  } else if (status === 503) {
+    message = 'Printer service is unavailable.';
+  } else if (status === 404) {
+    message = 'Saved item could not be found for printing.';
+  } else if (status === 400) {
+    message = 'Print request was invalid.';
+  } else {
+    message = error?.message || 'Printing failed.';
+  }
+
+  return detailsText ? `${message} (${detailsText})` : message;
+}

src/api/locations.js

@@ -42,9 +42,7 @@ export async function fetchLocations(store) {
     return cached.value;
   }
 
-  const payload = await apiRequest(store, getPath('locations'), {
+  const payload = await apiRequest(store, getPath('locations'));
-    includeKitchen: false,
-  });
   const tree = Array.isArray(payload)
     ? payload
     : payload?.data || payload?.locations || [];

src/api/stock.js

@@ -1,17 +1,87 @@
 import { apiRequest, getPath } from './client.js';
 
+const DEFAULT_LIST_PAGE_LIMIT = 100;
+
+function toBooleanFlag(value, defaultValue = false) {
+  if (value === undefined || value === null || value === '') {
+    return defaultValue;
+  }
+
+  if (typeof value === 'boolean') {
+    return value;
+  }
+
+  if (typeof value === 'number') {
+    return value !== 0;
+  }
+
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) {
+      return defaultValue;
+    }
+    if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) {
+      return true;
+    }
+    if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) {
+      return false;
+    }
+  }
+
+  return Boolean(value);
+}
+
 function unwrapEntryPayload(payload) {
   return payload?.data || payload?.entry || payload?.item || payload;
 }
 
+function unwrapListPayload(payload) {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  return payload?.data || payload?.entries || payload?.items || payload?.groups || [];
+}
+
+function hasExplicitPagination(filters = {}) {
+  return (
+    (filters.limit !== undefined && filters.limit !== null)
+    || (filters.offset !== undefined && filters.offset !== null)
+  );
+}
+
+async function fetchAllListPages(store, path, baseQuery = {}) {
+  const items = [];
+  let offset = 0;
+
+  while (true) {
+    const payload = await apiRequest(store, path, {
+      query: {
+        ...baseQuery,
+        limit: DEFAULT_LIST_PAGE_LIMIT,
+        offset,
+      },
+    });
+    const pageItems = unwrapListPayload(payload);
+    items.push(...pageItems);
+
+    if (pageItems.length < DEFAULT_LIST_PAGE_LIMIT) {
+      break;
+    }
+
+    offset += DEFAULT_LIST_PAGE_LIMIT;
+  }
+
+  return items;
+}
+
 export async function searchItemDefinitions(store, query) {
   if (query.trim().length <= 2) {
     return [];
   }
 
   const payload = await apiRequest(store, `${getPath('items')}/grouped`, {
-    includeKitchen: false,
+    query: { search_name: query, expanded: false },
-    query: { search_name: query, expanded: 0 },
   });
 
   if (Array.isArray(payload)) {
@@ -22,34 +92,64 @@ export async function searchItemDefinitions(store, query) {
 }
 
 export async function listStockEntries(store, filters = {}) {
+  const baseQuery = {};
+  const searchName = filters.searchName || filters.search_name;
+  if (searchName) {
+    baseQuery.search_name = searchName;
+  }
+
+  if (hasExplicitPagination(filters)) {
+    const query = { ...baseQuery };
+    if (filters.limit !== undefined && filters.limit !== null) {
+      query.limit = filters.limit;
+    }
+    if (filters.offset !== undefined && filters.offset !== null) {
+      query.offset = filters.offset;
+    }
+
     const payload = await apiRequest(store, getPath('items'), {
-    includeKitchen: false,
+      query,
     });
 
-  if (Array.isArray(payload)) {
+    return unwrapListPayload(payload);
-    return payload;
   }
 
-  return payload?.data || payload?.entries || payload?.items || [];
+  return fetchAllListPages(store, getPath('items'), baseQuery);
 }
 
-export async function listGroupedStockEntries(store) {
+export async function listGroupedStockEntries(store, options = {}) {
+  const baseQuery = {};
+  const expanded = toBooleanFlag(options.expanded, true);
+  baseQuery.expanded = expanded;
+  const searchName = options.searchName || options.search_name;
+  if (searchName) {
+    baseQuery.search_name = searchName;
+  }
+
+  if (hasExplicitPagination(options)) {
+    const query = { ...baseQuery };
+    if (options.limit !== undefined && options.limit !== null) {
+      query.limit = options.limit;
+    }
+    if (options.offset !== undefined && options.offset !== null) {
+      query.offset = options.offset;
+    }
+
     const payload = await apiRequest(store, `${getPath('items')}/grouped`, {
-    includeKitchen: false,
+      query,
-    query: { expanded: 1 },
     });
 
-  if (Array.isArray(payload)) {
+    return unwrapListPayload(payload);
-    return payload;
   }
 
-  return payload?.data || payload?.entries || payload?.items || payload?.groups || [];
+  return fetchAllListPages(store, `${getPath('items')}/grouped`, baseQuery);
 }
 
-export async function getStockEntry(store, stockId) {
+export async function getStockEntry(store, stockId, { allowInactive = false } = {}) {
-  const payload = await apiRequest(store, `${getPath('items')}/${stockId}`, {
+  const path = `${getPath('items')}/${stockId}`;
-    includeKitchen: false,
+  const payload = allowInactive
-  });
+    ? await apiRequest(store, path, { query: { allow_inactive: true } })
+    : await apiRequest(store, path);
   return unwrapEntryPayload(payload);
 }
 
@@ -57,34 +157,212 @@ export async function createStockEntry(store, body) {
   const payload = await apiRequest(store, getPath('items'), {
     method: 'POST',
     body,
-    includeKitchen: false,
+    query: { label: true, print: true },
-    query: { label: 1, print: 1 },
+  });
+  return unwrapEntryPayload(payload);
+}
+
+function normalizeUpsertResponse(payload) {
+  return {
+    status: payload?.status || null,
+    mode: payload?.mode || null,
+    operation: payload?.operation || null,
+    matchType: payload?.match_type || null,
+    matchedItem: payload?.matched_item || null,
+    item: payload?.item || null,
+    payload: payload?.payload || null,
+  };
+}
+
+function normalizeIdentifierLookupResponse(payload) {
+  return {
+    status: payload?.status || null,
+    source: payload?.source || null,
+    cacheHit: Boolean(payload?.cache_hit),
+    identifierCode: payload?.identifier_code || null,
+    identifierType: payload?.identifier_type || null,
+    item: payload?.item || null,
+    payloadFetchedAt: payload?.payload_fetched_at || null,
+    retryAfterSeconds:
+      Number.isInteger(payload?.retry_after_seconds) ? payload.retry_after_seconds : null,
+    staleCache: Boolean(payload?.stale_cache),
+  };
+}
+
+function normalizeItemLookupResponse(payload) {
+  return {
+    status: payload?.status || null,
+    found: Boolean(payload?.found),
+    update: Boolean(payload?.update),
+    identifierCode: payload?.identifier_code || null,
+    identifierType: payload?.identifier_type || null,
+    preview: payload?.preview || null,
+    updatedFields: Array.isArray(payload?.updated_fields) ? payload.updated_fields : [],
+    offPayloadFetchedAt: payload?.off_payload_fetched_at || null,
+    retryAfterSeconds:
+      Number.isInteger(payload?.retry_after_seconds) ? payload.retry_after_seconds : null,
+    staleCache: Boolean(payload?.stale_cache),
+    item: payload?.item || null,
+  };
+}
+
+export async function previewItemUpsert(store, body) {
+  const payload = await apiRequest(store, `${getPath('items')}/upsert`, {
+    method: 'POST',
+    body,
+    query: { mode: 'preview' },
+  });
+
+  return normalizeUpsertResponse(payload);
+}
+
+export async function applyItemUpsert(store, body) {
+  const payload = await apiRequest(store, `${getPath('items')}/upsert`, {
+    method: 'POST',
+    body,
+    query: { mode: 'apply' },
+  });
+
+  return normalizeUpsertResponse(payload);
+}
+
+export async function lookupItemByIdentifier(store, identifierCode) {
+  const payload = await apiRequest(store, `${getPath('items')}/lookup`, {
+    method: 'POST',
+    body: {
+      identifier_code: String(identifierCode || '').trim(),
+    },
+  });
+
+  return normalizeIdentifierLookupResponse(payload);
+}
+
+export async function lookupItemDetails(store, uuidB64, { update = false } = {}) {
+  const payload = await apiRequest(store, `${getPath('items')}/${uuidB64}/lookup`, {
+    method: 'POST',
+    query: { update: toBooleanFlag(update, false) },
+  });
+
+  return normalizeItemLookupResponse(payload);
+}
+
+export async function patchStockItem(store, uuidB64, body) {
+  const payload = await apiRequest(store, `${getPath('items')}/${uuidB64}`, {
+    method: 'PATCH',
+    body,
   });
   return unwrapEntryPayload(payload);
 }
 
 export async function updateStockItem(store, uuidB64, body) {
+  await apiRequest(store, `${getPath('items')}/${uuidB64}/stock`, {
+    method: 'POST',
+    body,
+  });
+  return getStockEntry(store, uuidB64, {
+    allowInactive: body?.level === 'gone' || Number(body?.quantity) <= 0,
+  });
+}
+
+export async function createStockEvent(store, uuidB64, body) {
   const payload = await apiRequest(store, `${getPath('items')}/${uuidB64}/stock`, {
     method: 'POST',
     body,
-    includeKitchen: false,
   });
-  return unwrapEntryPayload(payload);
+  return payload?.stock || payload;
+}
+
+export async function listStockEvents(store, uuidB64, options = {}) {
+  const query = {};
+  if (options.allowInactive) {
+    query.allow_inactive = true;
+  }
+  if (options.limit !== undefined && options.limit !== null) {
+    query.limit = options.limit;
+  }
+  if (options.offset !== undefined && options.offset !== null) {
+    query.offset = options.offset;
+  }
+  if (options.orderBy || options.order_by) {
+    query.order_by = options.orderBy || options.order_by;
+  }
+  if (options.orderDir || options.order_dir) {
+    query.order_dir = options.orderDir || options.order_dir;
+  }
+
+  const payload = await apiRequest(store, `${getPath('items')}/${uuidB64}/stock`, {
+    query,
+  });
+  return unwrapListPayload(payload);
+}
+
+export async function markStockGone(store, uuidB64, reason = 'consumed') {
+  try {
+    if (reason === 'consumed') {
+      const result = await useStockItem(store, uuidB64);
+      if (result.status === 'already_gone') {
+        return { status: 'already_gone', reason };
+      }
+      return { status: 'gone', reason };
+    }
+
+    await createStockEvent(store, uuidB64, {
+      level: 'gone',
+      gone_reason: reason,
+    });
+    return { status: 'gone', reason };
+  } catch (error) {
+    const status = error?.status || error?.cause?.status;
+    if (status === 409 || status === 404) {
+      return { status: 'already_gone', reason };
+    }
+
+    throw error;
+  }
 }
 
 export async function deleteStockItem(store, uuidB64) {
   const payload = await apiRequest(store, `${getPath('items')}/${uuidB64}`, {
     method: 'DELETE',
-    includeKitchen: false,
   });
   return unwrapEntryPayload(payload);
 }
 
+export async function useStockItem(store, uuidB64) {
+  try {
+    await apiRequest(store, `${getPath('items')}/${uuidB64}/use`, {
+      method: 'POST',
+    });
+    return { status: 'used' };
+  } catch (error) {
+    const status = error?.status || error?.cause?.status;
+    if (status === 409 || status === 404) {
+      return { status: 'already_gone' };
+    }
+
+    throw error;
+  }
+}
+
 export async function adjustStockEntry(store, stockId, body) {
-  const payload = await apiRequest(store, `${getPath('items')}/${stockId}/stock`, {
+  await apiRequest(store, `${getPath('items')}/${stockId}/stock`, {
     method: 'POST',
     body,
-    includeKitchen: false,
   });
-  return unwrapEntryPayload(payload);
+  return getStockEntry(store, stockId);
+}
+
+export async function listKitchenChanges(store, { since, limit = 10 } = {}) {
+  const payload = await apiRequest(store, getPath('changes'), {
+    query: {
+      since,
+      limit,
+    },
+  });
+
+  return {
+    since: payload?.since || null,
+    nextCursor: payload?.next_cursor || null,
+    changes: Array.isArray(payload?.changes) ? payload.changes : [],
+  };
 }

src/app/bootstrap.js

@@ -2,35 +2,216 @@ import Alpine from 'alpinejs';
 
 import { logout, restoreSession, verifyConnection } from '../api/auth.js';
 import { listKitchens } from '../api/kitchens.js';
-import { APP_NAME } from './config.js';
+import { APP_NAME, APP_VERSION } from './config.js';
 import { createRouter, navigate } from './router.js';
 import { createAppStore } from './store.js';
 import { appShell } from '../components/app-shell.js';
 import { navBar } from '../components/nav-bar.js';
 import { registerFeatureData } from '../features/register.js';
 
-async function installServiceWorker() {
+const APP_UPDATE_CHECK_INTERVAL_MS = 5 * 60 * 1000;
-  if (!('serviceWorker' in navigator)) {
+
+function createAppUpdateManager() {
+  let registration = null;
+  let waitingWorker = null;
+
+  async function fetchServerVersion() {
+    try {
+      const response = await fetch(`/version.json?ts=${Date.now()}`, {
+        cache: 'no-store',
+        headers: {
+          'cache-control': 'no-cache',
+          pragma: 'no-cache',
+        },
+      });
+
+      if (!response.ok) {
+        throw new Error(`Version endpoint failed with HTTP ${response.status}`);
+      }
+
+      const payload = await response.json();
+      const serverVersion = String(payload?.version || '').trim();
+      const serverBuildTime = String(payload?.buildTime || '').trim();
+
+      return {
+        serverVersion: serverVersion || null,
+        serverBuildTime: serverBuildTime || null,
+      };
+    } catch (error) {
+      return {
+        serverVersion: null,
+        serverBuildTime: null,
+        error: error instanceof Error ? error.message : 'Unable to reach version endpoint.',
+      };
+    }
+  }
+
+  function syncWaitingWorker() {
+    waitingWorker = registration?.waiting || null;
+  }
+
+  function setupRegistrationHooks() {
+    if (!registration) {
       return;
     }
 
+    syncWaitingWorker();
+
+    registration.addEventListener('updatefound', () => {
+      const installing = registration.installing;
+      if (!installing) {
+        return;
+      }
+
+      installing.addEventListener('statechange', () => {
+        if (installing.state === 'installed' && navigator.serviceWorker.controller) {
+          waitingWorker = registration.waiting || installing;
+        }
+      });
+    });
+  }
+
+  async function installServiceWorker() {
+    if (!('serviceWorker' in navigator)) {
+      return { supported: false };
+    }
+
     if (import.meta.env.DEV) {
       const registrations = await navigator.serviceWorker.getRegistrations();
-    await Promise.all(registrations.map((registration) => registration.unregister()));
+      await Promise.all(registrations.map((existingRegistration) => existingRegistration.unregister()));
+      return { supported: false, development: true };
+    }
+
+    registration = await navigator.serviceWorker.register('/service-worker.js');
+    setupRegistrationHooks();
+
+    return {
+      supported: true,
+      registered: true,
+    };
+  }
+
+  async function checkForAppUpdate() {
+    if (registration) {
+      await registration.update().catch(() => {});
+      syncWaitingWorker();
+    }
+
+    const server = await fetchServerVersion();
+    const hasVersionMismatch = Boolean(server.serverVersion && server.serverVersion !== APP_VERSION);
+
+    return {
+      supported: 'serviceWorker' in navigator,
+      currentVersion: APP_VERSION,
+      serverVersion: server.serverVersion,
+      serverBuildTime: server.serverBuildTime,
+      waitingWorker: Boolean(waitingWorker),
+      updateAvailable: Boolean(waitingWorker) || hasVersionMismatch,
+      hasVersionMismatch,
+      serverError: server.error || null,
+    };
+  }
+
+  async function waitForControllerChange(previousController, timeoutMs = 4000) {
+    if (!('serviceWorker' in navigator)) {
       return;
     }
 
-  await navigator.serviceWorker.register('/service-worker.js');
+    if (navigator.serviceWorker.controller && navigator.serviceWorker.controller !== previousController) {
+      return;
+    }
+
+    await new Promise((resolve) => {
+      let isDone = false;
+
+      const finish = () => {
+        if (isDone) {
+          return;
+        }
+
+        isDone = true;
+        navigator.serviceWorker.removeEventListener('controllerchange', onControllerChange);
+        clearTimeout(timeout);
+        resolve();
+      };
+
+      const onControllerChange = () => {
+        finish();
+      };
+
+      const timeout = setTimeout(finish, timeoutMs);
+
+      navigator.serviceWorker.addEventListener('controllerchange', onControllerChange);
+    });
+  }
+
+  async function clearAllServiceWorkerCaches() {
+    if (!('caches' in window)) {
+      return;
+    }
+
+    const keys = await caches.keys();
+    await Promise.all(keys.map((key) => caches.delete(key)));
+  }
+
+  async function applyAppUpdate() {
+    const previousController = navigator.serviceWorker?.controller || null;
+
+    if (registration) {
+      await registration.update().catch(() => {});
+      syncWaitingWorker();
+    }
+
+    if (waitingWorker) {
+      waitingWorker.postMessage({ type: 'SKIP_WAITING' });
+      await waitForControllerChange(previousController);
+    }
+
+    await clearAllServiceWorkerCaches().catch(() => {});
+
+    const nextUrl = new URL(window.location.href);
+    nextUrl.searchParams.set('app_update', String(Date.now()));
+    window.location.replace(nextUrl.toString());
+  }
+
+  function startPeriodicChecks() {
+    if (!registration) {
+      return;
+    }
+
+    window.setInterval(() => {
+      checkForAppUpdate().catch(() => {});
+    }, APP_UPDATE_CHECK_INTERVAL_MS);
+
+    document.addEventListener('visibilitychange', () => {
+      if (document.visibilityState === 'visible') {
+        checkForAppUpdate().catch(() => {});
+      }
+    });
+  }
+
+  return {
+    installServiceWorker,
+    checkForAppUpdate,
+    applyAppUpdate,
+    startPeriodicChecks,
+  };
 }
 
 export function bootstrapApp() {
   const store = createAppStore();
   Alpine.store('app', store);
 
+  const appUpdateManager = createAppUpdateManager();
+
   registerFeatureData(Alpine, store);
 
   const appRoot = document.querySelector('#app');
-  appRoot.innerHTML = appShell(APP_NAME);
+  appRoot.innerHTML = appShell(
+    APP_NAME,
+    APP_VERSION,
+    import.meta.env.DEV ? 'development' : 'production',
+  );
   Alpine.initTree(appRoot);
   const navRoot = document.querySelector('#app-nav');
 
@@ -100,6 +281,12 @@ export function bootstrapApp() {
       renderNav();
       return result;
     },
+    async checkForAppUpdate() {
+      return appUpdateManager.checkForAppUpdate();
+    },
+    async applyAppUpdate() {
+      return appUpdateManager.applyAppUpdate();
+    },
     handleAuthFailure(error) {
       if (!store.session?.applicationKey || !store.session?.hasValidated || authFailureHandled) {
         return;
@@ -148,7 +335,10 @@ export function bootstrapApp() {
 
   renderNav();
 
-  installServiceWorker().catch(() => {
+  appUpdateManager
+    .installServiceWorker()
+    .then(() => appUpdateManager.startPeriodicChecks())
+    .catch(() => {
       store.addAlert({
         type: 'warning',
         message: 'PWA installation support could not be initialized.',

src/app/config.js

@@ -1,4 +1,5 @@
 export const APP_NAME = 'Lonc';
+export const APP_VERSION = typeof __APP_VERSION__ !== 'undefined' ? __APP_VERSION__ : '0.2.6';
 export const TRYTON_APPLICATION = 'kitchen';
 
 export const CONNECTION_STATES = {
@@ -13,6 +14,7 @@ export const STORAGE_KEYS = {
   session: 'lonc.auth.session',
   activeKitchen: 'lonc.kitchen.active',
   labelDraft: 'lonc.labels.draft',
+  stockListContext: 'lonc.stock.list.context',
 };
 
 export const DEFAULT_CONFIG = {
@@ -24,13 +26,15 @@ export const API_PATHS = {
   userApplication: 'user/application/',
   kitchens: 'kitchen/kitchens',
   items: 'kitchen/items',
-  stockEntries: 'stock',
   locations: 'kitchen/locations',
+  categories: 'kitchen/categories',
+  changes: 'kitchen/changes',
 };
 
 export const ROUTES = {
   login: '/login',
   home: '/',
+  scan: '/scan',
   stock: '/stock',
   stockNew: '/stock/new',
   stockDetail: '/stock/:id',

src/app/router.js

@@ -6,10 +6,12 @@ import { renderLabelCreatePage } from '../features/labels/label-create-page.js';
 import { renderSettingsPage } from '../features/auth/settings-page.js';
 import { renderStockDetailPage } from '../features/stock/stock-detail-page.js';
 import { renderStockListPage } from '../features/stock/stock-list-page.js';
+import { renderStockScanPage } from '../features/stock/stock-scan-page.js';
 
 const routeDefinitions = [
   { path: ROUTES.login, render: renderLoginPage, protected: false },
   { path: ROUTES.home, render: renderDashboardPage, protected: true },
+  { path: ROUTES.scan, render: renderStockScanPage, protected: true },
   { path: ROUTES.stock, render: renderStockListPage, protected: true },
   { path: ROUTES.stockNew, render: renderLabelCreatePage, protected: true },
   { path: ROUTES.stockDetail, render: renderStockDetailPage, protected: true },
@@ -17,9 +19,13 @@ const routeDefinitions = [
   { path: ROUTES.settings, render: renderSettingsPage, protected: false },
 ];
 
-function normalizeHashRoute() {
+function parseHashRoute() {
   const route = window.location.hash.replace(/^#/, '') || ROUTES.home;
-  return route.startsWith('/') ? route : `/${route}`;
+  const normalized = route.startsWith('/') ? route : `/${route}`;
+  const [pathnameRaw, search = ''] = normalized.split('?');
+  const pathname = pathnameRaw || ROUTES.home;
+  const query = Object.fromEntries(new URLSearchParams(search).entries());
+  return { pathname, query };
 }
 
 function matchRoute(pathname) {
@@ -52,12 +58,12 @@ export function navigate(path) {
 }
 
 export function getRouteContext() {
-  return window.__loncRouteContext || { path: ROUTES.home, params: {} };
+  return window.__loncRouteContext || { path: ROUTES.home, params: {}, query: {} };
 }
 
 export function createRouter({ Alpine, store, outlet }) {
   const render = async () => {
-    const pathname = normalizeHashRoute();
+    const { pathname, query } = parseHashRoute();
     const match = matchRoute(pathname);
 
     if (!match) {
@@ -81,7 +87,11 @@ export function createRouter({ Alpine, store, outlet }) {
       return;
     }
 
-    window.__loncRouteContext = { path: pathname, params: match.params };
+    window.__loncRouteContext = {
+      path: pathname,
+      params: match.params,
+      query,
+    };
     outlet.innerHTML = match.render();
     Alpine.initTree(outlet);
   };

src/components/app-shell.js

@@ -1,12 +1,22 @@
 import { navBar } from './nav-bar.js';
 
-export function appShell(appName) {
+export function appShell(appName, appVersion, runtimeMode) {
+  const currentYear = new Date().getFullYear();
+
   return `
     <div class="app-shell d-flex flex-column min-vh-100">
       <div id="app-nav">
         ${navBar(appName)}
       </div>
       <main id="route-view" class="flex-grow-1"></main>
+      <footer class="app-footer border-top mt-auto py-3">
+        <div class="container-xxl d-flex flex-column flex-md-row justify-content-between align-items-md-center gap-1 small">
+          <div>&copy; ${currentYear} AKLARO</div>
+          <div class="text-body-secondary">
+            ${appName} v${appVersion} • ${runtimeMode} mode • PWA frontend for Tryton kitchen
+          </div>
+        </div>
+      </footer>
       <div class="toast-stack" x-data="alertsData()">
         <template x-for="alert in alerts" :key="alert.id">
           <div class="toast show align-items-center border-0 mb-2 text-bg-dark" role="status">

src/components/nav-bar.js

@@ -17,6 +17,9 @@ export function navBar(appName) {
             <li class="nav-item" x-show="$store.app.session?.state === 'connected'">
               <a class="nav-link" href="#/labels/new">New Label</a>
             </li>
+            <li class="nav-item" x-show="$store.app.session?.state === 'connected'">
+              <a class="nav-link" href="#/scan">Scan</a>
+            </li>
             <li class="nav-item" x-show="$store.app.session?.state === 'connected'">
               <a class="nav-link" href="#/stock">Stock</a>
             </li>

src/features/auth/settings-page.js

@@ -1,10 +1,12 @@
+import { APP_VERSION } from '../../app/config.js';
+
 export function renderSettingsPage() {
   return `
     <section class="container-xxl py-4 py-lg-5">
       <div class="row g-4">
         <div class="col-12 col-lg-7">
           <div class="card border-0 shadow-sm">
-            <div class="card-body p-4" x-data="settingsPage()">
+            <div class="card-body p-4" x-data="settingsPage()" x-init="initUpdatePanel()">
               <div class="d-flex justify-content-between align-items-start mb-4">
                 <div>
                   <p class="eyebrow mb-2">Client Settings</p>
@@ -40,6 +42,45 @@ export function renderSettingsPage() {
                 </div>
                 <button class="btn btn-primary align-self-start" type="submit">Save settings</button>
               </form>
+
+              <hr class="my-4" />
+
+              <div class="vstack gap-3">
+                <div>
+                  <h2 class="h5 mb-1">App update</h2>
+                  <p class="text-body-secondary mb-0">
+                    Check for the latest deployed build and force-refresh this installed app when needed.
+                  </p>
+                </div>
+                <div class="row g-3 small">
+                  <div class="col-12 col-md-6">
+                    <div class="border rounded-3 p-3 h-100 bg-body-tertiary">
+                      <div class="text-uppercase text-body-secondary fw-semibold mb-1">Current version</div>
+                      <div class="fw-semibold" x-text="update.currentVersion"></div>
+                    </div>
+                  </div>
+                  <div class="col-12 col-md-6">
+                    <div class="border rounded-3 p-3 h-100 bg-body-tertiary">
+                      <div class="text-uppercase text-body-secondary fw-semibold mb-1">Server version</div>
+                      <div class="fw-semibold" x-text="update.serverVersion || 'Unavailable'"></div>
+                      <template x-if="update.serverBuildTime">
+                        <div class="text-body-secondary mt-1" x-text="'Built: ' + formatBuildTime(update.serverBuildTime)"></div>
+                      </template>
+                    </div>
+                  </div>
+                </div>
+                <div class="d-flex flex-wrap align-items-center gap-2">
+                  <button class="btn btn-outline-secondary" type="button" @click="checkForUpdates()" :disabled="update.isChecking || update.isApplying">
+                    <span x-show="!update.isChecking">Check for updates</span>
+                    <span x-show="update.isChecking">Checking...</span>
+                  </button>
+                  <button class="btn btn-primary" type="button" @click="applyUpdate()" :disabled="update.isApplying">
+                    <span x-show="!update.isApplying">Update app</span>
+                    <span x-show="update.isApplying">Updating...</span>
+                  </button>
+                </div>
+                <div class="small" :class="updateStatusClass()" x-text="update.statusText"></div>
+              </div>
             </div>
           </div>
         </div>
@@ -68,6 +109,15 @@ export function settingsPageData(store) {
       baseUrl: store.config.baseUrl || '',
       database: store.config.database || '',
     },
+    update: {
+      currentVersion: APP_VERSION,
+      serverVersion: null,
+      serverBuildTime: null,
+      statusText: 'Ready to check for updates.',
+      statusType: 'secondary',
+      isChecking: false,
+      isApplying: false,
+    },
     get userLogin() {
       return store.session?.userLogin || '';
     },
@@ -83,5 +133,83 @@ export function settingsPageData(store) {
 
       store.addAlert({ type: 'success', message: 'Settings saved locally.' });
     },
+    formatBuildTime(value) {
+      const date = new Date(value);
+      if (Number.isNaN(date.getTime())) {
+        return value;
+      }
+
+      return date.toLocaleString();
+    },
+    updateStatusClass() {
+      switch (this.update.statusType) {
+        case 'success':
+          return 'text-success';
+        case 'warning':
+          return 'text-warning';
+        case 'danger':
+          return 'text-danger';
+        default:
+          return 'text-body-secondary';
+      }
+    },
+    async initUpdatePanel() {
+      await this.checkForUpdates();
+    },
+    async checkForUpdates() {
+      if (!window.__loncApp?.checkForAppUpdate) {
+        this.update.statusText = 'Service worker updates are not available in this browser.';
+        this.update.statusType = 'warning';
+        return;
+      }
+
+      this.update.isChecking = true;
+      this.update.statusText = 'Checking for updates...';
+      this.update.statusType = 'secondary';
+
+      try {
+        const result = await window.__loncApp.checkForAppUpdate();
+        this.update.currentVersion = result.currentVersion || APP_VERSION;
+        this.update.serverVersion = result.serverVersion || null;
+        this.update.serverBuildTime = result.serverBuildTime || null;
+
+        if (result.updateAvailable) {
+          this.update.statusText = 'Update available. Use "Update app" to refresh this installed build.';
+          this.update.statusType = 'warning';
+        } else if (result.serverError) {
+          this.update.statusText = `No update signal from server (${result.serverError}).`;
+          this.update.statusType = 'secondary';
+        } else {
+          this.update.statusText = 'This app is up to date.';
+          this.update.statusType = 'success';
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown update check error.';
+        this.update.statusText = `Update check failed: ${message}`;
+        this.update.statusType = 'danger';
+      } finally {
+        this.update.isChecking = false;
+      }
+    },
+    async applyUpdate() {
+      if (!window.__loncApp?.applyAppUpdate) {
+        this.update.statusText = 'Update action is not available in this browser.';
+        this.update.statusType = 'warning';
+        return;
+      }
+
+      this.update.isApplying = true;
+      this.update.statusText = 'Applying update and refreshing app...';
+      this.update.statusType = 'warning';
+
+      try {
+        await window.__loncApp.applyAppUpdate();
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown update error.';
+        this.update.statusText = `Update failed: ${message}`;
+        this.update.statusType = 'danger';
+        this.update.isApplying = false;
+      }
+    },
   };
 }

src/features/dashboard/dashboard-page.js

@@ -1,6 +1,10 @@
+import { fetchLocations } from '../../api/locations.js';
+import { getStockEntry, listKitchenChanges } from '../../api/stock.js';
+import { createAsyncState, runAsyncState } from '../shared/ui-state.js';
+
 export function renderDashboardPage() {
   return `
-    <section class="container-xxl py-4 py-lg-5" x-data="dashboardPage()">
+    <section class="container-xxl py-4 py-lg-5" x-data="dashboardPage()" x-init="init()">
       <div class="hero-card p-4 p-lg-5 mb-4">
         <div class="row align-items-center g-4">
           <div class="col-12 col-lg-7">
@@ -11,6 +15,7 @@ export function renderDashboardPage() {
             </p>
             <div class="d-flex flex-wrap gap-2">
               <a href="#/labels/new" class="btn btn-primary btn-lg">Create label</a>
+              <a href="#/scan" class="btn btn-outline-primary btn-lg">Scan item</a>
               <a href="#/stock" class="btn btn-outline-primary btn-lg">Browse stock</a>
             </div>
           </div>
@@ -66,10 +71,10 @@ export function renderDashboardPage() {
           </a>
         </div>
         <div class="col-12 col-md-6 col-xl-3">
-          <a class="quick-card" href="#/stock">
+          <a class="quick-card" href="#/scan">
-            <span class="quick-card-label">Adjustments</span>
+            <span class="quick-card-label">Scanning</span>
-            <strong>Fast quantity updates</strong>
+            <strong>Use, spoil, or inspect</strong>
-            <span class="text-body-secondary">Apply increments, decrements, or exact counts with clear feedback.</span>
+            <span class="text-body-secondary">Scan a label or barcode and act on the matching item.</span>
           </a>
         </div>
         <div class="col-12 col-md-6 col-xl-3">
@@ -80,6 +85,52 @@ export function renderDashboardPage() {
           </a>
         </div>
       </div>
+
+      <div class="row g-4 mt-1">
+        <div class="col-12">
+          <div class="card border-0 shadow-sm">
+            <div class="card-body p-4">
+              <div class="d-flex flex-wrap justify-content-between align-items-center gap-2 mb-3">
+                <div>
+                  <h2 class="h5 mb-1">Recent changes</h2>
+                  <p class="text-body-secondary mb-0 small">Latest item and stock updates from the kitchen change feed.</p>
+                  <p class="text-body-secondary mb-0 small">Saved means the backend created or updated a record.</p>
+                </div>
+                <button class="btn btn-outline-secondary btn-sm" @click="refreshChanges()" :disabled="changesState.isLoading">
+                  <span x-show="!changesState.isLoading">Refresh</span>
+                  <span x-show="changesState.isLoading">Refreshing...</span>
+                </button>
+              </div>
+
+              <template x-if="changesState.error">
+                <div class="alert alert-warning mb-0" x-text="changesState.error"></div>
+              </template>
+
+              <template x-if="!changesState.error && changesState.isLoading && !recentChanges.length">
+                <div class="text-body-secondary">Loading changes...</div>
+              </template>
+
+              <template x-if="!changesState.error && !changesState.isLoading && !recentChanges.length">
+                <div class="text-body-secondary">No recent changes yet.</div>
+              </template>
+
+              <template x-if="recentChanges.length">
+                <div class="list-group list-group-flush">
+                  <template x-for="(change, index) in recentChanges" :key="change.timestamp || index">
+                    <div class="list-group-item px-0">
+                      <div class="d-flex flex-wrap justify-content-between align-items-center gap-2">
+                        <div class="fw-semibold" x-text="changeHeadline(change)"></div>
+                        <div class="small text-body-secondary" x-text="formatChangeTimestamp(change.timestamp)"></div>
+                      </div>
+                      <div class="small text-body-secondary mt-1" x-text="changeStateLine(change)"></div>
+                    </div>
+                  </template>
+                </div>
+              </template>
+            </div>
+          </div>
+        </div>
+      </div>
     </section>
   `;
 }
@@ -87,10 +138,202 @@ export function renderDashboardPage() {
 export function dashboardPageData(store) {
   return {
     showKitchenPicker: false,
+    changesState: createAsyncState(),
+    recentChanges: [],
+    locationLabelByUuid: {},
+    itemByUuid: {},
+    async init() {
+      if (!store.isConnected) {
+        return;
+      }
+
+      await this.refreshChanges();
+    },
+    async refreshChanges() {
+      await runAsyncState(this.changesState, async () => {
+        const payload = await listKitchenChanges(store, { limit: 10 });
+        this.recentChanges = payload.changes;
+        await this.loadContextForChanges(payload.changes);
+      }).catch(() => {});
+    },
+    async loadContextForChanges(changes) {
+      const stockItemUuids = Array.from(new Set(
+        changes
+          .map((change) => change?.stock?.item_uuid_b64)
+          .filter(Boolean),
+      ));
+      const missingItemUuids = stockItemUuids.filter((uuid) => !this.itemByUuid[uuid]);
+
+      if (missingItemUuids.length) {
+        const results = await Promise.allSettled(
+          missingItemUuids.map(async (uuid) => {
+            try {
+              return await getStockEntry(store, uuid);
+            } catch (error) {
+              const status = error?.status || error?.cause?.status;
+              if (status !== 404) {
+                throw error;
+              }
+
+              return getStockEntry(store, uuid, { allowInactive: true });
+            }
+          }),
+        );
+
+        results.forEach((result) => {
+          if (result.status !== 'fulfilled' || !result.value?.uuid_b64) {
+            return;
+          }
+
+          this.itemByUuid[result.value.uuid_b64] = result.value;
+        });
+      }
+
+      if (Object.keys(this.locationLabelByUuid).length) {
+        return;
+      }
+
+      try {
+        const { flat } = await fetchLocations(store);
+        this.locationLabelByUuid = Object.fromEntries(
+          flat
+            .filter((location) => location.uuid_b64)
+            .map((location) => [location.uuid_b64, location.pathLabel || location.name]),
+        );
+      } catch {
+        this.locationLabelByUuid = {};
+      }
+    },
     setKitchen(kitchen) {
       store.setActiveKitchen(kitchen);
       this.showKitchenPicker = false;
       store.addAlert({ type: 'success', message: `Working in ${kitchen.name}.` });
+      this.locationLabelByUuid = {};
+      this.itemByUuid = {};
+      this.refreshChanges();
+    },
+    resolveItemForChange(change) {
+      if (change?.item?.uuid_b64) {
+        return change.item;
+      }
+
+      const stockItemUuid = change?.stock?.item_uuid_b64;
+      if (!stockItemUuid) {
+        return null;
+      }
+
+      return this.itemByUuid[stockItemUuid] || null;
+    },
+    humanStockType(value) {
+      if (!value) {
+        return null;
+      }
+
+      return value.charAt(0).toUpperCase() + value.slice(1);
+    },
+    formatQuantity(quantity, uomSymbol) {
+      if (quantity === null || quantity === undefined || quantity === '') {
+        return null;
+      }
+
+      return `${quantity}${uomSymbol ? ` ${uomSymbol}` : ''}`;
+    },
+    formatLevel(level) {
+      if (!level) {
+        return null;
+      }
+
+      return level.charAt(0).toUpperCase() + level.slice(1);
+    },
+    formatShortDate(value) {
+      if (!value) {
+        return null;
+      }
+
+      const date = new Date(value);
+      if (Number.isNaN(date.getTime())) {
+        return String(value);
+      }
+
+      return date.toLocaleDateString();
+    },
+    resolveLocationLabel(change, item) {
+      const locationUuid =
+        change?.stock?.location_uuid_b64 ||
+        item?.location_initial_uuid_b64 ||
+        null;
+      if (!locationUuid) {
+        return null;
+      }
+
+      return this.locationLabelByUuid[locationUuid] || locationUuid;
+    },
+    changeHeadline(change) {
+      const item = this.resolveItemForChange(change);
+      const itemName = item?.name || 'Unknown item';
+      const type = String(change?.type || 'change');
+      const action = String(change?.action || 'updated');
+
+      if (action === 'upsert' && type === 'item') {
+        return `Item saved: ${itemName}`;
+      }
+
+      if (action === 'upsert' && type === 'stock') {
+        return `Stock saved: ${itemName}`;
+      }
+
+      return `${type} ${action}: ${itemName}`;
+    },
+    changeStateLine(change) {
+      const item = this.resolveItemForChange(change);
+      const stock = change?.stock || {};
+      const state = [];
+
+      const stockType = this.humanStockType(item?.stock_type);
+      if (stockType) {
+        state.push(`Type: ${stockType}`);
+      }
+
+      const quantity = this.formatQuantity(
+        stock.quantity ?? item?.quantity,
+        stock.uom_symbol || item?.uom_symbol,
+      );
+      if (quantity) {
+        state.push(`Quantity: ${quantity}`);
+      }
+
+      const level = this.formatLevel(stock.level || item?.level);
+      if (level) {
+        state.push(`Level: ${level}`);
+      }
+
+      const expiry = this.formatShortDate(item?.expire_date);
+      if (expiry) {
+        state.push(`Expires: ${expiry}`);
+      }
+
+      const location = this.resolveLocationLabel(change, item);
+      if (location) {
+        state.push(`Location: ${location}`);
+      }
+
+      if (!state.length) {
+        return 'Saved (created or updated).';
+      }
+
+      return state.join(' • ');
+    },
+    formatChangeTimestamp(value) {
+      if (!value) {
+        return 'Unknown time';
+      }
+
+      const date = new Date(value);
+      if (Number.isNaN(date.getTime())) {
+        return String(value);
+      }
+
+      return date.toLocaleString();
     },
   };
 }

src/features/labels/identifier-lookup-mapper.js

@@ -0,0 +1,156 @@
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+function normalizedText(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function nonEmptyText(value) {
+  const text = normalizedText(value);
+  return text ? text : null;
+}
+
+function normalizedNumberText(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return String(value);
+  }
+
+  if (typeof value === 'string') {
+    const text = value.trim();
+    if (!text) {
+      return null;
+    }
+    const parsed = Number(text);
+    if (Number.isFinite(parsed)) {
+      return String(parsed);
+    }
+  }
+
+  return '';
+}
+
+function parseIsoDate(isoDate) {
+  if (!ISO_DATE_PATTERN.test(String(isoDate || ''))) {
+    return null;
+  }
+
+  const [year, month, day] = String(isoDate).split('-').map(Number);
+  const parsed = new Date(year, month - 1, day);
+
+  if (
+    parsed.getFullYear() !== year
+    || parsed.getMonth() !== month - 1
+    || parsed.getDate() !== day
+  ) {
+    return null;
+  }
+
+  return parsed;
+}
+
+function addDaysToIsoDate(isoDate, days) {
+  const parsed = parseIsoDate(isoDate);
+  if (!parsed) {
+    return '';
+  }
+
+  parsed.setDate(parsed.getDate() + days);
+  const year = parsed.getFullYear();
+  const month = String(parsed.getMonth() + 1).padStart(2, '0');
+  const day = String(parsed.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function diffIsoDays(fromIsoDate, toIsoDate) {
+  const fromDate = parseIsoDate(fromIsoDate);
+  const toDate = parseIsoDate(toIsoDate);
+  if (!fromDate || !toDate) {
+    return null;
+  }
+
+  const millisecondsPerDay = 24 * 60 * 60 * 1000;
+  const diff = Math.round((toDate - fromDate) / millisecondsPerDay);
+  return diff >= 0 ? diff : null;
+}
+
+function nonNegativeDays(value) {
+  if (value == null) {
+    return null;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return null;
+  }
+
+  return Math.round(parsed);
+}
+
+export function deriveLookupExpirationDays(lookupItem) {
+  const explicitDays = nonNegativeDays(lookupItem?.expiration_days);
+  if (explicitDays !== null) {
+    return explicitDays;
+  }
+
+  return diffIsoDays(lookupItem?.date, lookupItem?.expire_date);
+}
+
+export function mapLookupItemToForm({
+  form,
+  lookupItem,
+  locations = [],
+}) {
+  const nextForm = { ...form };
+  let nextLocationSearch = null;
+  let didUpdate = false;
+
+  const setField = (targetField, value) => {
+    if (nextForm[targetField] === value) {
+      return;
+    }
+
+    nextForm[targetField] = value;
+    didUpdate = true;
+  };
+
+  const textValue = (sourceField) => normalizedText(lookupItem?.[sourceField]);
+  const numberValue = (sourceField) => normalizedNumberText(lookupItem?.[sourceField]);
+
+  setField('identifierCode', textValue('identifier_code'));
+  setField('name', textValue('name'));
+  setField('description', textValue('description'));
+  setField('level', textValue('level'));
+  setField('quantity', numberValue('quantity_initial'));
+  setField('uom', textValue('uom_symbol'));
+  setField('energy', numberValue('calories'));
+  setField('energyUnit', textValue('calories_unit'));
+  setField('externalSource', textValue('external_source'));
+  setField('externalId', textValue('external_id'));
+
+  setField('search', nextForm.name);
+
+  const expirationDays = deriveLookupExpirationDays(lookupItem);
+  if (expirationDays !== null) {
+    setField('expireDays', String(expirationDays));
+    setField('expirationDate', addDaysToIsoDate(nextForm.productionDate, expirationDays));
+  } else {
+    setField('expireDays', '');
+    setField('expirationDate', '');
+  }
+
+  const locationUuid = nonEmptyText(lookupItem?.location_initial_uuid_b64);
+  if (locationUuid) {
+    const matchingLocation = locations.find((entry) => entry.uuid_b64 === locationUuid);
+    if (matchingLocation) {
+      setField('locationId', String(matchingLocation.id));
+      if (nextLocationSearch !== matchingLocation.name) {
+        nextLocationSearch = matchingLocation.name;
+      }
+    }
+  }
+
+  return {
+    form: nextForm,
+    locationSearch: nextLocationSearch,
+    didUpdate,
+  };
+}

src/features/labels/label-create-page.js

@@ -1,9 +1,30 @@
-import { createStockEntry, searchItemDefinitions } from '../../api/stock.js';
+import {
+  applyItemUpsert,
+  getStockEntry,
+  lookupItemByIdentifier,
+  previewItemUpsert,
+  searchItemDefinitions,
+} from '../../api/stock.js';
+import { mapLookupItemToForm } from './identifier-lookup-mapper.js';
 import { fetchLocations } from '../../api/locations.js';
-import { previewLabel } from '../../api/labels.js';
+import {
+  formatPrintErrorMessage,
+  previewLabel,
+  printItemLabel,
+} from '../../api/labels.js';
 import { STORAGE_KEYS } from '../../app/config.js';
 import { debounce, normalizeValidationError } from '../shared/form-utils.js';
 import { loadStoredValue, saveStoredValue } from '../shared/storage.js';
+import { renderScannerModal } from '../shared/scanner-modal.js';
+import {
+  canUseCameraScanner,
+  createScannerReader,
+  normalizeIdentifierCode,
+  parseKitchenScanPayload,
+  normalizeScannerError,
+  startCameraScanner,
+  stopCameraScanner,
+} from '../shared/scanner.js';
 import { createAsyncState, runAsyncState } from '../shared/ui-state.js';
 
 const STOCK_TYPE_OPTIONS = [
@@ -23,8 +44,42 @@ const STOCK_LEVEL_OPTIONS = [
 
 const QUANTITY_UNIT_OPTIONS = ['g', 'ml', 'pc'];
 const EXPIRATION_DAY_OPTIONS = ['3', '5', '8', '10', '15', '20', '25', '30', '45', '60', '90', '120', '150', '180'];
+const LABEL_DRAFT_STALE_MS = 30 * 60 * 1000;
+const SCANNER_ACTION_OPTIONS = [
+  {
+    key: 'lookup',
+    label: 'Lookup',
+    description: 'Lookup identifier data and prefill the label form.',
+  },
+  {
+    key: 'create',
+    label: 'Create',
+    description: 'Lookup data and create label immediately when required fields are complete.',
+  },
+  {
+    key: 'create_print',
+    label: 'Create & print',
+    description: 'Lookup data, create label, and print when required fields are complete.',
+  },
+];
 
 export function renderLabelCreatePage() {
+  const scannerOptionsMarkup = `
+            <div class="scan-label-mode-list mb-3">
+              <template x-for="action in scannerActionOptions" :key="'label-scanner-' + action.key">
+                <button
+                  class="btn btn-sm scan-label-mode-btn"
+                  type="button"
+                  :class="scannerAction === action.key ? 'scan-label-mode-btn-active' : 'btn-outline-secondary'"
+                  @click="scannerAction = action.key"
+                >
+                  <span x-text="action.label"></span>
+                </button>
+              </template>
+            </div>
+            <div class="small text-body-secondary mb-3" x-text="activeScannerActionDescription()"></div>
+  `;
+
   return `
     <section class="container-xxl py-4 py-lg-5" x-data="labelCreatePage()" x-init="init()">
       <div class="d-flex flex-column flex-lg-row justify-content-between gap-3 align-items-lg-end mb-4">
@@ -46,7 +101,8 @@ export function renderLabelCreatePage() {
             <div class="card border-0 shadow-sm">
             <div class="card-body p-4">
               <form class="vstack gap-3" @submit.prevent="create()" autocomplete="off" x-ref="labelForm">
-                <div class="position-relative search-field-with-clear">
+                <div class="row g-3 align-items-start">
+                  <div class="col-12 col-md-6 position-relative search-field-with-clear">
                     <label class="form-label">Search item definitions</label>
                     <input class="form-control pe-5" type="text" x-model="form.search" @input="onSearchInput()" placeholder="Search by item name" autocomplete="off" />
                     <button
@@ -69,6 +125,52 @@ export function renderLabelCreatePage() {
                       </div>
                     </template>
                   </div>
+                  <div class="col-12 col-md-6">
+                    <label class="form-label">Identifier code</label>
+                    <div class="input-group">
+                      <input
+                        class="form-control"
+                        type="text"
+                        x-model="form.identifierCode"
+                        @input="lookupState.error = ''"
+                        inputmode="numeric"
+                        autocomplete="off"
+                        placeholder="EAN / UPC / GTIN"
+                      />
+                      <button
+                        class="btn btn-outline-primary"
+                        type="button"
+                        @click="lookupIdentifierDetails()"
+                        :disabled="lookupState.isLoading || !hasLookupIdentifierCode()"
+                      >
+                        <span x-show="!lookupState.isLoading">Lookup</span>
+                        <span x-show="lookupState.isLoading">Looking up...</span>
+                      </button>
+                      <button
+                        class="btn btn-outline-secondary"
+                        type="button"
+                        @click="openScanner()"
+                        x-show="scannerState.hasCamera"
+                      >
+                        Camera
+                      </button>
+                      <button
+                        class="btn btn-outline-secondary"
+                        type="button"
+                        x-show="form.identifierCode"
+                        @click="form.identifierCode = ''"
+                      >
+                        Clear
+                      </button>
+                    </div>
+                    <div class="form-text">
+                      Optional. Scan with camera, use a hardware scanner, or enter manually.
+                    </div>
+                    <template x-if="lookupState.error">
+                      <div class="small text-danger mt-1" x-text="lookupState.error"></div>
+                    </template>
+                  </div>
+                </div>
 
                 <div class="row g-3">
                   <div class="col-12 col-md-8 position-relative text-field-with-clear">
@@ -400,18 +502,48 @@ export function renderLabelCreatePage() {
                   <div class="alert alert-success mb-0" x-text="successMessage"></div>
                 </template>
 
-                <div class="d-flex flex-wrap justify-content-between align-items-center gap-2">
+                <template x-if="upsertPreview?.mode === 'preview' && !upsertPreview.error">
-                  <div class="d-flex flex-wrap gap-2">
+                  <div class="alert alert-info mb-0 py-2" x-text="upsertPreviewSummary()"></div>
-                    <button class="btn btn-outline-primary" type="button" @click="preview()" :disabled="previewState.isLoading">
+                </template>
+
+                <template x-if="upsertPreview?.error">
+                  <div class="alert alert-warning mb-0 py-2" x-text="upsertPreview.error"></div>
+                </template>
+
+                <template x-if="printIssue">
+                  <div class="alert alert-warning mb-0 py-2 d-flex flex-wrap align-items-center justify-content-between gap-2">
+                    <span x-text="printIssue"></span>
+                    <button
+                      class="btn btn-sm btn-outline-secondary"
+                      type="button"
+                      x-show="canRetryLastLabelPrint()"
+                      @click="retryLastLabelPrint()"
+                      :disabled="printState.isLoading"
+                    >
+                      <span x-show="!printState.isLoading">Reprint label</span>
+                      <span x-show="printState.isLoading">Printing...</span>
+                    </button>
+                  </div>
+                </template>
+
+                <div class="d-flex flex-wrap justify-content-between align-items-center gap-2 label-actions-row">
+                  <div class="d-flex flex-wrap gap-2 label-actions-primary">
+                    <button class="btn btn-outline-primary label-action-btn" type="button" @click="preview()" :disabled="previewState.isLoading">
                       <span x-show="!previewState.isLoading">Preview label</span>
                       <span x-show="previewState.isLoading">Rendering preview...</span>
                     </button>
-                    <button class="btn btn-primary" type="submit" :disabled="createState.isLoading">
+                    <div class="input-group input-group-label-submit">
-                      <span x-show="!createState.isLoading">Create stock entry</span>
+                      <span class="input-group-text">
+                        <input class="form-check-input mt-0 me-2" type="checkbox" x-model="printLabelOnSave" aria-label="Print label on save" />
+                        Print
+                      </span>
+                      <button class="btn btn-primary label-action-btn" type="submit" :disabled="createState.isLoading">
+                        <span x-show="!createState.isLoading">Save stock entry</span>
                         <span x-show="createState.isLoading">Saving...</span>
                       </button>
                     </div>
-                  <button class="btn btn-outline-secondary" type="button" @click="reset()">Clear form</button>
+                  </div>
+                  <button class="btn btn-outline-secondary label-action-btn" type="button" @click="reset()">Clear form</button>
                 </div>
                 <div class="small text-body-secondary">
                   <span class="text-danger">*</span> Required field
@@ -444,6 +576,17 @@ export function renderLabelCreatePage() {
           </div>
         </div>
       </div>
+
+      ${renderScannerModal({
+        title: 'Scan barcode',
+        subtitle: 'Point your camera at a product barcode or kitchen DataMatrix label.',
+        optionsMarkup: scannerOptionsMarkup,
+        manualCodeModel: 'scannerManualCode',
+        manualSubmitAction: 'processScannerManualCode()',
+        manualPlaceholder: 'Scan with hardware reader or paste code',
+        manualHelp: 'Use this with keyboard-style barcode scanners or for manual paste.',
+        manualDisabledExpression: 'lookupState.isLoading || createState.isLoading || scannerState.isLoading || scannerState.isProcessing',
+      })}
     </section>
   `;
 }
@@ -478,6 +621,10 @@ function diffDays(fromIsoDate, toIsoDate) {
 function createDefaultForm() {
   return {
     itemId: '',
+    itemUuidB64: '',
+    identifierCode: '',
+    externalSource: '',
+    externalId: '',
     search: '',
     name: '',
     description: '',
@@ -494,9 +641,7 @@ function createDefaultForm() {
   };
 }
 
-function loadLabelDraft() {
+function normalizeLabelDraft(draft) {
-  const draft = loadStoredValue(STORAGE_KEYS.labelDraft, createDefaultForm());
-
   return {
     ...createDefaultForm(),
     ...draft,
@@ -505,6 +650,10 @@ function loadLabelDraft() {
         ? ''
         : draft.quantity,
     itemId: '',
+    itemUuidB64: '',
+    identifierCode: '',
+    externalSource: '',
+    externalId: '',
     search: '',
   };
 }
@@ -513,14 +662,58 @@ function buildDraftPayload(form) {
   return {
     ...form,
     itemId: '',
+    itemUuidB64: '',
+    identifierCode: '',
+    externalSource: '',
+    externalId: '',
     search: '',
   };
 }
 
+function buildLabelDraftEnvelope(form) {
+  return {
+    form: buildDraftPayload(form),
+    savedAt: Date.now(),
+  };
+}
+
+function saveLabelDraft(form) {
+  saveStoredValue(STORAGE_KEYS.labelDraft, buildLabelDraftEnvelope(form));
+}
+
+function loadLabelDraft() {
+  const storedDraft = loadStoredValue(STORAGE_KEYS.labelDraft, null);
+
+  if (!storedDraft || typeof storedDraft !== 'object' || Array.isArray(storedDraft)) {
+    return createDefaultForm();
+  }
+
+  const hasEnvelope =
+    storedDraft.form
+    && typeof storedDraft.form === 'object'
+    && !Array.isArray(storedDraft.form);
+
+  if (!hasEnvelope) {
+    return normalizeLabelDraft(storedDraft);
+  }
+
+  const savedAt = Number(storedDraft.savedAt || 0);
+  if (!savedAt || Date.now() - savedAt >= LABEL_DRAFT_STALE_MS) {
+    return createDefaultForm();
+  }
+
+  return normalizeLabelDraft(storedDraft.form);
+}
+
 export function labelCreatePageData(store) {
   return {
     previewState: createAsyncState(),
     createState: createAsyncState(),
+    lookupState: createAsyncState(),
+    printState: createAsyncState(),
+    scannerActionOptions: SCANNER_ACTION_OPTIONS,
+    scannerAction: 'lookup',
+    scannerManualCode: '',
     stockTypeOptions: STOCK_TYPE_OPTIONS,
     stockLevelOptions: STOCK_LEVEL_OPTIONS,
     quantityUnitOptions: QUANTITY_UNIT_OPTIONS,
@@ -536,10 +729,26 @@ export function labelCreatePageData(store) {
     successMessage: '',
     submitError: '',
     fieldErrors: {},
+    upsertPreview: null,
+    printLabelOnSave: true,
+    printIssue: '',
+    lastCreatedLabelUuidB64: '',
+    lastCreatedLabelName: '',
+    scannerReader: null,
+    scannerControls: null,
+    scannerState: {
+      isOpen: false,
+      isLoading: false,
+      isProcessing: false,
+      hasCamera: false,
+      error: '',
+      lastDetectedCode: '',
+    },
     form: {
       ...loadLabelDraft(),
     },
     async init() {
+      this.scannerState.hasCamera = this.canUseCameraScanner();
       if (!store.isConnected) {
         return;
       }
@@ -573,6 +782,468 @@ export function labelCreatePageData(store) {
         this.suggestions = await searchItemDefinitions(store, this.form.search.trim());
       }, 250);
     },
+    destroy() {
+      this.stopScanner();
+    },
+    canUseCameraScanner() {
+      return canUseCameraScanner();
+    },
+    normalizeIdentifierCode(value) {
+      return normalizeIdentifierCode(value);
+    },
+    hasLookupIdentifierCode() {
+      return Boolean(this.normalizeIdentifierCode(this.form.identifierCode));
+    },
+    lookupStatusMessage(status, identifierCode) {
+      const normalizedCode = this.normalizeIdentifierCode(identifierCode);
+
+      if (!normalizedCode || status === 'missing_identifier') {
+        return 'Provide an identifier code before lookup.';
+      }
+
+      if (status === 'not_found') {
+        return `No lookup result found for code ${normalizedCode}.`;
+      }
+
+      if (status === 'lookup_failed') {
+        return 'Lookup failed on the server. You can still fill the form manually.';
+      }
+
+      if (status === 'rate_limited') {
+        return 'Lookup is temporarily rate-limited. Try again shortly.';
+      }
+
+      return 'Lookup response could not be applied to this form.';
+    },
+    lookupStatusMessageWithDetails(response, identifierCode) {
+      const base = this.lookupStatusMessage(response?.status, identifierCode);
+      if (response?.status !== 'rate_limited') {
+        return base;
+      }
+
+      if (!Number.isInteger(response?.retryAfterSeconds) || response.retryAfterSeconds <= 0) {
+        return base;
+      }
+
+      return `${base} Retry in ${response.retryAfterSeconds}s.`;
+    },
+    lookupSourceLabel(source) {
+      if (!source) {
+        return '';
+      }
+
+      const labels = {
+        item: 'existing item',
+        cache: 'cache',
+        openfoodfacts: 'OpenFoodFacts',
+      };
+
+      return labels[source] || source;
+    },
+    lookupSuccessMessage(response) {
+      const parts = ['Lookup applied product details'];
+      const metadata = [];
+
+      if (response?.source) {
+        metadata.push(`source: ${this.lookupSourceLabel(response.source)}`);
+      }
+      if (response?.cacheHit) {
+        metadata.push('cache hit');
+      }
+      if (response?.staleCache) {
+        metadata.push('stale cache');
+      }
+      if (response?.payloadFetchedAt) {
+        const fetchedAt = new Date(response.payloadFetchedAt);
+        metadata.push(
+          `fetched: ${
+            Number.isNaN(fetchedAt.getTime())
+              ? response.payloadFetchedAt
+              : fetchedAt.toLocaleString()
+          }`,
+        );
+      }
+
+      if (metadata.length) {
+        parts.push(`(${metadata.join(', ')})`);
+      }
+
+      return `${parts.join(' ')}.`;
+    },
+    normalizeScannerError(error) {
+      return normalizeScannerError(error);
+    },
+    activeScannerActionDescription() {
+      return this.scannerActionOptions.find((action) => action.key === this.scannerAction)?.description || '';
+    },
+    async openScanner() {
+      this.scannerState.error = '';
+      this.scannerState.lastDetectedCode = '';
+      this.scannerState.isProcessing = false;
+      this.scannerManualCode = this.form.identifierCode || '';
+      this.scannerState.isOpen = true;
+      await this.$nextTick();
+      await this.startScanner();
+    },
+    async startScanner() {
+      this.scannerState.error = '';
+      this.scannerState.lastDetectedCode = '';
+
+      if (!this.canUseCameraScanner()) {
+        this.scannerState.hasCamera = false;
+        this.scannerState.error = 'Camera scanning is not supported in this browser. Enter the identifier code manually.';
+        return;
+      }
+
+      const videoElement = this.$refs.scannerVideo;
+      if (!videoElement) {
+        this.scannerState.error = 'Scanner video element is unavailable. Close and reopen scanner.';
+        return;
+      }
+
+      this.stopScanner();
+      this.scannerState.isLoading = true;
+
+      try {
+        if (!this.scannerReader) {
+          this.scannerReader = createScannerReader();
+        }
+
+        const session = await startCameraScanner({
+          reader: this.scannerReader,
+          videoElement,
+          onDetected: (code) => this.onBarcodeDetected(code),
+        });
+        this.scannerReader = session.reader;
+        this.scannerControls = session.controls;
+      } catch (error) {
+        this.scannerState.error = this.normalizeScannerError(error);
+      } finally {
+        this.scannerState.isLoading = false;
+      }
+    },
+    stopScanner() {
+      stopCameraScanner({
+        reader: this.scannerReader,
+        controls: this.scannerControls,
+        videoElement: this.$refs.scannerVideo,
+      });
+      this.scannerControls = null;
+    },
+    closeScanner() {
+      this.stopScanner();
+      this.scannerState.isOpen = false;
+      this.scannerState.isLoading = false;
+      this.scannerState.error = '';
+    },
+    async resolveIdentifierCodeFromScan(rawCode) {
+      const parsed = parseKitchenScanPayload(rawCode);
+      if (parsed.type === 'empty' || parsed.type === 'unknown') {
+        return {
+          identifierCode: '',
+          message: 'Scanned code could not be interpreted.',
+          level: 'warning',
+        };
+      }
+
+      if (parsed.type === 'item') {
+        const item = await getStockEntry(store, parsed.uuidB64, { allowInactive: true });
+        const itemIdentifierCode = this.normalizeIdentifierCode(item?.identifier_code);
+        if (!itemIdentifierCode) {
+          return {
+            identifierCode: '',
+            message: `${item?.name || 'Scanned item'} has no identifier code. Add one first, then scan again.`,
+            level: 'info',
+          };
+        }
+
+        return {
+          identifierCode: itemIdentifierCode,
+          message: `Resolved identifier ${itemIdentifierCode} from ${item?.name || 'scanned item'}.`,
+          level: 'success',
+        };
+      }
+
+      return {
+        identifierCode: this.normalizeIdentifierCode(parsed.identifierCode),
+        message: '',
+        level: 'success',
+      };
+    },
+    applyLookupResult(response, identifierCode, { announceSuccess = true } = {}) {
+      if (response.status !== 'ok') {
+        const message = this.lookupStatusMessageWithDetails(response, identifierCode);
+        this.lookupState.error = message;
+        store.addAlert({
+          type: response.status === 'not_found' ? 'info' : 'warning',
+          message,
+        });
+        return false;
+      }
+
+      if (!response.item || typeof response.item !== 'object') {
+        const message = 'Lookup returned no item payload to apply.';
+        this.lookupState.error = message;
+        store.addAlert({
+          type: 'warning',
+          message,
+        });
+        return false;
+      }
+
+      const mapped = mapLookupItemToForm({
+        form: this.form,
+        lookupItem: response.item,
+        locations: this.locations,
+      });
+
+      if (!mapped.didUpdate) {
+        const message = 'Lookup finished, but no compatible fields were returned.';
+        this.lookupState.error = message;
+        store.addAlert({
+          type: 'info',
+          message,
+        });
+        return false;
+      }
+
+      this.form = {
+        ...mapped.form,
+        itemId: '',
+        itemUuidB64: '',
+      };
+      if (mapped.locationSearch !== null) {
+        this.locationSearch = mapped.locationSearch;
+      }
+      this.syncStockTypeState(this.form.stockType);
+      this.syncStockTypeSelect();
+      this.syncStockLevelSelect();
+      this.syncLocationValidity();
+      this.upsertPreview = null;
+      this.previewState.error = '';
+      this.submitError = '';
+      if (this.previewUrl.startsWith('blob:')) {
+        URL.revokeObjectURL(this.previewUrl);
+      }
+      this.previewUrl = '';
+      this.suggestions = [];
+      this.persistDraft();
+
+      if (announceSuccess) {
+        store.addAlert({
+          type: 'success',
+          message: this.lookupSuccessMessage(response),
+        });
+      }
+
+      return true;
+    },
+    async lookupIdentifierDetailsByCode(identifierCode, { announceSuccess = true } = {}) {
+      const normalizedCode = this.normalizeIdentifierCode(identifierCode);
+      this.form.identifierCode = normalizedCode;
+      this.lookupState.error = '';
+
+      if (!normalizedCode) {
+        this.lookupState.error = 'Provide an identifier code before lookup.';
+        return false;
+      }
+
+      const response = await lookupItemByIdentifier(store, normalizedCode);
+      return this.applyLookupResult(response, normalizedCode, { announceSuccess });
+    },
+    canAutoCreateFromForm() {
+      if (!String(this.form.name || '').trim()) {
+        return false;
+      }
+      if (!this.form.productionDate) {
+        return false;
+      }
+      if (!this.selectedLocation?.uuid_b64) {
+        return false;
+      }
+      if (this.form.stockType === 'measured') {
+        const quantity = Number(this.form.quantity);
+        if (Number.isNaN(quantity) || quantity <= 0) {
+          return false;
+        }
+      }
+      return true;
+    },
+    async createFromScannerAction({ shouldPrint = false } = {}) {
+      const entry = await applyItemUpsert(store, this.buildUpsertPayload());
+      const entryName = entry.item?.name || this.form.name;
+      const operationVerb = entry.operation === 'update' ? 'updated' : 'created';
+      const createdUuidB64 = entry.item?.uuid_b64 || null;
+      this.lastCreatedLabelUuidB64 = createdUuidB64 || '';
+      this.lastCreatedLabelName = entryName;
+
+      this.successMessage = `${entryName} was ${operationVerb} successfully.`;
+      this.upsertPreview = entry;
+      saveLabelDraft(this.form);
+
+      if (shouldPrint) {
+        if (!createdUuidB64) {
+          const message = `${entryName} was ${operationVerb}, but label printing is unavailable for this entry.`;
+          this.printIssue = message;
+          store.addAlert({
+            type: 'warning',
+            message,
+          });
+          return true;
+        }
+
+        try {
+          await printItemLabel(store, createdUuidB64);
+          const message = `${entryName} was ${operationVerb} and printed. Ready for next scan.`;
+          store.addAlert({
+            type: 'success',
+            message,
+          });
+          void this.openScanner().catch(() => {});
+        } catch (printError) {
+          const parsedPrintMessage = formatPrintErrorMessage(printError);
+          this.printIssue = `${entryName} was ${operationVerb}, but printing failed: ${parsedPrintMessage}`;
+          store.addAlert({
+            type: 'warning',
+            message: this.printIssue,
+          });
+        }
+        return true;
+      }
+
+      const message = `${entryName} was ${operationVerb}. Ready for next scan.`;
+      store.addAlert({
+        type: 'success',
+        message,
+      });
+      void this.openScanner().catch(() => {});
+      return true;
+    },
+    canRetryLastLabelPrint() {
+      return Boolean(this.lastCreatedLabelUuidB64);
+    },
+    async retryLastLabelPrint() {
+      if (!this.canRetryLastLabelPrint()) {
+        return;
+      }
+
+      await runAsyncState(this.printState, async () => {
+        await printItemLabel(store, this.lastCreatedLabelUuidB64);
+        this.printIssue = '';
+        store.addAlert({
+          type: 'success',
+          message: `${this.lastCreatedLabelName || 'Label'} sent to printer.`,
+        });
+      }).catch((printError) => {
+        const parsedPrintMessage = formatPrintErrorMessage(printError);
+        const itemName = this.lastCreatedLabelName || 'Label';
+        this.printIssue = `Could not print ${itemName}: ${parsedPrintMessage}`;
+      });
+    },
+    async runScannerActionForCode(rawCode) {
+      try {
+        const resolved = await this.resolveIdentifierCodeFromScan(rawCode);
+        if (!resolved.identifierCode) {
+          store.addAlert({
+            type: resolved.level || 'warning',
+            message: resolved.message || 'Scanned code could not be used for lookup.',
+          });
+          return;
+        }
+
+        this.form.identifierCode = resolved.identifierCode;
+        if (resolved.message) {
+          store.addAlert({
+            type: resolved.level || 'info',
+            message: resolved.message,
+          });
+        }
+
+        const didLookupApply = await this.lookupIdentifierDetailsByCode(resolved.identifierCode, {
+          announceSuccess: this.scannerAction === 'lookup',
+        });
+        if (!didLookupApply) {
+          return;
+        }
+
+        if (this.scannerAction === 'lookup') {
+          return;
+        }
+
+        if (!this.canAutoCreateFromForm()) {
+          const message = 'Lookup filled part of the form. Complete required fields, then save or print.';
+          this.lookupState.error = message;
+          store.addAlert({
+            type: 'info',
+            message,
+          });
+          return;
+        }
+
+        this.submitError = '';
+        this.fieldErrors = {};
+        this.printIssue = '';
+        await runAsyncState(this.createState, async () => {
+          await this.createFromScannerAction({
+            shouldPrint: this.scannerAction === 'create_print',
+          });
+        }).catch((error) => {
+          this.fieldErrors = normalizeValidationError(error);
+          this.submitError = error.message || 'Could not create from scanned lookup.';
+        });
+      } catch (error) {
+        store.addAlert({
+          type: 'warning',
+          message: `Scanner action failed: ${error.message || 'Unknown error.'}`,
+        });
+      }
+    },
+    processScannerManualCode() {
+      const code = this.normalizeIdentifierCode(this.scannerManualCode);
+      if (!code) {
+        this.scannerState.error = 'Scan or enter a code first.';
+        return;
+      }
+      this.scannerState.lastDetectedCode = code;
+      this.scannerState.isProcessing = true;
+      this.closeScanner();
+      this.runScannerActionForCode(code).finally(() => {
+        this.scannerState.isProcessing = false;
+      });
+    },
+    onBarcodeDetected(rawCode) {
+      const code = this.normalizeIdentifierCode(rawCode);
+      if (!code || !this.scannerState.isOpen || this.scannerState.isProcessing) {
+        return;
+      }
+
+      this.scannerState.lastDetectedCode = code;
+      this.scannerManualCode = code;
+      this.scannerState.isProcessing = true;
+      this.closeScanner();
+      this.runScannerActionForCode(rawCode).finally(() => {
+        this.scannerState.isProcessing = false;
+      });
+    },
+    async lookupIdentifierDetails() {
+      const identifierCode = this.normalizeIdentifierCode(this.form.identifierCode);
+      this.form.identifierCode = identifierCode;
+      this.lookupState.error = '';
+
+      if (!identifierCode) {
+        this.lookupState.error = 'Provide an identifier code before lookup.';
+        return;
+      }
+
+      await runAsyncState(this.lookupState, async () => {
+        await this.lookupIdentifierDetailsByCode(identifierCode, { announceSuccess: true });
+      }).catch((error) => {
+        store.addAlert({
+          type: 'warning',
+          message: `Could not complete lookup: ${error.message || 'Unknown lookup error.'}`,
+        });
+      });
+    },
     async loadLocations() {
       if (!store.isConnected) {
         return;
@@ -590,6 +1261,14 @@ export function labelCreatePageData(store) {
       }
     },
     onSearchInput() {
+      this.upsertPreview = null;
+      if (this.form.itemUuidB64 || this.form.itemId) {
+        this.form.itemId = '';
+        this.form.itemUuidB64 = '';
+        this.form.identifierCode = '';
+        this.form.externalSource = '';
+        this.form.externalId = '';
+      }
       this.persistDraft();
       this.searchDebounced();
     },
@@ -603,6 +1282,10 @@ export function labelCreatePageData(store) {
             : null;
 
       this.form.itemId = item.id;
+      this.form.itemUuidB64 = item.uuid_b64 || '';
+      this.form.identifierCode = item.identifier_code || '';
+      this.form.externalSource = item.external_source || '';
+      this.form.externalId = item.external_id || '';
       this.form.search = item.name;
       this.form.name = item.name;
       this.form.description = item.description || this.form.description;
@@ -623,12 +1306,17 @@ export function labelCreatePageData(store) {
     },
     clearItemSearch() {
       this.form.itemId = '';
+      this.form.itemUuidB64 = '';
+      this.form.identifierCode = '';
+      this.form.externalSource = '';
+      this.form.externalId = '';
       this.form.search = '';
+      this.upsertPreview = null;
       this.suggestions = [];
       this.persistDraft();
     },
     persistDraft() {
-      saveStoredValue(STORAGE_KEYS.labelDraft, buildDraftPayload(this.form));
+      saveLabelDraft(this.form);
     },
     get filteredLocations() {
       const query = this.locationSearch.trim().toLowerCase();
@@ -908,6 +1596,8 @@ export function labelCreatePageData(store) {
             : null
           : Number(this.form.quantity);
 
+      const selectedLocationUuidB64 = this.selectedLocation?.uuid_b64 || null;
+
       return {
         item_id: this.form.itemId || null,
         name: this.form.name.trim(),
@@ -920,13 +1610,56 @@ export function labelCreatePageData(store) {
         level: this.form.stockType === 'measured' ? null : this.form.level || null,
         date: this.form.productionDate || null,
         expire_date: this.form.expirationDate || null,
-        location_initial: this.form.locationId || null,
+        location_initial: selectedLocationUuidB64,
         kitchen_id: store.activeKitchen?.id || null,
       };
     },
+    buildUpsertPayload() {
+      const basePayload = this.buildPayload();
+      const itemPayload = {
+        name: basePayload.name,
+        description: basePayload.description,
+        quantity_initial: basePayload.quantity_initial,
+        uom_symbol: basePayload.uom_symbol,
+        calories: basePayload.calories,
+        calories_unit: basePayload.calories_unit,
+        stock_type: basePayload.stock_type,
+        level: basePayload.level,
+        date: basePayload.date,
+        expire_date: basePayload.expire_date,
+        location_initial: basePayload.location_initial,
+      };
+
+      return {
+        uuid_b64: this.form.itemUuidB64 || null,
+        identifier_code: this.form.identifierCode || null,
+        external_source: this.form.externalSource || null,
+        external_id: this.form.externalId || null,
+        item: itemPayload,
+      };
+    },
+    upsertPreviewSummary() {
+      if (!this.upsertPreview || this.upsertPreview.error) {
+        return '';
+      }
+
+      if (this.upsertPreview.mode !== 'preview') {
+        return '';
+      }
+
+      if (this.upsertPreview.operation === 'update') {
+        const name = this.upsertPreview.matchedItem?.name || this.form.name;
+        const matchType = this.upsertPreview.matchType ? ` (matched by ${this.upsertPreview.matchType})` : '';
+        return `Submit will update: ${name}${matchType}.`;
+      }
+
+      return 'Submit will create a new stock item.';
+    },
     async preview() {
       this.submitError = '';
       this.fieldErrors = {};
+      this.upsertPreview = null;
+      this.printIssue = '';
 
       if (!this.validateBeforeSubmit()) {
         this.previewState.error = 'Please fill out the required fields before previewing the label.';
@@ -940,31 +1673,55 @@ export function labelCreatePageData(store) {
           URL.revokeObjectURL(this.previewUrl);
         }
         this.previewUrl = result.objectUrl;
+        try {
+          this.upsertPreview = await previewItemUpsert(store, this.buildUpsertPayload());
+        } catch (error) {
+          this.upsertPreview = {
+            error: error.message || 'Upsert preview failed.',
+          };
+        }
         this.persistDraft();
       });
     },
     async create() {
       this.submitError = '';
       this.fieldErrors = {};
+      this.printIssue = '';
 
       if (!this.validateBeforeSubmit()) {
-        this.submitError = 'Please fill out the required fields before creating the stock entry.';
+        this.submitError = 'Please fill out the required fields before saving the stock entry.';
         return;
       }
 
       await runAsyncState(this.createState, async () => {
         try {
-          const entry = await createStockEntry(store, this.buildPayload());
+          const entry = await applyItemUpsert(store, this.buildUpsertPayload());
-          if (this.previewUrl && this.previewUrl.startsWith('blob:')) {
+          const entryName = entry.item?.name || this.form.name;
-            URL.revokeObjectURL(this.previewUrl);
+          const operationVerb = entry.operation === 'update' ? 'updated' : 'created';
+          const createdUuidB64 = entry.item?.uuid_b64 || null;
+          this.lastCreatedLabelUuidB64 = createdUuidB64 || '';
+          this.lastCreatedLabelName = entryName;
+
+          if (this.printLabelOnSave && createdUuidB64) {
+            try {
+              await printItemLabel(store, createdUuidB64);
+            } catch (printError) {
+              const parsedPrintMessage = formatPrintErrorMessage(printError);
+              this.printIssue = `${entryName} was ${operationVerb}, but printing failed: ${parsedPrintMessage}`;
+              store.addAlert({
+                type: 'warning',
+                message: this.printIssue,
+              });
             }
-          this.previewUrl = '';
+          }
-          this.successMessage = `${entry.name || this.form.name} was created successfully.`;
+
+          this.successMessage = `${entryName} was ${operationVerb} successfully.`;
           store.addAlert({
             type: 'success',
-            message: `${entry.name || this.form.name} was created successfully.`,
+            message: `${entryName} was ${operationVerb} successfully.`,
           });
-          saveStoredValue(STORAGE_KEYS.labelDraft, buildDraftPayload(this.form));
+          this.upsertPreview = entry;
+          saveLabelDraft(this.form);
         } catch (error) {
           this.fieldErrors = normalizeValidationError(error);
           this.submitError = error.message;
@@ -973,6 +1730,7 @@ export function labelCreatePageData(store) {
       }).catch(() => {});
     },
     reset(revokePreview = true) {
+      this.closeScanner();
       this.form = createDefaultForm();
       this.syncStockTypeState(this.form.stockType);
       this.suggestions = [];
@@ -980,8 +1738,13 @@ export function labelCreatePageData(store) {
       this.locationPickerOpen = false;
       this.successMessage = '';
       this.submitError = '';
+      this.lookupState.error = '';
       this.fieldErrors = {};
-      saveStoredValue(STORAGE_KEYS.labelDraft, this.form);
+      this.upsertPreview = null;
+      this.printIssue = '';
+      this.lastCreatedLabelUuidB64 = '';
+      this.lastCreatedLabelName = '';
+      saveLabelDraft(this.form);
       if (revokePreview && this.previewUrl.startsWith('blob:')) {
         URL.revokeObjectURL(this.previewUrl);
       }

src/features/register.js

@@ -6,6 +6,7 @@ import { kitchenSelectorData } from './kitchens/kitchen-selector.js';
 import { labelCreatePageData } from './labels/label-create-page.js';
 import { stockDetailPageData } from './stock/stock-detail-page.js';
 import { stockListPageData } from './stock/stock-list-page.js';
+import { stockScanPageData } from './stock/stock-scan-page.js';
 
 export function registerFeatureData(Alpine, store) {
   Alpine.data('alertsData', () => alertsData(store));
@@ -14,6 +15,7 @@ export function registerFeatureData(Alpine, store) {
   Alpine.data('dashboardPage', () => dashboardPageData(store));
   Alpine.data('kitchenSelector', () => kitchenSelectorData(store));
   Alpine.data('labelCreatePage', () => labelCreatePageData(store));
+  Alpine.data('stockScanPage', () => stockScanPageData(store));
   Alpine.data('stockListPage', () => stockListPageData(store));
   Alpine.data('stockDetailPage', () => stockDetailPageData(store));
 }

src/features/shared/scanner-modal.js

@@ -0,0 +1,65 @@
+export function renderScannerModal({
+  title = 'Scan barcode',
+  subtitle = 'Point your camera at the barcode.',
+  optionsMarkup = '',
+  manualCodeModel = 'scannerManualCode',
+  manualSubmitAction = 'processScannerManualCode()',
+  manualPlaceholder = 'Scan with hardware reader or paste code',
+  manualHelp = 'Manual entry works with keyboard-style barcode scanners.',
+  manualButtonLabel = 'Run',
+  manualDisabledExpression = 'scannerState.isLoading',
+}) {
+  return `
+      <div
+        class="scanner-modal-backdrop"
+        x-show="scannerState.isOpen"
+        @click.self="closeScanner()"
+        @keydown.escape.window="closeScanner()"
+      >
+        <div class="scanner-modal card border-0 shadow-lg">
+          <div class="card-body p-3 p-md-4">
+            <div class="d-flex align-items-center justify-content-between gap-3 mb-3">
+              <div>
+                <h2 class="h5 mb-1">${title}</h2>
+                <p class="text-body-secondary small mb-0">${subtitle}</p>
+              </div>
+              <button class="btn btn-sm btn-outline-secondary" type="button" @click="closeScanner()">Close</button>
+            </div>
+
+            ${optionsMarkup}
+
+            <form class="mb-3" @submit.prevent="${manualSubmitAction}">
+              <label class="form-label">Manual scan code</label>
+              <div class="input-group">
+                <input
+                  class="form-control"
+                  type="text"
+                  x-model="${manualCodeModel}"
+                  placeholder="${manualPlaceholder}"
+                  autocomplete="off"
+                />
+                <button class="btn btn-outline-primary" type="submit" :disabled="${manualDisabledExpression}">
+                  ${manualButtonLabel}
+                </button>
+              </div>
+              <div class="form-text">${manualHelp}</div>
+            </form>
+
+            <div class="scanner-video-shell mb-3">
+              <video class="scanner-video" x-ref="scannerVideo" autoplay muted playsinline></video>
+            </div>
+
+            <div class="d-flex flex-wrap align-items-center gap-2">
+              <div class="small text-body-secondary" x-show="scannerState.isLoading">Starting camera...</div>
+              <div class="small text-success" x-show="scannerState.lastDetectedCode" x-text="'Detected: ' + scannerState.lastDetectedCode"></div>
+              <button class="btn btn-outline-secondary btn-sm" type="button" @click="startScanner()" :disabled="scannerState.isLoading">Retry</button>
+            </div>
+
+            <template x-if="scannerState.error">
+              <div class="alert alert-warning py-2 mt-3 mb-0" x-text="scannerState.error"></div>
+            </template>
+          </div>
+        </div>
+      </div>
+  `;
+}

src/features/shared/scanner.js

@@ -0,0 +1,151 @@
+import {
+  BarcodeFormat,
+  BrowserMultiFormatReader,
+} from '@zxing/browser';
+import { DecodeHintType } from '@zxing/library';
+
+const KITCHEN_ITEM_PREFIX = 'kitchen:item::';
+const UUID_B64_PATTERN = /^[A-Za-z0-9_-]{22}$/;
+const UUID_B64_WITH_PADDING_PATTERN = /^[A-Za-z0-9_-]{22}={0,2}$/;
+
+const SCANNER_FORMATS = [
+  BarcodeFormat.DATA_MATRIX,
+  BarcodeFormat.EAN_13,
+  BarcodeFormat.EAN_8,
+  BarcodeFormat.UPC_A,
+  BarcodeFormat.UPC_E,
+  BarcodeFormat.CODE_128,
+  BarcodeFormat.CODE_39,
+  BarcodeFormat.QR_CODE,
+];
+
+export function normalizeIdentifierCode(value) {
+  return String(value || '').replace(/\s+/g, '').trim();
+}
+
+export function parseKitchenScanPayload(rawValue) {
+  const value = normalizeIdentifierCode(rawValue);
+  if (!value) {
+    return { type: 'empty', raw: '' };
+  }
+
+  if (value.toLowerCase().startsWith(KITCHEN_ITEM_PREFIX)) {
+    const uuidB64 = value.slice(KITCHEN_ITEM_PREFIX.length).trim();
+    return uuidB64
+      ? { type: 'item', uuidB64, raw: value }
+      : { type: 'unknown', raw: value };
+  }
+
+  // Backward compatibility: some labels/scanners provide the raw base64 UUID only.
+  if (UUID_B64_PATTERN.test(value) || UUID_B64_WITH_PADDING_PATTERN.test(value)) {
+    return {
+      type: 'item',
+      uuidB64: value.replace(/=+$/g, ''),
+      raw: value,
+    };
+  }
+
+  return { type: 'identifier', identifierCode: value, raw: value };
+}
+
+export function canUseCameraScanner() {
+  return Boolean(
+    typeof navigator !== 'undefined'
+    && navigator.mediaDevices
+    && typeof navigator.mediaDevices.getUserMedia === 'function',
+  );
+}
+
+export function createScannerReader() {
+  const hints = new Map();
+  hints.set(DecodeHintType.POSSIBLE_FORMATS, SCANNER_FORMATS);
+  return new BrowserMultiFormatReader(hints);
+}
+
+export function normalizeScannerError(error) {
+  const message = String(error?.message || '');
+  const normalized = message.toLowerCase();
+
+  if (error?.name === 'NotAllowedError' || normalized.includes('permission')) {
+    return 'Camera access was denied. Allow access to scan, or enter the code manually.';
+  }
+
+  if (error?.name === 'NotFoundError' || normalized.includes('requested device not found')) {
+    return 'No camera was found on this device. Enter the code manually.';
+  }
+
+  if (error?.name === 'NotReadableError' || normalized.includes('could not start video source')) {
+    return 'Camera is busy in another app. Close it there and try scanning again.';
+  }
+
+  return 'Could not start scanning. Enter the code manually.';
+}
+
+export async function startCameraScanner({
+  reader,
+  videoElement,
+  onDetected,
+  onDecodeError,
+}) {
+  const activeReader = reader || createScannerReader();
+  const shouldLogDecodeErrors = import.meta.env.DEV;
+  let lastDecodeErrorName = '';
+  let lastDecodeErrorAt = 0;
+
+  const controls = await activeReader.decodeFromConstraints(
+    {
+      audio: false,
+      video: {
+        facingMode: { ideal: 'environment' },
+      },
+    },
+    videoElement,
+    (result, error) => {
+      if (result) {
+        onDetected?.(result.getText?.() || '');
+        return;
+      }
+
+      if (!error) {
+        return;
+      }
+
+      onDecodeError?.(error);
+      if (!shouldLogDecodeErrors) {
+        return;
+      }
+
+      const errorName = String(error?.name || 'UnknownError');
+      const now = Date.now();
+      if (errorName !== lastDecodeErrorName || now - lastDecodeErrorAt > 2000) {
+        console.debug('[scanner] Ignoring frame decode error while scanning:', errorName, error?.message || '');
+        lastDecodeErrorName = errorName;
+        lastDecodeErrorAt = now;
+      }
+    },
+  );
+
+  return { reader: activeReader, controls };
+}
+
+export function stopCameraScanner({ reader, controls, videoElement }) {
+  try {
+    controls?.stop?.();
+  } catch {
+    // Ignore cleanup errors when scanner is already stopped.
+  }
+
+  try {
+    reader?.reset?.();
+  } catch {
+    // Ignore cleanup errors from stale reader state.
+  }
+
+  const stream = videoElement?.srcObject;
+  if (stream && typeof stream.getTracks === 'function') {
+    stream.getTracks().forEach((track) => track.stop());
+  }
+  if (videoElement) {
+    videoElement.srcObject = null;
+  }
+}

src/features/shared/stock-actions.js

@@ -0,0 +1,77 @@
+const LEVEL_TO_FACTOR = {
+  plenty: 0.75,
+  good: 0.50,
+  some: 0.25,
+  low: 0.10,
+  trace: 0.05,
+  gone: 0,
+};
+
+function levelFromRatio(ratio) {
+  if (ratio <= 0) {
+    return 'gone';
+  }
+  if (ratio >= 0.75) {
+    return 'plenty';
+  }
+  if (ratio >= 0.50) {
+    return 'good';
+  }
+  if (ratio >= 0.25) {
+    return 'some';
+  }
+  if (ratio >= 0.10) {
+    return 'low';
+  }
+  return 'trace';
+}
+
+export function buildGoneStockPayload(reason = 'consumed') {
+  return {
+    level: 'gone',
+    gone_reason: reason,
+  };
+}
+
+export function buildConsumeOneStockPayload(item) {
+  if (!item || item.active === false) {
+    return buildGoneStockPayload('consumed');
+  }
+
+  if (item.stock_type === 'binary') {
+    return buildGoneStockPayload('consumed');
+  }
+
+  const currentQuantity = Number(item.quantity || 0);
+  const nextQuantity = Math.max(currentQuantity - 1, 0);
+  if (item.stock_type === 'measured') {
+    return nextQuantity <= 0
+      ? { quantity: 0, level: 'gone', gone_reason: 'consumed' }
+      : { quantity: nextQuantity };
+  }
+
+  if (item.stock_type === 'descriptive') {
+    const initialQuantity = Number(item.quantity_initial || 0);
+    if (!initialQuantity) {
+      return buildGoneStockPayload('consumed');
+    }
+
+    const nextLevel = levelFromRatio(nextQuantity / initialQuantity);
+    return nextLevel === 'gone'
+      ? buildGoneStockPayload('consumed')
+      : { level: nextLevel };
+  }
+
+  const currentLevel = item.level || 'plenty';
+  const currentFactor = LEVEL_TO_FACTOR[currentLevel] ?? 1;
+  const initialQuantity = Number(item.quantity_initial || item.quantity || 1);
+  const estimatedQuantity = currentQuantity || currentFactor * initialQuantity;
+  const nextLevel = levelFromRatio(Math.max(estimatedQuantity - 1, 0) / initialQuantity);
+  return nextLevel === 'gone'
+    ? buildGoneStockPayload('consumed')
+    : { level: nextLevel };
+}
+
+export function isGonePayload(payload) {
+  return payload?.level === 'gone' || Number(payload?.quantity) <= 0;
+}

src/features/stock/stock-scan-page.js

@@ -0,0 +1,825 @@
+import {
+  applyItemUpsert,
+  createStockEvent,
+  getStockEntry,
+  listStockEntries,
+  lookupItemByIdentifier,
+  markStockGone,
+} from '../../api/stock.js';
+import { formatPrintErrorMessage, printItemLabel } from '../../api/labels.js';
+import { fetchLocations } from '../../api/locations.js';
+import { STORAGE_KEYS } from '../../app/config.js';
+import { mapLookupItemToForm } from '../labels/identifier-lookup-mapper.js';
+import { saveStoredValue } from '../shared/storage.js';
+import { createAsyncState, runAsyncState } from '../shared/ui-state.js';
+import { formatDate } from '../shared/date-utils.js';
+import { renderScannerModal } from '../shared/scanner-modal.js';
+import {
+  canUseCameraScanner,
+  createScannerReader,
+  normalizeIdentifierCode,
+  normalizeScannerError,
+  parseKitchenScanPayload,
+  startCameraScanner,
+  stopCameraScanner,
+} from '../shared/scanner.js';
+import {
+  buildConsumeOneStockPayload,
+  isGonePayload,
+} from '../shared/stock-actions.js';
+
+const SCAN_MODES = [
+  {
+    key: 'details',
+    label: 'Open details',
+    description: 'Scan and inspect the exact item.',
+  },
+  {
+    key: 'consume',
+    label: 'Consume standard unit',
+    description: 'Reduce stock by one standard unit.',
+  },
+  {
+    key: 'used',
+    label: 'Mark used',
+    description: 'Mark the item gone because it was consumed.',
+  },
+  {
+    key: 'spoiled',
+    label: 'Mark spoiled',
+    description: 'Mark the item gone because it spoiled.',
+  },
+  {
+    key: 'label',
+    label: 'Label workflow',
+    description: 'Lookup product data and continue to label creation.',
+  },
+];
+
+const LABEL_SCAN_ACTIONS = [
+  {
+    key: 'lookup',
+    label: 'Lookup',
+    description: 'Open label form with prefilled lookup data.',
+  },
+  {
+    key: 'create',
+    label: 'Create',
+    description: 'Create stock label directly when lookup has enough data.',
+  },
+  {
+    key: 'create_print',
+    label: 'Create & print',
+    description: 'Create and print when data is sufficient.',
+  },
+];
+
+function parseDateValue(value) {
+  if (!value) {
+    return null;
+  }
+  const [year, month, day] = String(value).split('-').map(Number);
+  if (!year || !month || !day) {
+    return null;
+  }
+  return new Date(year, month - 1, day);
+}
+
+function sortByOperationalPriority(entries, locationMap) {
+  return [...entries].sort((left, right) => {
+    const leftDate = parseDateValue(left.expire_date)?.getTime() ?? Number.MAX_SAFE_INTEGER;
+    const rightDate = parseDateValue(right.expire_date)?.getTime() ?? Number.MAX_SAFE_INTEGER;
+    if (leftDate !== rightDate) {
+      return leftDate - rightDate;
+    }
+
+    const leftLocation = locationMap[left.location_initial_uuid_b64] || '';
+    const rightLocation = locationMap[right.location_initial_uuid_b64] || '';
+    if (leftLocation !== rightLocation) {
+      return leftLocation.localeCompare(rightLocation);
+    }
+
+    return (left.name || '').localeCompare(right.name || '');
+  });
+}
+
+function quantityLabel(entry) {
+  if (!entry) {
+    return '';
+  }
+  if (entry.stock_type === 'binary') {
+    return entry.level === 'gone' ? 'Gone' : 'Available';
+  }
+  const quantity = entry.quantity ?? null;
+  const uom = entry.uom_symbol || '';
+  const measured = quantity !== null && quantity !== undefined ? `${quantity} ${uom}`.trim() : '';
+  return measured || entry.level || 'No quantity';
+}
+
+function todayIsoDate() {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, '0');
+  const day = String(now.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function createLabelDraftBase() {
+  return {
+    itemId: '',
+    itemUuidB64: '',
+    identifierCode: '',
+    externalSource: '',
+    externalId: '',
+    search: '',
+    name: '',
+    description: '',
+    quantity: '',
+    uom: 'g',
+    stockType: 'binary',
+    level: 'plenty',
+    energy: '',
+    energyUnit: 'kcal (100g/ml)',
+    productionDate: todayIsoDate(),
+    expireDays: '',
+    expirationDate: '',
+    locationId: '',
+  };
+}
+
+export function renderStockScanPage() {
+  const scannerOptionsMarkup = `
+            <div class="scan-modal-mode-list mb-3">
+              <template x-for="mode in scanModes" :key="'modal-' + mode.key">
+                <button
+                  class="btn btn-sm scan-modal-mode-btn"
+                  type="button"
+                  :class="scanMode === mode.key ? 'scan-modal-mode-btn-active' : 'btn-outline-secondary'"
+                  @click="scanMode = mode.key"
+                >
+                  <span x-text="mode.label"></span>
+                </button>
+              </template>
+            </div>
+
+            <template x-if="scanMode === 'label'">
+              <div class="scan-label-mode-list mb-3">
+                <template x-for="action in labelScanActions" :key="'modal-label-' + action.key">
+                  <button
+                    class="btn btn-sm scan-label-mode-btn"
+                    type="button"
+                    :class="labelScanAction === action.key ? 'scan-label-mode-btn-active' : 'btn-outline-secondary'"
+                    @click="labelScanAction = action.key"
+                  >
+                    <span x-text="action.label"></span>
+                  </button>
+                </template>
+              </div>
+            </template>
+  `;
+
+  return `
+    <section class="container-xxl py-4 py-lg-5" x-data="stockScanPage()" x-init="init()">
+      <div class="scan-hero card border-0 shadow-sm mb-4">
+        <div class="card-body p-4 p-lg-5">
+          <div class="d-flex flex-column flex-lg-row justify-content-between gap-4">
+            <div>
+              <p class="eyebrow mb-2">Scan operations</p>
+              <h1 class="h3 mb-2">Scan a label or barcode and act immediately.</h1>
+              <p class="text-body-secondary mb-0">
+                DataMatrix labels open the exact stock item. Product barcodes resolve matching active stock and ask when there is ambiguity.
+              </p>
+            </div>
+            <div class="d-flex align-items-start gap-2">
+              <button class="btn btn-primary btn-lg" type="button" @click="openScanner()" :disabled="!scannerState.hasCamera || actionState.isLoading">
+                Start camera
+              </button>
+              <a class="btn btn-outline-secondary btn-lg" href="#/stock">Browse stock</a>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div class="row g-4">
+        <div class="col-12 col-xl-5">
+          <div class="card border-0 shadow-sm h-100">
+            <div class="card-body p-4">
+              <h2 class="h5 mb-3">Choose scan action</h2>
+              <div class="scan-mode-grid">
+                <template x-for="mode in scanModes" :key="mode.key">
+                  <button
+                    class="scan-mode-card"
+                    type="button"
+                    :class="scanMode === mode.key ? 'scan-mode-card-active' : ''"
+                    @click="scanMode = mode.key"
+                  >
+                    <span class="fw-semibold" x-text="mode.label"></span>
+                    <span class="small text-body-secondary" x-text="mode.description"></span>
+                  </button>
+                </template>
+              </div>
+
+              <template x-if="scanMode === 'label'">
+                <div class="mt-3">
+                  <label class="form-label mb-2">Label action</label>
+                  <div class="scan-label-mode-list">
+                    <template x-for="action in labelScanActions" :key="action.key">
+                      <button
+                        class="btn btn-sm scan-label-mode-btn"
+                        type="button"
+                        :class="labelScanAction === action.key ? 'scan-label-mode-btn-active' : 'btn-outline-secondary'"
+                        @click="labelScanAction = action.key"
+                      >
+                        <span x-text="action.label"></span>
+                      </button>
+                    </template>
+                  </div>
+                  <div class="small text-body-secondary mt-2" x-text="activeLabelActionDescription()"></div>
+                </div>
+              </template>
+
+              <div class="mt-4">
+                <label class="form-label">Manual scan code</label>
+                <div class="input-group">
+                  <input class="form-control" type="text" x-model="manualCode" placeholder="Scan with hardware reader or paste code" autocomplete="off" />
+                  <button class="btn btn-outline-primary" type="button" @click="processManualCode()" :disabled="actionState.isLoading">Run</button>
+                </div>
+                <div class="form-text">Works with keyboard-style barcode scanners and manual paste.</div>
+              </div>
+
+              <template x-if="!scannerState.hasCamera">
+                <div class="alert alert-warning mt-4 mb-0">
+                  Camera scanning is not available in this browser. Manual entry still works.
+                </div>
+              </template>
+            </div>
+          </div>
+        </div>
+
+        <div class="col-12 col-xl-7">
+          <div class="card border-0 shadow-sm h-100">
+            <div class="card-body p-4">
+              <div class="d-flex justify-content-between gap-3 align-items-start mb-3">
+                <div>
+                  <h2 class="h5 mb-1">Scan result</h2>
+                  <p class="text-body-secondary small mb-0">Last scanned code and the action outcome.</p>
+                </div>
+                <button class="btn btn-sm btn-outline-secondary" type="button" @click="clearResult()" x-show="result.item || result.message || candidateItems.length">Clear</button>
+              </div>
+
+              <template x-if="actionState.error">
+                <div class="alert alert-danger" x-text="actionState.error"></div>
+              </template>
+
+              <template x-if="result.message">
+                <div class="alert" :class="result.type === 'success' ? 'alert-success' : 'alert-info'" x-text="result.message"></div>
+              </template>
+
+              <template x-if="candidateItems.length">
+                <div>
+                  <h3 class="h6 mb-2">Choose matching stock item</h3>
+                  <div class="list-group scan-candidate-list">
+                    <template x-for="item in candidateItems" :key="item.uuid_b64">
+                      <button class="list-group-item list-group-item-action" type="button" @click="selectCandidate(item)">
+                        <div class="d-flex justify-content-between gap-3">
+                          <div>
+                            <div class="fw-semibold" x-text="item.name"></div>
+                            <div class="small text-body-secondary" x-text="locationLabel(item)"></div>
+                          </div>
+                          <div class="small text-end">
+                            <div class="fw-semibold" x-text="quantityLabel(item)"></div>
+                            <div class="text-body-secondary" x-text="formatDate(item.expire_date)"></div>
+                          </div>
+                        </div>
+                      </button>
+                    </template>
+                  </div>
+                </div>
+              </template>
+
+              <template x-if="result.item">
+                <div class="scan-result-card">
+                  <div class="d-flex flex-column flex-md-row justify-content-between gap-3">
+                    <div>
+                      <p class="eyebrow mb-2">Item</p>
+                      <h3 class="h5 mb-1" x-text="result.item.name"></h3>
+                      <p class="text-body-secondary mb-2" x-text="result.item.description || 'No description'"></p>
+                      <div class="small text-body-secondary">
+                        <span x-text="quantityLabel(result.item)"></span>
+                        <span aria-hidden="true"> · </span>
+                        <span x-text="locationLabel(result.item)"></span>
+                      </div>
+                    </div>
+                    <div class="d-flex flex-wrap align-content-start gap-2">
+                      <a class="btn btn-outline-primary btn-sm" :href="detailHref(result.item)">View item</a>
+                      <button class="btn btn-outline-secondary btn-sm" type="button" @click="printResultLabel()" :disabled="printState.isLoading">
+                        <span x-show="!printState.isLoading">Print label</span>
+                        <span x-show="printState.isLoading">Printing...</span>
+                      </button>
+                      <button class="btn btn-primary btn-sm" type="button" @click="openScanner()" :disabled="!scannerState.hasCamera">Scan another</button>
+                    </div>
+                  </div>
+                </div>
+              </template>
+
+              <template x-if="!actionState.error && !result.message && !result.item && !candidateItems.length">
+                <div class="empty-state-inline">
+                  Pick an action, scan a kitchen label or barcode, and the result will appear here.
+                </div>
+              </template>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      ${renderScannerModal({
+        title: 'Scan for <span x-text="activeModeLabel()"></span>',
+        subtitle: 'Point your camera at a DataMatrix label or product barcode.',
+        optionsMarkup: scannerOptionsMarkup,
+        manualCodeModel: 'scannerManualCode',
+        manualSubmitAction: 'processScannerManualCode()',
+        manualPlaceholder: 'Scan with hardware reader or paste code',
+        manualHelp: 'Works with keyboard-style barcode scanners and manual paste.',
+        manualDisabledExpression: 'actionState.isLoading || scannerState.isLoading',
+      })}
+    </section>
+  `;
+}
+
+export function stockScanPageData(store) {
+  return {
+    scanModes: SCAN_MODES,
+    labelScanActions: LABEL_SCAN_ACTIONS,
+    scanMode: 'details',
+    labelScanAction: 'lookup',
+    manualCode: '',
+    scannerManualCode: '',
+    scannerReader: null,
+    scannerControls: null,
+    scannerState: {
+      isOpen: false,
+      isLoading: false,
+      hasCamera: false,
+      error: '',
+      lastDetectedCode: '',
+    },
+    actionState: createAsyncState(),
+    printState: createAsyncState(),
+    result: {
+      type: '',
+      message: '',
+      item: null,
+    },
+    candidateItems: [],
+    locations: [],
+    locationPathByUuid: {},
+    async init() {
+      this.scannerState.hasCamera = canUseCameraScanner();
+      if (!store.isConnected) {
+        return;
+      }
+      const locations = await fetchLocations(store).catch(() => ({ flat: [] }));
+      this.locations = locations.flat || [];
+      this.locationPathByUuid = Object.fromEntries(
+        this.locations
+          .filter((location) => location.uuid_b64)
+          .map((location) => [location.uuid_b64, location.pathLabel || location.name]),
+      );
+    },
+    destroy() {
+      this.stopScanner();
+    },
+    activeModeLabel() {
+      return this.scanModes.find((mode) => mode.key === this.scanMode)?.label || 'scan';
+    },
+    activeLabelActionDescription() {
+      return this.labelScanActions.find((action) => action.key === this.labelScanAction)?.description || '';
+    },
+    async openScanner() {
+      this.scannerState.error = '';
+      this.scannerState.lastDetectedCode = '';
+      this.scannerManualCode = this.manualCode;
+      this.scannerState.isOpen = true;
+      await this.$nextTick();
+      await this.startScanner();
+    },
+    async startScanner() {
+      this.scannerState.error = '';
+      this.scannerState.lastDetectedCode = '';
+
+      if (!canUseCameraScanner()) {
+        this.scannerState.hasCamera = false;
+        this.scannerState.error = 'Camera scanning is not supported in this browser. Enter the code manually.';
+        return;
+      }
+
+      const videoElement = this.$refs.scannerVideo;
+      if (!videoElement) {
+        this.scannerState.error = 'Scanner video element is unavailable. Close and reopen scanner.';
+        return;
+      }
+
+      this.stopScanner();
+      this.scannerState.isLoading = true;
+      try {
+        if (!this.scannerReader) {
+          this.scannerReader = createScannerReader();
+        }
+        const session = await startCameraScanner({
+          reader: this.scannerReader,
+          videoElement,
+          onDetected: (code) => this.onScanDetected(code),
+        });
+        this.scannerReader = session.reader;
+        this.scannerControls = session.controls;
+      } catch (error) {
+        this.scannerState.error = normalizeScannerError(error);
+      } finally {
+        this.scannerState.isLoading = false;
+      }
+    },
+    stopScanner() {
+      stopCameraScanner({
+        reader: this.scannerReader,
+        controls: this.scannerControls,
+        videoElement: this.$refs.scannerVideo,
+      });
+      this.scannerControls = null;
+    },
+    closeScanner() {
+      this.stopScanner();
+      this.scannerState.isOpen = false;
+      this.scannerState.isLoading = false;
+      this.scannerState.error = '';
+    },
+    onScanDetected(rawCode) {
+      const code = normalizeIdentifierCode(rawCode);
+      if (!code || !this.scannerState.isOpen) {
+        return;
+      }
+      this.scannerState.lastDetectedCode = code;
+      this.scannerManualCode = code;
+      this.closeScanner();
+      this.processScannedCode(code);
+    },
+    processScannerManualCode() {
+      const code = normalizeIdentifierCode(this.scannerManualCode);
+      if (!code) {
+        this.scannerState.error = 'Scan or enter a code first.';
+        return;
+      }
+      this.scannerState.lastDetectedCode = code;
+      this.manualCode = code;
+      this.closeScanner();
+      this.processScannedCode(code);
+    },
+    processManualCode() {
+      this.processScannedCode(this.manualCode);
+    },
+    async processScannedCode(rawCode) {
+      const parsed = parseKitchenScanPayload(rawCode);
+      this.clearResult();
+      if (parsed.type === 'empty') {
+        this.actionState.error = 'Scan or enter a code first.';
+        return;
+      }
+
+      if (this.scanMode === 'label') {
+        await runAsyncState(this.actionState, async () => {
+          await this.processLabelScan(parsed);
+        }).catch(() => {});
+        return;
+      }
+
+      await runAsyncState(this.actionState, async () => {
+        if (parsed.type === 'item') {
+          const item = await getStockEntry(store, parsed.uuidB64, { allowInactive: true });
+          await this.executeAction(item);
+          return;
+        }
+
+        const matches = await this.resolveIdentifierMatches(parsed.identifierCode);
+        if (!matches.length) {
+          this.result = {
+            type: 'info',
+            message: `No active stock item matched ${parsed.identifierCode}.`,
+            item: null,
+          };
+          return;
+        }
+
+        if (matches.length > 1) {
+          this.candidateItems = matches;
+          this.result = {
+            type: 'info',
+            message: `${matches.length} stock items match this barcode. Choose the one to ${this.activeModeLabel().toLowerCase()}.`,
+            item: null,
+          };
+          return;
+        }
+
+        await this.executeAction(matches[0]);
+      }).catch(() => {});
+    },
+    buildLabelDraftFromLookup(lookupItem, identifierCode) {
+      const mapped = mapLookupItemToForm({
+        form: {
+          ...createLabelDraftBase(),
+          identifierCode: identifierCode || '',
+        },
+        lookupItem,
+        locations: this.locations,
+      });
+
+      const stockType = ['measured', 'descriptive', 'binary'].includes(lookupItem?.stock_type)
+        ? lookupItem.stock_type
+        : mapped.form.stockType || 'binary';
+      const level = stockType === 'measured'
+        ? ''
+        : (mapped.form.level || 'plenty');
+
+      return {
+        form: {
+          ...mapped.form,
+          stockType,
+          level,
+          identifierCode: normalizeIdentifierCode(identifierCode || mapped.form.identifierCode),
+        },
+        locationSearch: mapped.locationSearch || '',
+      };
+    },
+    locationUuidFromDraft(form) {
+      const location = this.locations.find((entry) => String(entry.id) === String(form.locationId));
+      return location?.uuid_b64 || null;
+    },
+    canAutoCreateLabel(form) {
+      if (!String(form.name || '').trim()) {
+        return false;
+      }
+      if (!this.locationUuidFromDraft(form)) {
+        return false;
+      }
+      if (!form.productionDate) {
+        return false;
+      }
+      if (form.stockType === 'measured') {
+        const quantity = Number(form.quantity);
+        if (Number.isNaN(quantity) || quantity <= 0) {
+          return false;
+        }
+      }
+      return true;
+    },
+    buildUpsertPayloadFromDraft(form) {
+      const locationUuidB64 = this.locationUuidFromDraft(form);
+      const quantity = form.quantity === ''
+        ? form.stockType === 'binary'
+          ? 1
+          : null
+        : Number(form.quantity);
+
+      return {
+        uuid_b64: form.itemUuidB64 || null,
+        identifier_code: form.identifierCode || null,
+        external_source: form.externalSource || null,
+        external_id: form.externalId || null,
+        item: {
+          name: String(form.name || '').trim(),
+          description: String(form.description || '').trim(),
+          quantity_initial: Number.isNaN(quantity) ? null : quantity,
+          uom_symbol: String(form.uom || '').trim() || null,
+          calories: form.energy === '' ? null : Number(form.energy),
+          calories_unit: String(form.energyUnit || '').trim() || null,
+          stock_type: form.stockType,
+          level: form.stockType === 'measured' ? null : (form.level || null),
+          date: form.productionDate || null,
+          expire_date: form.expirationDate || null,
+          location_initial: locationUuidB64,
+        },
+      };
+    },
+    saveLabelDraftAndOpenForm(form) {
+      saveStoredValue(STORAGE_KEYS.labelDraft, {
+        form,
+        savedAt: Date.now(),
+      });
+      window.__loncApp.navigate('/labels/new');
+    },
+    async processLabelScan(parsed) {
+      let identifierCode = '';
+      if (parsed.type === 'item') {
+        const item = await getStockEntry(store, parsed.uuidB64, { allowInactive: true });
+        identifierCode = normalizeIdentifierCode(item?.identifier_code);
+        if (!identifierCode) {
+          this.result = {
+            type: 'info',
+            message: `${item?.name || 'Item'} has no identifier code. Open label form to complete it first.`,
+            item: item || null,
+          };
+          return;
+        }
+      } else {
+        identifierCode = normalizeIdentifierCode(parsed.identifierCode);
+      }
+
+      if (!identifierCode) {
+        throw new Error('No identifier code found in scan.');
+      }
+
+      const lookup = await lookupItemByIdentifier(store, identifierCode);
+      if (lookup.status !== 'ok' || !lookup.item) {
+        this.result = {
+          type: 'info',
+          message: `Lookup did not return a usable item for ${identifierCode}.`,
+          item: null,
+        };
+        return;
+      }
+
+      const draft = this.buildLabelDraftFromLookup(lookup.item, identifierCode);
+      if (this.labelScanAction === 'lookup') {
+        this.saveLabelDraftAndOpenForm(draft.form);
+        store.addAlert({
+          type: 'success',
+          message: `Lookup loaded for ${identifierCode}. Continue in label form.`,
+        });
+        return;
+      }
+
+      if (!this.canAutoCreateLabel(draft.form)) {
+        this.saveLabelDraftAndOpenForm(draft.form);
+        store.addAlert({
+          type: 'info',
+          message: 'Lookup data is incomplete for direct create. Please complete required fields in label form.',
+        });
+        return;
+      }
+
+      const upsertPayload = this.buildUpsertPayloadFromDraft(draft.form);
+      const entry = await applyItemUpsert(store, upsertPayload);
+      const entryName = entry.item?.name || draft.form.name;
+      const operationVerb = entry.operation === 'update' ? 'updated' : 'created';
+
+      if (this.labelScanAction === 'create_print') {
+        const createdUuidB64 = entry.item?.uuid_b64 || '';
+        if (!createdUuidB64) {
+          const message = `${entryName} was ${operationVerb}, but label printing is unavailable for this entry.`;
+          this.result = {
+            type: 'info',
+            message,
+            item: entry.item || null,
+          };
+          store.addAlert({
+            type: 'warning',
+            message,
+          });
+          return;
+        }
+
+        try {
+          await printItemLabel(store, createdUuidB64);
+          const message = `${entryName} was ${operationVerb} and printed. Ready for next scan.`;
+          this.result = {
+            type: 'success',
+            message,
+            item: entry.item || null,
+          };
+          store.addAlert({
+            type: 'success',
+            message,
+          });
+          void this.openScanner().catch(() => {});
+        } catch (error) {
+          const parsed = formatPrintErrorMessage(error);
+          const message = `${entryName} was ${operationVerb}, but printing failed: ${parsed} Use "Print label" to retry.`;
+          this.result = {
+            type: 'info',
+            message,
+            item: entry.item || null,
+          };
+          store.addAlert({
+            type: 'warning',
+            message: `${entryName} was ${operationVerb}, but printing failed: ${parsed}`,
+          });
+        }
+        return;
+      }
+
+      const message = `${entryName} was ${operationVerb}. Ready for next scan.`;
+      this.result = {
+        type: 'success',
+        message,
+        item: entry.item || null,
+      };
+      store.addAlert({
+        type: 'success',
+        message,
+      });
+      void this.openScanner().catch(() => {});
+    },
+    async resolveIdentifierMatches(identifierCode) {
+      const normalizedCode = normalizeIdentifierCode(identifierCode);
+      if (!normalizedCode) {
+        return [];
+      }
+
+      const entries = await listStockEntries(store).catch(() => []);
+      const matches = entries.filter((entry) =>
+        normalizeIdentifierCode(entry.identifier_code) === normalizedCode,
+      );
+      return sortByOperationalPriority(matches, this.locationPathByUuid);
+    },
+    async selectCandidate(item) {
+      this.candidateItems = [];
+      await runAsyncState(this.actionState, async () => {
+        await this.executeAction(item);
+      }).catch(() => {});
+    },
+    async executeAction(item) {
+      if (!item?.uuid_b64) {
+        throw new Error('Scanned item could not be resolved.');
+      }
+
+      if (this.scanMode === 'details') {
+        window.__loncApp.navigate(`/stock/${item.uuid_b64}?from=scan`);
+        return;
+      }
+
+      if (item.active === false) {
+        this.result = {
+          type: 'info',
+          message: `${item.name} is already out of stock.`,
+          item,
+        };
+        return;
+      }
+
+      if (this.scanMode === 'used' || this.scanMode === 'spoiled') {
+        const reason = this.scanMode === 'spoiled' ? 'spoiled' : 'consumed';
+        const result = await markStockGone(store, item.uuid_b64, reason);
+        const label = reason === 'spoiled' ? 'marked spoilt' : 'marked used';
+        this.result = {
+          type: result.status === 'already_gone' ? 'info' : 'success',
+          message: result.status === 'already_gone'
+            ? `${item.name} was already out of stock.`
+            : `${item.name} was ${label}.`,
+          item: { ...item, active: false, level: 'gone', gone_reason: reason },
+        };
+        return;
+      }
+
+      const payload = buildConsumeOneStockPayload(item);
+      await createStockEvent(store, item.uuid_b64, payload);
+      const refreshed = await getStockEntry(store, item.uuid_b64, {
+        allowInactive: isGonePayload(payload),
+      }).catch(() => ({
+        ...item,
+        active: false,
+        level: 'gone',
+      }));
+      this.result = {
+        type: 'success',
+        message: `${item.name} stock was reduced by one standard unit.`,
+        item: refreshed,
+      };
+    },
+    async printResultLabel() {
+      if (!this.result.item?.uuid_b64) {
+        return;
+      }
+
+      await runAsyncState(this.printState, async () => {
+        try {
+          await printItemLabel(store, this.result.item.uuid_b64);
+          store.addAlert({
+            type: 'success',
+            message: `${this.result.item.name} label sent to printer.`,
+          });
+        } catch (error) {
+          const parsed = formatPrintErrorMessage(error);
+          store.addAlert({
+            type: 'warning',
+            message: `Could not print ${this.result.item.name} label: ${parsed}`,
+          });
+        }
+      }).catch(() => {});
+    },
+    clearResult() {
+      this.actionState.error = '';
+      this.result = {
+        type: '',
+        message: '',
+        item: null,
+      };
+      this.candidateItems = [];
+    },
+    detailHref(item) {
+      return `#/stock/${item.uuid_b64}?from=scan`;
+    },
+    locationLabel(item) {
+      return this.locationPathByUuid[item?.location_initial_uuid_b64] || 'No location assigned';
+    },
+    quantityLabel,
+    formatDate,
+  };
+}

src/styles/app.css

@@ -26,6 +26,45 @@ body {
   position: relative;
 }
 
+.app-footer {
+  background: rgba(255, 255, 255, 0.8);
+  backdrop-filter: blur(4px);
+}
+
+.input-group-label-submit .input-group-text {
+  background: rgba(255, 255, 255, 0.9);
+  white-space: nowrap;
+}
+
+.label-actions-row .btn {
+  white-space: nowrap;
+}
+
+.input-group-label-submit {
+  width: auto;
+  flex: 0 0 auto;
+}
+
+.input-group-label-submit .btn {
+  white-space: nowrap;
+}
+
+.label-action-btn {
+  white-space: nowrap !important;
+  flex: 0 0 auto;
+  min-width: max-content;
+}
+
+@media (min-width: 768px) {
+  .label-actions-row {
+    flex-wrap: nowrap !important;
+  }
+
+  .label-actions-primary {
+    flex-wrap: nowrap !important;
+  }
+}
+
 .brand-mark {
   display: inline-grid;
   place-items: center;
@@ -275,10 +314,112 @@ body {
   color: var(--lonc-primary);
 }
 
+.stock-filter-hub {
+  background:
+    linear-gradient(160deg, rgba(255, 255, 255, 0.94), rgba(245, 250, 255, 0.88)),
+    linear-gradient(135deg, rgba(93, 169, 255, 0.1), rgba(31, 75, 153, 0.06));
+}
+
+.stock-workspace {
+  align-items: flex-start;
+}
+
+.stock-results-pane {
+  min-width: 0;
+}
+
+.stock-filter-summary {
+  padding: 0.85rem 0.95rem;
+  border-radius: 0.9rem;
+  border: 1px dashed rgba(31, 75, 153, 0.24);
+  background: rgba(255, 255, 255, 0.7);
+  min-height: 100%;
+}
+
+.stock-filter-rail .overview-list-locations {
+  max-height: 18rem;
+}
+
+.stock-filter-rail .location-overview-columns {
+  grid-template-columns: 1fr;
+}
+
+@media (min-width: 768px) and (max-width: 1199.98px) {
+  .stock-filter-panels {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    align-items: start;
+  }
+
+  .stock-filter-panels.stock-filter-panels-single-open {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (min-width: 1200px) {
+  .stock-filter-rail .stock-filter-hub {
+    position: sticky;
+    top: 1rem;
+  }
+}
+
 .stock-view-switch {
-  display: inline-flex;
+  display: grid;
-  flex-wrap: wrap;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
-  gap: 0.5rem;
+  gap: 0.65rem;
+}
+
+.stock-view-switch-wrap {
+  min-width: min(100%, 38rem);
+}
+
+.stock-view-tab {
+  display: grid;
+  align-content: start;
+  gap: 0.2rem;
+  text-align: left;
+  border: 1px solid var(--lonc-border);
+  border-radius: 0.9rem;
+  background: rgba(255, 255, 255, 0.66);
+  color: inherit;
+  padding: 0.65rem 0.85rem;
+  transition:
+    border-color 160ms ease,
+    box-shadow 160ms ease,
+    background-color 160ms ease,
+    transform 160ms ease;
+}
+
+.stock-view-tab:hover {
+  transform: translateY(-1px);
+  border-color: rgba(31, 75, 153, 0.24);
+  box-shadow: 0 8px 16px rgba(24, 42, 79, 0.08);
+}
+
+.stock-view-tab:focus-visible {
+  outline: 2px solid rgba(31, 75, 153, 0.4);
+  outline-offset: 2px;
+}
+
+.stock-view-tab-active {
+  border-color: rgba(31, 75, 153, 0.42);
+  background: rgba(31, 75, 153, 0.1);
+  box-shadow: inset 0 0 0 1px rgba(31, 75, 153, 0.18);
+}
+
+.stock-view-tab-title {
+  font-weight: 700;
+  font-size: 0.95rem;
+}
+
+.stock-view-tab-subtitle {
+  font-size: 0.78rem;
+  color: var(--lonc-muted);
+}
+
+@media (max-width: 767.98px) {
+  .stock-view-switch {
+    grid-template-columns: 1fr;
+  }
 }
 
 .overview-row-single-open > [class*='col-'] {
@@ -290,6 +431,16 @@ body {
   height: auto;
 }
 
+.stock-filter-panel-card {
+  border: 1px solid var(--lonc-border);
+  border-radius: 1rem;
+  background: rgba(255, 255, 255, 0.84);
+}
+
+.stock-filter-panel-card[open] {
+  box-shadow: 0 10px 24px rgba(24, 42, 79, 0.08);
+}
+
 .overview-summary {
   display: block;
   cursor: pointer;
@@ -553,21 +704,69 @@ button.legend-card:focus-visible {
   list-style: none;
 }
 
+.grouped-stock-summary-row {
+  min-height: 0;
+}
+
+.grouped-stock-summary-title {
+  font-size: 1.1rem;
+  line-height: 1.2;
+}
+
+.grouped-stock-summary-description {
+  margin: 0.12rem 0 0.35rem;
+}
+
 .grouped-stock-summary::-webkit-details-marker {
   display: none;
 }
 
 .grouped-stock-summary-meta {
   align-items: center;
+  align-content: flex-start;
+  column-gap: 0.95rem;
+  row-gap: 0.08rem;
+  line-height: 1.25;
+}
+
+.grouped-stock-summary-status {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: flex-start;
+  gap: 0.4rem 0.75rem;
+}
+
+.grouped-stock-secondary-details {
+  border-top: 1px dashed rgba(31, 39, 64, 0.14);
+  padding-top: 0.75rem;
+}
+
+.grouped-stock-secondary-toggle {
+  border-radius: 0.85rem;
+  border: 1px solid var(--lonc-border);
+  padding: 0.5rem 0.75rem;
+  background: rgba(255, 255, 255, 0.66);
+}
+
+.grouped-stock-secondary-toggle > summary {
+  list-style: none;
+  cursor: pointer;
+}
+
+.grouped-stock-secondary-toggle > summary::-webkit-details-marker {
+  display: none;
 }
 
 .grouped-stock-toggle-label {
   color: var(--lonc-primary);
+  font-size: 0.8rem;
+  line-height: 1.1;
 }
 
 .grouped-stock-toggle-label::after {
   content: 'Expand';
-  margin-left: 0.35rem;
+  margin-left: 0.25rem;
 }
 
 .grouped-stock-card[open] .grouped-stock-toggle-label::after {
@@ -594,14 +793,20 @@ button.legend-card:focus-visible {
   border-left-color: #6c757d;
 }
 
+@media (min-width: 1200px) {
+  .grouped-stock-summary-status {
+    justify-content: flex-end;
+  }
+}
+
 .grouped-stock-items {
   display: grid;
-  gap: 0.75rem;
+  gap: 0.55rem;
 }
 
 .grouped-stock-item {
   display: block;
-  padding: 0.9rem 1rem;
+  padding: 0.65rem 0.8rem;
   border-radius: 0.95rem;
   border: 1px solid var(--lonc-border);
   background: rgba(255, 255, 255, 0.72);
@@ -638,8 +843,72 @@ button.legend-card:focus-visible {
   background: rgba(108, 117, 125, 0.08);
 }
 
-.grouped-stock-item-meta {
+.grouped-stock-item-row {
-  justify-content: flex-start;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto auto;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.grouped-stock-item-main {
+  min-width: 0;
+}
+
+.grouped-stock-item-title-line {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 0.6rem;
+}
+
+.grouped-stock-item-name {
+  font-size: 1rem;
+  line-height: 1.2;
+}
+
+.grouped-stock-item-id {
+  color: var(--lonc-muted);
+  font-size: 0.8rem;
+}
+
+.grouped-stock-item-aux {
+  display: grid;
+  gap: 0.2rem;
+  text-align: right;
+  justify-items: end;
+  white-space: nowrap;
+}
+
+.grouped-stock-item-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  white-space: nowrap;
+}
+
+.grouped-stock-item-link {
+  font-size: 0.8rem;
+}
+
+.stock-item-link-disabled {
+  pointer-events: none;
+  opacity: 0.55;
+}
+
+.stock-item-refresh-indicator {
+  color: rgba(31, 39, 64, 0.78) !important;
+  font-weight: 600;
+  margin-top: 0.15rem;
+}
+
+.stock-item-refreshing {
+  opacity: 0.94;
+}
+
+.grouped-stock-mark-gone {
+  padding: 0.2rem 0.55rem;
+  line-height: 1.2;
+  white-space: nowrap;
 }
 
 .grouped-stock-item-subline {
@@ -664,9 +933,62 @@ button.legend-card:focus-visible {
   font-weight: 700;
 }
 
-@media (min-width: 1200px) {
+.grouped-stock-close-row {
-  .grouped-stock-item-meta {
+  display: flex;
   justify-content: flex-end;
+  margin-top: 0.2rem;
+  padding-top: 0.2rem;
+  border-top: 1px dashed rgba(31, 39, 64, 0.12);
+}
+
+.grouped-stock-close {
+  padding: 0.1rem 0.2rem;
+  font-size: 0.78rem;
+  color: rgba(31, 39, 64, 0.82);
+  line-height: 1.1;
+}
+
+.grouped-stock-close:hover {
+  color: var(--lonc-primary-dark);
+}
+
+@media (max-width: 991.98px) {
+  .grouped-stock-item-row {
+    grid-template-columns: minmax(0, 1fr) auto;
+    align-items: start;
+  }
+
+  .grouped-stock-item-actions {
+    grid-column: 1 / -1;
+    justify-content: space-between;
+    padding-top: 0.15rem;
+  }
+
+  .grouped-stock-item-aux {
+    text-align: left;
+    justify-items: start;
+  }
+}
+
+@media (max-width: 575.98px) {
+  .grouped-stock-item {
+    padding: 0.6rem 0.7rem;
+  }
+
+  .grouped-stock-item-row {
+    grid-template-columns: 1fr;
+    gap: 0.4rem;
+  }
+
+  .grouped-stock-item-aux {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    text-align: left;
+  }
+
+  .grouped-stock-item-title-line {
+    gap: 0.45rem;
   }
 }
 
@@ -747,6 +1069,139 @@ button.legend-card:focus-visible {
   cursor: pointer;
 }
 
+.scanner-modal-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 1100;
+  display: grid;
+  place-items: center;
+  padding: 1rem;
+  background: rgba(16, 24, 40, 0.62);
+  backdrop-filter: blur(2px);
+}
+
+.scanner-modal {
+  width: min(40rem, 100%);
+  border-radius: 1rem;
+}
+
+.scanner-video-shell {
+  border-radius: 0.85rem;
+  overflow: hidden;
+  border: 1px solid rgba(31, 75, 153, 0.2);
+  background: #0f172a;
+}
+
+.scanner-video {
+  display: block;
+  width: 100%;
+  aspect-ratio: 16 / 10;
+  object-fit: cover;
+}
+
+.scan-hero {
+  background:
+    radial-gradient(circle at 15% 20%, rgba(80, 180, 140, 0.18), transparent 28rem),
+    linear-gradient(145deg, rgba(255, 255, 255, 0.96), rgba(245, 250, 255, 0.92));
+}
+
+.scan-mode-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0.8rem;
+}
+
+.scan-mode-card {
+  display: grid;
+  gap: 0.25rem;
+  min-height: 6rem;
+  padding: 1rem;
+  text-align: left;
+  color: inherit;
+  background: rgba(255, 255, 255, 0.74);
+  border: 1px solid var(--lonc-border);
+  border-radius: 1rem;
+  transition:
+    transform 160ms ease,
+    box-shadow 160ms ease,
+    border-color 160ms ease,
+    background-color 160ms ease;
+}
+
+.scan-mode-card:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 12px 24px rgba(24, 42, 79, 0.08);
+}
+
+.scan-mode-card-active {
+  border-color: rgba(31, 75, 153, 0.42);
+  background: rgba(31, 75, 153, 0.1);
+  box-shadow: inset 0 0 0 1px rgba(31, 75, 153, 0.18);
+}
+
+.scan-candidate-list {
+  max-height: 24rem;
+  overflow-y: auto;
+}
+
+.scan-modal-mode-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.45rem;
+}
+
+.scan-modal-mode-btn {
+  border-radius: 999px;
+}
+
+.scan-modal-mode-btn-active {
+  color: #fff;
+  background: var(--lonc-primary);
+  border-color: var(--lonc-primary);
+}
+
+.scan-label-mode-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.45rem;
+}
+
+.scan-label-mode-btn {
+  border-radius: 999px;
+}
+
+.scan-label-mode-btn-active {
+  color: #fff;
+  background: var(--lonc-primary-dark);
+  border-color: var(--lonc-primary-dark);
+}
+
+.scan-result-card {
+  padding: 1.25rem;
+  border-radius: 1.25rem;
+  border: 1px solid var(--lonc-border);
+  background:
+    linear-gradient(135deg, rgba(235, 243, 255, 0.78), rgba(255, 255, 255, 0.92));
+}
+
+.empty-state-inline {
+  display: grid;
+  min-height: 12rem;
+  place-items: center;
+  padding: 2rem;
+  color: var(--lonc-muted);
+  text-align: center;
+  border: 1px dashed rgba(31, 75, 153, 0.22);
+  border-radius: 1.25rem;
+  background: rgba(255, 255, 255, 0.58);
+}
+
+@media (max-width: 575.98px) {
+  .scan-mode-grid {
+    grid-template-columns: 1fr;
+  }
+}
+
 @media (max-width: 991.98px) {
   .navbar {
     backdrop-filter: blur(10px);
@@ -760,4 +1215,15 @@ button.legend-card:focus-visible {
   .empty-preview {
     border-radius: 1.25rem;
   }
+
+  .scanner-modal-backdrop {
+    align-items: end;
+  }
+
+  .scanner-modal {
+    width: 100%;
+    margin-bottom: 0.75rem;
+    border-bottom-left-radius: 0;
+    border-bottom-right-radius: 0;
+  }
 }

tests/api/categories.test.js

@@ -0,0 +1,67 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const apiRequestMock = vi.fn();
+
+vi.mock('../../src/api/client.js', () => ({
+  getPath(key) {
+    const paths = {
+      categories: 'kitchen/categories',
+    };
+    return paths[key];
+  },
+  apiRequest: (...args) => apiRequestMock(...args),
+}));
+
+const { listCategories } = await import('../../src/api/categories.js');
+
+describe('api/categories', () => {
+  beforeEach(() => {
+    apiRequestMock.mockReset();
+  });
+
+  it('forwards explicit pagination and filters', async () => {
+    apiRequestMock.mockResolvedValueOnce([]);
+
+    await listCategories(
+      { config: { database: 'db' } },
+      { searchName: 'dairy', active: true, limit: 10, offset: 20, orderBy: 'name', orderDir: 'asc' },
+    );
+
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/categories',
+      {
+        query: {
+          search_name: 'dairy',
+          active: true,
+          order_by: 'name',
+          order_dir: 'asc',
+          limit: 10,
+          offset: 20,
+        },
+      },
+    );
+  });
+
+  it('aggregates category pages by default', async () => {
+    apiRequestMock
+      .mockResolvedValueOnce(Array.from({ length: 100 }, (_, id) => ({ id: id + 1 })))
+      .mockResolvedValueOnce([{ id: 101 }]);
+
+    const response = await listCategories({ config: { database: 'db' } }, {});
+
+    expect(response).toHaveLength(101);
+    expect(apiRequestMock).toHaveBeenNthCalledWith(
+      1,
+      { config: { database: 'db' } },
+      'kitchen/categories',
+      { query: { limit: 100, offset: 0 } },
+    );
+    expect(apiRequestMock).toHaveBeenNthCalledWith(
+      2,
+      { config: { database: 'db' } },
+      'kitchen/categories',
+      { query: { limit: 100, offset: 100 } },
+    );
+  });
+});

tests/api/client.test.js

@@ -48,27 +48,25 @@ describe('api/client', () => {
   it('returns configured path constants', () => {
     expect(getPath('items')).toBe('kitchen/items');
     expect(getPath('userApplication')).toBe('user/application/');
+    expect(getPath('changes')).toBe('kitchen/changes');
   });
 
-  it('builds kitchen urls with encoded path segments and query values', () => {
+  it('builds database-scoped kitchen urls with encoded query values', () => {
     const store = createStore({
       config: {
         baseUrl: 'https://api.example.com',
         database: 'my db',
       },
-      activeKitchen: {
-        id: 'kitchen/01',
-      },
     });
 
     const url = buildKitchenApiUrl(store, 'kitchen/items/grouped', {
       search_name: 'Milk + eggs',
-      expanded: 1,
+      expanded: true,
       ignored: '',
     });
 
     expect(url).toBe(
-      'https://api.example.com/my%20db/kitchen/kitchen%2F01/kitchen/items/grouped?search_name=Milk+%2B+eggs&expanded=1',
+      'https://api.example.com/my%20db/kitchen/items/grouped?search_name=Milk+%2B+eggs&expanded=true',
     );
   });
 
@@ -90,14 +88,14 @@ describe('api/client', () => {
         name: 'Rice',
       },
       query: {
-        label: 1,
+        label: true,
       },
     });
 
     expect(payload).toEqual({ ok: true });
 
     const [url, request] = fetchSpy.mock.calls[0];
-    expect(url).toBe('/kitchen-db/kitchen/kitchen-1/kitchen/items?label=1');
+    expect(url).toBe('/kitchen-db/kitchen/items?label=true');
     expect(request.method).toBe('POST');
     expect(request.body).toBe('{"name":"Rice"}');
     expect(request.headers.get('Accept')).toBe('application/json');

tests/api/labels.test.js

@@ -0,0 +1,89 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const apiRequestMock = vi.fn();
+
+vi.mock('../../src/api/client.js', () => ({
+  getPath(key) {
+    const paths = {
+      items: 'kitchen/items',
+    };
+    return paths[key];
+  },
+  apiRequest: (...args) => apiRequestMock(...args),
+}));
+
+const {
+  formatPrintErrorMessage,
+  getItemLabel,
+  previewLabel,
+} = await import('../../src/api/labels.js');
+
+describe('api/labels', () => {
+  beforeEach(() => {
+    apiRequestMock.mockReset();
+  });
+
+  it('previewLabel uses boolean label/preview query flags', async () => {
+    apiRequestMock.mockResolvedValueOnce({
+      label: 'YWJj',
+    });
+
+    const response = await previewLabel({ config: { database: 'db' } }, { name: 'Rice' });
+
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items',
+      {
+        method: 'POST',
+        body: { name: 'Rice' },
+        accept: 'image/svg+xml, image/png, application/json',
+        query: { label: true, preview: true },
+      },
+    );
+    expect(response).toEqual({
+      objectUrl: 'data:image/png;base64,YWJj',
+      contentType: 'image/png',
+    });
+  });
+
+  it('getItemLabel fetches PNG from /label endpoint', async () => {
+    apiRequestMock.mockResolvedValueOnce({
+      label: 'YWJj',
+    });
+
+    const response = await getItemLabel({ config: { database: 'db' } }, 'item-1');
+
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items/item-1/label',
+      {
+        method: 'GET',
+        accept: 'image/png, application/json',
+      },
+    );
+    expect(response).toEqual({
+      objectUrl: 'data:image/png;base64,YWJj',
+      contentType: 'image/png',
+    });
+  });
+});
+
+describe('api/labels formatPrintErrorMessage', () => {
+  it('maps printer_unavailable payload to user-friendly message', () => {
+    const message = formatPrintErrorMessage({
+      status: 503,
+      payload: {
+        code: 'printer_unavailable',
+        message: 'Backend says unavailable',
+        details: { printer: 'Office Zebra' },
+      },
+    });
+
+    expect(message).toBe('Printer is unavailable. (printer: Office Zebra)');
+  });
+
+  it('falls back to generic message when payload is missing', () => {
+    const message = formatPrintErrorMessage(new Error('Something failed'));
+    expect(message).toBe('Something failed');
+  });
+});

tests/api/stock.test.js

@@ -0,0 +1,456 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const apiRequestMock = vi.fn();
+
+vi.mock('../../src/api/client.js', () => ({
+  getPath(key) {
+    const paths = {
+      items: 'kitchen/items',
+      changes: 'kitchen/changes',
+    };
+    return paths[key];
+  },
+  apiRequest: (...args) => apiRequestMock(...args),
+}));
+
+const {
+  adjustStockEntry,
+  applyItemUpsert,
+  getStockEntry,
+  listGroupedStockEntries,
+  listKitchenChanges,
+  listStockEntries,
+  markStockGone,
+  lookupItemByIdentifier,
+  lookupItemDetails,
+  patchStockItem,
+  previewItemUpsert,
+  updateStockItem,
+  useStockItem,
+} = await import('../../src/api/stock.js');
+
+describe('api/stock', () => {
+  beforeEach(() => {
+    apiRequestMock.mockReset();
+  });
+
+  it('listStockEntries forwards explicit pagination query filters', async () => {
+    apiRequestMock.mockResolvedValueOnce([]);
+
+    await listStockEntries(
+      { config: { database: 'db' } },
+      { searchName: 'Milk', limit: 20, offset: 40 },
+    );
+
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items',
+      {
+        query: {
+          search_name: 'Milk',
+          limit: 20,
+          offset: 40,
+        },
+      },
+    );
+  });
+
+  it('listStockEntries aggregates all pages by default', async () => {
+    apiRequestMock
+      .mockResolvedValueOnce(Array.from({ length: 100 }, (_, id) => ({ id: id + 1 })))
+      .mockResolvedValueOnce([{ id: 101 }]);
+
+    const response = await listStockEntries(
+      { config: { database: 'db' } },
+      { searchName: 'Milk' },
+    );
+
+    expect(response).toHaveLength(101);
+    expect(apiRequestMock).toHaveBeenNthCalledWith(
+      1,
+      { config: { database: 'db' } },
+      'kitchen/items',
+      { query: { search_name: 'Milk', limit: 100, offset: 0 } },
+    );
+    expect(apiRequestMock).toHaveBeenNthCalledWith(
+      2,
+      { config: { database: 'db' } },
+      'kitchen/items',
+      { query: { search_name: 'Milk', limit: 100, offset: 100 } },
+    );
+  });
+
+  it('listGroupedStockEntries forwards explicit pagination options', async () => {
+    apiRequestMock.mockResolvedValueOnce([]);
+
+    await listGroupedStockEntries(
+      { config: { database: 'db' } },
+      { expanded: false, searchName: 'Rice', limit: 10, offset: 0 },
+    );
+
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items/grouped',
+      {
+        query: {
+          expanded: false,
+          search_name: 'Rice',
+          limit: 10,
+          offset: 0,
+        },
+      },
+    );
+  });
+
+  it('listGroupedStockEntries aggregates all pages by default', async () => {
+    apiRequestMock
+      .mockResolvedValueOnce(Array.from({ length: 100 }, (_, id) => ({ id: id + 1 })))
+      .mockResolvedValueOnce([{ id: 101 }]);
+
+    const response = await listGroupedStockEntries(
+      { config: { database: 'db' } },
+      { expanded: true, searchName: 'Rice' },
+    );
+
+    expect(response).toHaveLength(101);
+    expect(apiRequestMock).toHaveBeenNthCalledWith(
+      1,
+      { config: { database: 'db' } },
+      'kitchen/items/grouped',
+      { query: { expanded: true, search_name: 'Rice', limit: 100, offset: 0 } },
+    );
+    expect(apiRequestMock).toHaveBeenNthCalledWith(
+      2,
+      { config: { database: 'db' } },
+      'kitchen/items/grouped',
+      { query: { expanded: true, search_name: 'Rice', limit: 100, offset: 100 } },
+    );
+  });
+
+  it('getStockEntry fetches item without allow_inactive by default', async () => {
+    apiRequestMock.mockResolvedValueOnce({ uuid_b64: 'item-1', name: 'Milk' });
+
+    const result = await getStockEntry({ config: { database: 'db' } }, 'item-1');
+
+    expect(result).toEqual({ uuid_b64: 'item-1', name: 'Milk' });
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items/item-1',
+    );
+  });
+
+  it('getStockEntry forwards allow_inactive when requested', async () => {
+    apiRequestMock.mockResolvedValueOnce({ uuid_b64: 'item-2', active: false });
+
+    const result = await getStockEntry(
+      { config: { database: 'db' } },
+      'item-2',
+      { allowInactive: true },
+    );
+
+    expect(result).toEqual({ uuid_b64: 'item-2', active: false });
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items/item-2',
+      { query: { allow_inactive: true } },
+    );
+  });
+
+  it('listKitchenChanges returns normalized changes payload', async () => {
+    apiRequestMock.mockResolvedValueOnce({
+      since: 'cursor-1',
+      next_cursor: 'cursor-2',
+      changes: [{ type: 'item', action: 'upsert', timestamp: '2026-04-10T10:00:00Z' }],
+    });
+
+    const result = await listKitchenChanges({ config: { database: 'db' } }, { limit: 10 });
+
+    expect(result).toEqual({
+      since: 'cursor-1',
+      nextCursor: 'cursor-2',
+      changes: [{ type: 'item', action: 'upsert', timestamp: '2026-04-10T10:00:00Z' }],
+    });
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/changes',
+      { query: { since: undefined, limit: 10 } },
+    );
+  });
+
+  it('listKitchenChanges falls back to empty shape when changes are missing', async () => {
+    apiRequestMock.mockResolvedValueOnce({});
+
+    const result = await listKitchenChanges({ config: { database: 'db' } }, {});
+
+    expect(result).toEqual({
+      since: null,
+      nextCursor: null,
+      changes: [],
+    });
+  });
+
+  it('previewItemUpsert normalizes preview response', async () => {
+    apiRequestMock.mockResolvedValueOnce({
+      status: 'ok',
+      mode: 'preview',
+      operation: 'update',
+      match_type: 'uuid_b64',
+      matched_item: { uuid_b64: 'abc', name: 'Rice' },
+      payload: { name: 'Rice' },
+    });
+
+    const response = await previewItemUpsert({ config: { database: 'db' } }, { item: { name: 'Rice' } });
+
+    expect(response).toEqual({
+      status: 'ok',
+      mode: 'preview',
+      operation: 'update',
+      matchType: 'uuid_b64',
+      matchedItem: { uuid_b64: 'abc', name: 'Rice' },
+      item: null,
+      payload: { name: 'Rice' },
+    });
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items/upsert',
+      {
+        method: 'POST',
+        body: { item: { name: 'Rice' } },
+        query: { mode: 'preview' },
+      },
+    );
+  });
+
+  it('applyItemUpsert normalizes apply response', async () => {
+    apiRequestMock.mockResolvedValueOnce({
+      status: 'ok',
+      mode: 'apply',
+      operation: 'create',
+      match_type: null,
+      item: { uuid_b64: 'new1', name: 'Beans' },
+    });
+
+    const response = await applyItemUpsert({ config: { database: 'db' } }, { item: { name: 'Beans' } });
+
+    expect(response).toEqual({
+      status: 'ok',
+      mode: 'apply',
+      operation: 'create',
+      matchType: null,
+      matchedItem: null,
+      item: { uuid_b64: 'new1', name: 'Beans' },
+      payload: null,
+    });
+  });
+
+  it('lookupItemByIdentifier normalizes lookup metadata fields', async () => {
+    apiRequestMock.mockResolvedValueOnce({
+      status: 'rate_limited',
+      source: 'openfoodfacts',
+      cache_hit: true,
+      identifier_code: '1234',
+      identifier_type: 'ean_13',
+      retry_after_seconds: 42,
+      payload_fetched_at: '2026-04-11T08:00:00Z',
+      stale_cache: true,
+      item: null,
+    });
+
+    const response = await lookupItemByIdentifier(
+      { config: { database: 'db' } },
+      '1234',
+    );
+
+    expect(response).toEqual({
+      status: 'rate_limited',
+      source: 'openfoodfacts',
+      cacheHit: true,
+      identifierCode: '1234',
+      identifierType: 'ean_13',
+      retryAfterSeconds: 42,
+      payloadFetchedAt: '2026-04-11T08:00:00Z',
+      staleCache: true,
+      item: null,
+    });
+  });
+
+  it('lookupItemDetails maps item lookup response and query flag', async () => {
+    apiRequestMock.mockResolvedValueOnce({
+      status: 'ok',
+      found: true,
+      update: true,
+      identifier_code: '555',
+      identifier_type: 'ean_13',
+      preview: { name: 'Milk' },
+      updated_fields: ['name'],
+      off_payload_fetched_at: '2026-04-11T09:00:00Z',
+      retry_after_seconds: null,
+      stale_cache: false,
+      item: { uuid_b64: 'item-1', name: 'Milk' },
+    });
+
+    const response = await lookupItemDetails(
+      { config: { database: 'db' } },
+      'item-1',
+      { update: true },
+    );
+
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items/item-1/lookup',
+      { method: 'POST', query: { update: true } },
+    );
+    expect(response).toEqual({
+      status: 'ok',
+      found: true,
+      update: true,
+      identifierCode: '555',
+      identifierType: 'ean_13',
+      preview: { name: 'Milk' },
+      updatedFields: ['name'],
+      offPayloadFetchedAt: '2026-04-11T09:00:00Z',
+      retryAfterSeconds: null,
+      staleCache: false,
+      item: { uuid_b64: 'item-1', name: 'Milk' },
+    });
+  });
+
+  it('patchStockItem sends PATCH to item endpoint', async () => {
+    apiRequestMock.mockResolvedValueOnce({
+      uuid_b64: 'item-1',
+      identifier_code: '3830012345678',
+    });
+
+    const response = await patchStockItem(
+      { config: { database: 'db' } },
+      'item-1',
+      { identifier_code: '3830012345678' },
+    );
+
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items/item-1',
+      { method: 'PATCH', body: { identifier_code: '3830012345678' } },
+    );
+    expect(response).toEqual({
+      uuid_b64: 'item-1',
+      identifier_code: '3830012345678',
+    });
+  });
+
+  it('updateStockItem posts stock event and re-fetches updated item', async () => {
+    apiRequestMock
+      .mockResolvedValueOnce({ status: 'OK', stock: { id: 1 } })
+      .mockResolvedValueOnce({ uuid_b64: 'item-1', quantity: 2 });
+
+    const response = await updateStockItem(
+      { config: { database: 'db' } },
+      'item-1',
+      { quantity: 2 },
+    );
+
+    expect(apiRequestMock).toHaveBeenNthCalledWith(
+      1,
+      { config: { database: 'db' } },
+      'kitchen/items/item-1/stock',
+      { method: 'POST', body: { quantity: 2 } },
+    );
+    expect(apiRequestMock).toHaveBeenNthCalledWith(
+      2,
+      { config: { database: 'db' } },
+      'kitchen/items/item-1',
+    );
+    expect(response).toEqual({ uuid_b64: 'item-1', quantity: 2 });
+  });
+
+  it('adjustStockEntry posts stock event and re-fetches updated item', async () => {
+    apiRequestMock
+      .mockResolvedValueOnce({ status: 'OK', stock: { id: 2 } })
+      .mockResolvedValueOnce({ uuid_b64: 'item-1', level: 'good' });
+
+    const response = await adjustStockEntry(
+      { config: { database: 'db' } },
+      'item-1',
+      { level: 'good' },
+    );
+
+    expect(apiRequestMock).toHaveBeenNthCalledWith(
+      1,
+      { config: { database: 'db' } },
+      'kitchen/items/item-1/stock',
+      { method: 'POST', body: { level: 'good' } },
+    );
+    expect(apiRequestMock).toHaveBeenNthCalledWith(
+      2,
+      { config: { database: 'db' } },
+      'kitchen/items/item-1',
+    );
+    expect(response).toEqual({ uuid_b64: 'item-1', level: 'good' });
+  });
+
+  it('useStockItem returns used on 204', async () => {
+    apiRequestMock.mockResolvedValueOnce(null);
+
+    const result = await useStockItem({ config: { database: 'db' } }, 'item-1');
+
+    expect(result).toEqual({ status: 'used' });
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items/item-1/use',
+      { method: 'POST' },
+    );
+  });
+
+  it('useStockItem returns already_gone on 409', async () => {
+    apiRequestMock.mockRejectedValueOnce({ status: 409, message: 'Item is out of stock.' });
+
+    const result = await useStockItem({ config: { database: 'db' } }, 'item-1');
+
+    expect(result).toEqual({ status: 'already_gone' });
+  });
+
+  it('useStockItem returns already_gone on 404', async () => {
+    apiRequestMock.mockRejectedValueOnce({ status: 404 });
+
+    const result = await useStockItem({ config: { database: 'db' } }, 'item-1');
+
+    expect(result).toEqual({ status: 'already_gone' });
+    expect(apiRequestMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('useStockItem does not fallback on unrelated client errors', async () => {
+    apiRequestMock.mockRejectedValueOnce({ status: 422, message: 'validation_error' });
+
+    await expect(useStockItem({ config: { database: 'db' } }, 'item-1')).rejects.toMatchObject({
+      status: 422,
+      message: 'validation_error',
+    });
+    expect(apiRequestMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('markStockGone uses /use endpoint for consumed reason', async () => {
+    apiRequestMock.mockResolvedValueOnce(null);
+
+    const result = await markStockGone({ config: { database: 'db' } }, 'item-1', 'consumed');
+
+    expect(result).toEqual({ status: 'gone', reason: 'consumed' });
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items/item-1/use',
+      { method: 'POST' },
+    );
+  });
+
+  it('markStockGone uses /stock endpoint for non-consumed reasons', async () => {
+    apiRequestMock.mockResolvedValueOnce({ status: 'OK', stock: { id: 3 } });
+
+    const result = await markStockGone({ config: { database: 'db' } }, 'item-1', 'spoiled');
+
+    expect(result).toEqual({ status: 'gone', reason: 'spoiled' });
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items/item-1/stock',
+      { method: 'POST', body: { level: 'gone', gone_reason: 'spoiled' } },
+    );
+  });
+});

tests/features/dashboard/dashboard-page.test.js

@@ -0,0 +1,193 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const listKitchenChangesMock = vi.fn();
+const getStockEntryMock = vi.fn();
+const fetchLocationsMock = vi.fn();
+
+vi.mock('../../../src/api/stock.js', () => ({
+  listKitchenChanges: (...args) => listKitchenChangesMock(...args),
+  getStockEntry: (...args) => getStockEntryMock(...args),
+}));
+
+vi.mock('../../../src/api/locations.js', () => ({
+  fetchLocations: (...args) => fetchLocationsMock(...args),
+}));
+
+const { dashboardPageData, renderDashboardPage } = await import('../../../src/features/dashboard/dashboard-page.js');
+
+describe('features/dashboard/dashboard-page', () => {
+  beforeEach(() => {
+    listKitchenChangesMock.mockReset();
+    getStockEntryMock.mockReset();
+    fetchLocationsMock.mockReset();
+  });
+
+  it('renders dashboard with recent changes section', () => {
+    const html = renderDashboardPage();
+    expect(html).toContain('Recent changes');
+    expect(html).toContain('x-data="dashboardPage()"');
+    expect(html).toContain('Saved means the backend created or updated a record.');
+  });
+
+  it('loads recent changes on init and renders item-focused state lines', async () => {
+    listKitchenChangesMock.mockResolvedValueOnce({
+      since: null,
+      nextCursor: null,
+      changes: [{
+        type: 'item',
+        action: 'upsert',
+        timestamp: '2026-04-10T10:00:00Z',
+        item: {
+          uuid_b64: 'u1',
+          name: 'Rice',
+          stock_type: 'measured',
+          quantity: 3,
+          uom_symbol: 'kg',
+          level: 'good',
+          expire_date: '2026-04-21',
+          location_initial_uuid_b64: 'loc1',
+        },
+      }],
+    });
+    fetchLocationsMock.mockResolvedValueOnce({
+      flat: [{ uuid_b64: 'loc1', pathLabel: 'Pantry / Shelf A' }],
+    });
+
+    const store = {
+      isConnected: true,
+      setActiveKitchen: vi.fn(),
+      addAlert: vi.fn(),
+    };
+    const data = dashboardPageData(store);
+
+    await data.init();
+
+    expect(listKitchenChangesMock).toHaveBeenCalledWith(store, { limit: 10 });
+    expect(data.recentChanges).toHaveLength(1);
+    expect(data.changesState.error).toBe('');
+    expect(data.changeHeadline(data.recentChanges[0])).toBe('Item saved: Rice');
+    expect(data.changeStateLine(data.recentChanges[0])).toContain('Quantity: 3 kg');
+    expect(data.changeStateLine(data.recentChanges[0])).toContain('Location: Pantry / Shelf A');
+    expect(getStockEntryMock).not.toHaveBeenCalled();
+  });
+
+  it('resolves stock event item context via item lookup when needed', async () => {
+    listKitchenChangesMock.mockResolvedValueOnce({
+      since: null,
+      nextCursor: null,
+      changes: [{
+        type: 'stock',
+        action: 'upsert',
+        timestamp: '2026-04-10T10:00:00Z',
+        stock: {
+          item_uuid_b64: 'item-uuid-1',
+          quantity: 0.5,
+          uom_symbol: 'kg',
+          level: 'some',
+          location_uuid_b64: 'loc2',
+        },
+      }],
+    });
+    getStockEntryMock.mockResolvedValueOnce({
+      uuid_b64: 'item-uuid-1',
+      name: 'Flour',
+      stock_type: 'measured',
+      expire_date: '2026-05-02',
+    });
+    fetchLocationsMock.mockResolvedValueOnce({
+      flat: [{ uuid_b64: 'loc2', pathLabel: 'Pantry / Bin 2' }],
+    });
+
+    const data = dashboardPageData({
+      isConnected: true,
+      setActiveKitchen: vi.fn(),
+      addAlert: vi.fn(),
+    });
+
+    await data.refreshChanges();
+
+    expect(data.changeHeadline(data.recentChanges[0])).toBe('Stock saved: Flour');
+    expect(data.changeStateLine(data.recentChanges[0])).toContain('Quantity: 0.5 kg');
+    expect(data.changeStateLine(data.recentChanges[0])).toContain('Level: Some');
+    expect(data.changeStateLine(data.recentChanges[0])).toContain('Location: Pantry / Bin 2');
+    expect(getStockEntryMock).toHaveBeenCalledWith(expect.anything(), 'item-uuid-1');
+  });
+
+  it('retries stock event item lookup with allowInactive after 404', async () => {
+    listKitchenChangesMock.mockResolvedValueOnce({
+      since: null,
+      nextCursor: null,
+      changes: [{
+        type: 'stock',
+        action: 'upsert',
+        timestamp: '2026-04-10T10:00:00Z',
+        stock: {
+          item_uuid_b64: 'item-uuid-2',
+          quantity: 1,
+          uom_symbol: 'pcs',
+        },
+      }],
+    });
+    getStockEntryMock
+      .mockRejectedValueOnce(Object.assign(new Error('Not found'), { status: 404 }))
+      .mockResolvedValueOnce({
+        uuid_b64: 'item-uuid-2',
+        name: 'Archived pasta',
+        stock_type: 'measured',
+      });
+    fetchLocationsMock.mockResolvedValueOnce({ flat: [] });
+
+    const store = {
+      isConnected: true,
+      setActiveKitchen: vi.fn(),
+      addAlert: vi.fn(),
+    };
+    const data = dashboardPageData(store);
+
+    await data.refreshChanges();
+
+    expect(getStockEntryMock).toHaveBeenNthCalledWith(1, store, 'item-uuid-2');
+    expect(getStockEntryMock).toHaveBeenNthCalledWith(
+      2,
+      store,
+      'item-uuid-2',
+      { allowInactive: true },
+    );
+    expect(data.changeHeadline(data.recentChanges[0])).toBe('Stock saved: Archived pasta');
+    expect(data.changeStateLine(data.recentChanges[0])).toContain('Quantity: 1 pcs');
+  });
+
+  it('keeps empty state when API returns no changes', async () => {
+    listKitchenChangesMock.mockResolvedValueOnce({
+      since: null,
+      nextCursor: null,
+      changes: [],
+    });
+    fetchLocationsMock.mockResolvedValueOnce({ flat: [] });
+
+    const data = dashboardPageData({
+      isConnected: true,
+      setActiveKitchen: vi.fn(),
+      addAlert: vi.fn(),
+    });
+
+    await data.refreshChanges();
+
+    expect(data.recentChanges).toEqual([]);
+    expect(data.changesState.error).toBe('');
+  });
+
+  it('captures refresh errors in async state', async () => {
+    listKitchenChangesMock.mockRejectedValueOnce(new Error('Feed unavailable'));
+    const data = dashboardPageData({
+      isConnected: true,
+      setActiveKitchen: vi.fn(),
+      addAlert: vi.fn(),
+    });
+
+    await data.refreshChanges();
+
+    expect(data.changesState.error).toBe('Feed unavailable');
+    expect(data.recentChanges).toEqual([]);
+  });
+});

tests/features/labels/identifier-lookup-feedback.test.js

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from 'vitest';
+
+const lookupItemByIdentifierMock = vi.fn();
+
+vi.mock('../../../src/api/stock.js', () => ({
+  applyItemUpsert: vi.fn(),
+  previewItemUpsert: vi.fn(),
+  searchItemDefinitions: vi.fn(async () => []),
+  lookupItemByIdentifier: (...args) => lookupItemByIdentifierMock(...args),
+}));
+
+vi.mock('../../../src/api/labels.js', () => ({
+  previewLabel: vi.fn(async () => ({ objectUrl: 'blob:preview' })),
+  printItemLabel: vi.fn(async () => null),
+  formatPrintErrorMessage: (error) => error?.message || 'Printing failed.',
+}));
+
+vi.mock('../../../src/api/locations.js', () => ({
+  fetchLocations: vi.fn(async () => ({ flat: [], tree: [] })),
+}));
+
+const { labelCreatePageData } = await import('../../../src/features/labels/label-create-page.js');
+
+describe('label identifier lookup feedback', () => {
+  it('shows retry hint for rate-limited lookup responses', () => {
+    const data = labelCreatePageData({
+      isConnected: false,
+      activeKitchen: { id: 1 },
+      addAlert: vi.fn(),
+    });
+
+    const message = data.lookupStatusMessageWithDetails(
+      { status: 'rate_limited', retryAfterSeconds: 30 },
+      '3830012345678',
+    );
+
+    expect(message).toContain('rate-limited');
+    expect(message).toContain('Retry in 30s');
+  });
+
+  it('builds metadata-aware success message with source/cache/freshness context', () => {
+    const data = labelCreatePageData({
+      isConnected: false,
+      activeKitchen: { id: 1 },
+      addAlert: vi.fn(),
+    });
+
+    const message = data.lookupSuccessMessage({
+      source: 'openfoodfacts',
+      cacheHit: true,
+      staleCache: true,
+      payloadFetchedAt: '2026-04-11T09:00:00Z',
+    });
+
+    expect(message).toContain('OpenFoodFacts');
+    expect(message).toContain('cache hit');
+    expect(message).toContain('stale cache');
+    expect(message).toContain('fetched:');
+  });
+
+  it('applies non-ok lookup status as warning message with details', async () => {
+    lookupItemByIdentifierMock.mockResolvedValueOnce({
+      status: 'rate_limited',
+      retryAfterSeconds: 45,
+      source: 'openfoodfacts',
+      cacheHit: false,
+      staleCache: false,
+      item: null,
+    });
+
+    const addAlert = vi.fn();
+    const data = labelCreatePageData({
+      isConnected: false,
+      activeKitchen: { id: 1 },
+      addAlert,
+    });
+    data.form.identifierCode = '3830012345678';
+
+    await data.lookupIdentifierDetails();
+
+    expect(data.lookupState.error).toContain('Retry in 45s');
+    expect(addAlert).toHaveBeenCalledWith({
+      type: 'warning',
+      message: data.lookupState.error,
+    });
+  });
+});

tests/features/labels/identifier-lookup-mapper.test.js

@@ -0,0 +1,187 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  deriveLookupExpirationDays,
+  mapLookupItemToForm,
+} from '../../../src/features/labels/identifier-lookup-mapper.js';
+
+function createForm(overrides = {}) {
+  return {
+    itemId: '',
+    itemUuidB64: '',
+    identifierCode: '',
+    externalSource: '',
+    externalId: '',
+    search: '',
+    name: '',
+    description: '',
+    quantity: '',
+    uom: 'g',
+    stockType: 'binary',
+    level: 'plenty',
+    energy: '',
+    energyUnit: 'kcal (100g/ml)',
+    productionDate: '2026-04-10',
+    expireDays: '',
+    expirationDate: '',
+    locationId: '',
+    ...overrides,
+  };
+}
+
+describe('identifier lookup form mapper', () => {
+  it('overwrites mapped fields with non-empty values and preserves production date', () => {
+    const form = createForm({
+      name: 'Old name',
+      productionDate: '2026-04-10',
+    });
+    const lookupItem = {
+      identifier_code: ' 3830012345678 ',
+      name: 'Yogurt',
+      description: 'Plain yogurt',
+      stock_type: 'measured',
+      level: 'low',
+      quantity_initial: 0,
+      uom_symbol: 'ml',
+      calories: 61,
+      calories_unit: 'kcal',
+      external_source: 'openfoodfacts',
+      external_id: 'off-123',
+      expiration_days: 5,
+      location_initial_uuid_b64: 'loc-freezer',
+    };
+    const locations = [
+      { id: 44, uuid_b64: 'loc-freezer', name: 'Freezer' },
+    ];
+
+    const result = mapLookupItemToForm({
+      form,
+      lookupItem,
+      locations,
+    });
+
+    expect(result.didUpdate).toBe(true);
+    expect(result.form.identifierCode).toBe('3830012345678');
+    expect(result.form.name).toBe('Yogurt');
+    expect(result.form.search).toBe('Yogurt');
+    expect(result.form.description).toBe('Plain yogurt');
+    expect(result.form.stockType).toBe('binary');
+    expect(result.form.level).toBe('low');
+    expect(result.form.quantity).toBe('0');
+    expect(result.form.uom).toBe('ml');
+    expect(result.form.energy).toBe('61');
+    expect(result.form.energyUnit).toBe('kcal');
+    expect(result.form.externalSource).toBe('openfoodfacts');
+    expect(result.form.externalId).toBe('off-123');
+    expect(result.form.productionDate).toBe('2026-04-10');
+    expect(result.form.expireDays).toBe('5');
+    expect(result.form.expirationDate).toBe('2026-04-15');
+    expect(result.form.locationId).toBe('44');
+    expect(result.locationSearch).toBe('Freezer');
+  });
+
+  it('clears mapped fields when lookup values are empty or null', () => {
+    const form = createForm({
+      name: 'Keep me',
+      description: 'Still here',
+      quantity: '2',
+      uom: 'pc',
+      energy: '120',
+      energyUnit: 'kcal',
+      stockType: 'descriptive',
+      level: 'some',
+      search: 'Keep me',
+      identifierCode: '12345678',
+      externalSource: 'cache',
+      externalId: 'xyz',
+      expireDays: '3',
+      expirationDate: '2026-04-13',
+    });
+    const lookupItem = {
+      name: '   ',
+      description: null,
+      quantity_initial: null,
+      uom_symbol: '',
+      calories: null,
+      calories_unit: '',
+      stock_type: '',
+      level: '',
+      identifier_code: '',
+      external_source: null,
+      external_id: '   ',
+      date: 'bad-date',
+      expire_date: '2026-05-20',
+    };
+
+    const result = mapLookupItemToForm({
+      form,
+      lookupItem,
+      locations: [],
+    });
+
+    expect(result.didUpdate).toBe(true);
+    expect(result.form.identifierCode).toBe('');
+    expect(result.form.name).toBe('');
+    expect(result.form.search).toBe('');
+    expect(result.form.description).toBe('');
+    expect(result.form.stockType).toBe('descriptive');
+    expect(result.form.level).toBe('');
+    expect(result.form.quantity).toBe('');
+    expect(result.form.uom).toBe('');
+    expect(result.form.energy).toBe('');
+    expect(result.form.energyUnit).toBe('');
+    expect(result.form.externalSource).toBe('');
+    expect(result.form.externalId).toBe('');
+    expect(result.form.expireDays).toBe('');
+    expect(result.form.expirationDate).toBe('');
+    expect(result.form.productionDate).toBe('2026-04-10');
+  });
+
+  it('derives expiration days from date/expire_date when expiration_days is missing', () => {
+    const days = deriveLookupExpirationDays({
+      date: '2026-01-02',
+      expire_date: '2026-01-12',
+    });
+
+    expect(days).toBe(10);
+  });
+
+  it('updates location when lookup provides one', () => {
+    const lookupItem = {
+      location_initial_uuid_b64: 'loc-fridge',
+    };
+    const locations = [
+      { id: 5, uuid_b64: 'loc-fridge', name: 'Fridge' },
+    ];
+
+    const withExistingLocation = mapLookupItemToForm({
+      form: createForm({ locationId: '8' }),
+      lookupItem,
+      locations,
+    });
+    const withoutLocation = mapLookupItemToForm({
+      form: createForm({ locationId: '' }),
+      lookupItem,
+      locations,
+    });
+
+    expect(withExistingLocation.form.locationId).toBe('5');
+    expect(withExistingLocation.locationSearch).toBe('Fridge');
+    expect(withoutLocation.form.locationId).toBe('5');
+    expect(withoutLocation.locationSearch).toBe('Fridge');
+  });
+
+  it('keeps location unchanged when lookup location is null', () => {
+    const form = createForm({ locationId: '9' });
+    const result = mapLookupItemToForm({
+      form,
+      lookupItem: {
+        location_initial_uuid_b64: null,
+      },
+      locations: [{ id: 5, uuid_b64: 'loc-fridge', name: 'Fridge' }],
+    });
+
+    expect(result.form.locationId).toBe('9');
+    expect(result.locationSearch).toBeNull();
+  });
+});

tests/features/labels/upsert-submit.test.js

@@ -0,0 +1,309 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const applyItemUpsertMock = vi.fn();
+const previewItemUpsertMock = vi.fn();
+const printItemLabelMock = vi.fn();
+const LABEL_DRAFT_STORAGE_KEY = 'lonc.labels.draft';
+
+let localStorageState;
+let localStorageMock;
+
+function createWindowStorageMock(initialState = {}) {
+  const state = new Map(Object.entries(initialState));
+  const localStorage = {
+    getItem: vi.fn((key) => (state.has(key) ? state.get(key) : null)),
+    setItem: vi.fn((key, value) => {
+      state.set(key, String(value));
+    }),
+    removeItem: vi.fn((key) => {
+      state.delete(key);
+    }),
+  };
+
+  vi.stubGlobal('window', { localStorage });
+  return { state, localStorage };
+}
+
+function readStoredLabelDraft() {
+  const raw = localStorageState.get(LABEL_DRAFT_STORAGE_KEY);
+  return raw ? JSON.parse(raw) : null;
+}
+
+vi.mock('../../../src/api/stock.js', () => ({
+  applyItemUpsert: (...args) => applyItemUpsertMock(...args),
+  previewItemUpsert: (...args) => previewItemUpsertMock(...args),
+  searchItemDefinitions: vi.fn(async () => []),
+}));
+
+vi.mock('../../../src/api/labels.js', () => ({
+  previewLabel: vi.fn(async () => ({ objectUrl: 'blob:preview' })),
+  printItemLabel: (...args) => printItemLabelMock(...args),
+  formatPrintErrorMessage: (error) => error?.message || 'Printing failed.',
+}));
+
+vi.mock('../../../src/api/locations.js', () => ({
+  fetchLocations: vi.fn(async () => ({ flat: [], tree: [] })),
+}));
+
+const { labelCreatePageData } = await import('../../../src/features/labels/label-create-page.js');
+
+describe('label create upsert-first submit', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-04-12T12:00:00Z'));
+    applyItemUpsertMock.mockReset();
+    previewItemUpsertMock.mockReset();
+    printItemLabelMock.mockReset();
+
+    const storageMock = createWindowStorageMock();
+    localStorageState = storageMock.state;
+    localStorageMock = storageMock.localStorage;
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it('defaults print checkbox to enabled', () => {
+    const data = labelCreatePageData({
+      isConnected: false,
+      activeKitchen: { id: 1 },
+      addAlert: vi.fn(),
+    });
+    expect(data.printLabelOnSave).toBe(true);
+  });
+
+  it('restores a fresh enveloped draft when inactivity is below 30 minutes', () => {
+    localStorageState.set(
+      LABEL_DRAFT_STORAGE_KEY,
+      JSON.stringify({
+        form: {
+          name: 'Draft yogurt',
+          productionDate: '2026-04-11',
+          stockType: 'descriptive',
+        },
+        savedAt: Date.now() - (29 * 60 * 1000),
+      }),
+    );
+
+    const data = labelCreatePageData({
+      isConnected: false,
+      activeKitchen: { id: 1 },
+      addAlert: vi.fn(),
+    });
+
+    expect(data.form.name).toBe('Draft yogurt');
+    expect(data.form.productionDate).toBe('2026-04-11');
+    expect(data.form.stockType).toBe('descriptive');
+  });
+
+  it('drops stale enveloped drafts at 30 minutes inactivity and loads a clean form', () => {
+    localStorageState.set(
+      LABEL_DRAFT_STORAGE_KEY,
+      JSON.stringify({
+        form: {
+          name: 'Old draft',
+          description: 'Should be removed',
+          productionDate: '2026-04-10',
+          stockType: 'measured',
+          quantity: '4',
+          uom: 'kg',
+        },
+        savedAt: Date.now() - (30 * 60 * 1000),
+      }),
+    );
+
+    const data = labelCreatePageData({
+      isConnected: false,
+      activeKitchen: { id: 1 },
+      addAlert: vi.fn(),
+    });
+
+    expect(data.form.name).toBe('');
+    expect(data.form.description).toBe('');
+    expect(data.form.stockType).toBe('binary');
+    expect(data.form.quantity).toBe('');
+    expect(data.form.uom).toBe('g');
+    expect(data.form.productionDate).toBe('2026-04-12');
+  });
+
+  it('keeps draft when day changes but inactivity stays below 30 minutes', () => {
+    vi.setSystemTime(new Date('2026-04-12T00:10:00Z'));
+    localStorageState.set(
+      LABEL_DRAFT_STORAGE_KEY,
+      JSON.stringify({
+        form: {
+          name: 'Day-changed draft',
+          productionDate: '2026-04-11',
+        },
+        savedAt: Date.now() - (10 * 60 * 1000),
+      }),
+    );
+
+    const data = labelCreatePageData({
+      isConnected: false,
+      activeKitchen: { id: 1 },
+      addAlert: vi.fn(),
+    });
+
+    expect(data.form.name).toBe('Day-changed draft');
+    expect(data.form.productionDate).toBe('2026-04-11');
+  });
+
+  it('loads legacy plain-object drafts without forcing discard', () => {
+    localStorageState.set(
+      LABEL_DRAFT_STORAGE_KEY,
+      JSON.stringify({
+        name: 'Legacy draft',
+        productionDate: '2026-04-05',
+      }),
+    );
+
+    const data = labelCreatePageData({
+      isConnected: false,
+      activeKitchen: { id: 1 },
+      addAlert: vi.fn(),
+    });
+
+    expect(data.form.name).toBe('Legacy draft');
+    expect(data.form.productionDate).toBe('2026-04-05');
+  });
+
+  it('writes enveloped draft payload from persist and reset save paths', () => {
+    const data = labelCreatePageData({
+      isConnected: false,
+      activeKitchen: { id: 1 },
+      addAlert: vi.fn(),
+    });
+
+    data.form = {
+      ...data.form,
+      name: 'Persisted entry',
+      search: 'temp search value',
+    };
+    data.persistDraft();
+
+    const persistedDraft = readStoredLabelDraft();
+    expect(persistedDraft.savedAt).toBe(Date.now());
+    expect(persistedDraft.form.name).toBe('Persisted entry');
+    expect(persistedDraft.form.search).toBe('');
+
+    vi.setSystemTime(new Date('2026-04-12T12:05:00Z'));
+    data.form.name = 'Reset me';
+    data.$refs = {};
+    data.reset(false);
+
+    const resetDraft = readStoredLabelDraft();
+    expect(resetDraft.savedAt).toBe(Date.now());
+    expect(resetDraft.form.name).toBe('');
+    expect(resetDraft.form.productionDate).toBe('2026-04-12');
+  });
+
+  it('builds upsert payload with selected template uuid', () => {
+    const store = {
+      isConnected: false,
+      activeKitchen: { id: 7 },
+      addAlert: vi.fn(),
+    };
+    const data = labelCreatePageData(store);
+    data.form = {
+      ...data.form,
+      itemUuidB64: 'uuid-template-1',
+      name: 'Beans',
+      description: 'Dry beans',
+      stockType: 'measured',
+      quantity: '2',
+      uom: 'kg',
+      level: '',
+      productionDate: '2026-04-10',
+      expirationDate: '2026-08-10',
+      locationId: '',
+      identifierCode: '12345',
+    };
+
+    const payload = data.buildUpsertPayload();
+
+    expect(payload.uuid_b64).toBe('uuid-template-1');
+    expect(payload.identifier_code).toBe('12345');
+    expect(payload.item.name).toBe('Beans');
+    expect(payload.item.quantity_initial).toBe(2);
+  });
+
+  it('create uses applyItemUpsert and sets operation-aware success message', async () => {
+    applyItemUpsertMock.mockResolvedValueOnce({
+      operation: 'update',
+      item: { name: 'Rice', uuid_b64: 'uuid-rice-1' },
+    });
+    printItemLabelMock.mockResolvedValueOnce(null);
+
+    const addAlert = vi.fn();
+    const store = {
+      isConnected: false,
+      activeKitchen: { id: 3 },
+      addAlert,
+    };
+    const data = labelCreatePageData(store);
+    data.validateBeforeSubmit = () => true;
+    data.form = {
+      ...data.form,
+      name: 'Rice',
+      stockType: 'binary',
+      locationId: '',
+      productionDate: '2026-04-10',
+      itemUuidB64: 'uuid-rice-1',
+    };
+
+    await data.create();
+
+    expect(applyItemUpsertMock).toHaveBeenCalledTimes(1);
+    expect(applyItemUpsertMock.mock.calls[0][1].uuid_b64).toBe('uuid-rice-1');
+    expect(printItemLabelMock).toHaveBeenCalledWith(store, 'uuid-rice-1');
+    expect(data.successMessage).toBe('Rice was updated successfully.');
+    expect(addAlert).toHaveBeenCalledWith({
+      type: 'success',
+      message: 'Rice was updated successfully.',
+    });
+    const savedDraft = readStoredLabelDraft();
+    expect(savedDraft).toMatchObject({
+      form: {
+        name: 'Rice',
+      },
+    });
+    expect(savedDraft.savedAt).toBeTypeOf('number');
+  });
+
+  it('create shows parsed print issue warning when printing fails', async () => {
+    applyItemUpsertMock.mockResolvedValueOnce({
+      operation: 'create',
+      item: { name: 'Beans', uuid_b64: 'uuid-beans-1' },
+    });
+    printItemLabelMock.mockRejectedValueOnce(new Error('Printer is unavailable.'));
+
+    const addAlert = vi.fn();
+    const store = {
+      isConnected: false,
+      activeKitchen: { id: 3 },
+      addAlert,
+    };
+    const data = labelCreatePageData(store);
+    data.validateBeforeSubmit = () => true;
+    data.form = {
+      ...data.form,
+      name: 'Beans',
+      stockType: 'binary',
+      locationId: '',
+      productionDate: '2026-04-10',
+      itemUuidB64: '',
+    };
+
+    await data.create();
+
+    expect(data.printIssue).toBe('Beans was created, but printing failed: Printer is unavailable.');
+    expect(addAlert).toHaveBeenCalledWith({
+      type: 'warning',
+      message: 'Beans was created, but printing failed: Printer is unavailable.',
+    });
+    expect(localStorageMock.setItem).toHaveBeenCalled();
+  });
+});

tests/features/stock/mark-gone.test.js

@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const markStockGoneMock = vi.fn();
+const getStockEntryMock = vi.fn();
+const listGroupedStockEntriesMock = vi.fn();
+
+vi.mock('../../../src/api/stock.js', () => ({
+  markStockGone: (...args) => markStockGoneMock(...args),
+  getStockEntry: (...args) => getStockEntryMock(...args),
+  adjustStockEntry: vi.fn(),
+  lookupItemDetails: vi.fn(),
+  patchStockItem: vi.fn(),
+  listStockEntries: vi.fn(),
+  listGroupedStockEntries: (...args) => listGroupedStockEntriesMock(...args),
+  updateStockItem: vi.fn(),
+}));
+
+vi.mock('../../../src/api/locations.js', () => ({
+  fetchLocations: vi.fn(async () => ({ flat: [], tree: [] })),
+}));
+
+const { stockDetailPageData } = await import('../../../src/features/stock/stock-detail-page.js');
+const { stockListPageData } = await import('../../../src/features/stock/stock-list-page.js');
+
+describe('stock mark-gone behavior', () => {
+  beforeEach(() => {
+    markStockGoneMock.mockReset();
+    getStockEntryMock.mockReset();
+    listGroupedStockEntriesMock.mockReset();
+    globalThis.window = {
+      __loncApp: {
+        navigate: vi.fn(),
+      },
+    };
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete globalThis.window;
+  });
+
+  it('stock detail markGone posts gone event and shows info for already gone', async () => {
+    markStockGoneMock.mockResolvedValueOnce({ status: 'already_gone' });
+    const addAlert = vi.fn();
+    const data = stockDetailPageData({ addAlert });
+    data.entry = { uuid_b64: 'item-1', name: 'Rice' };
+
+    await data.markGone();
+
+    expect(markStockGoneMock).toHaveBeenCalledWith({ addAlert }, 'item-1', 'consumed');
+    expect(addAlert).toHaveBeenCalledWith({
+      type: 'info',
+      message: 'Rice was already out of stock.',
+    });
+    expect(globalThis.window.__loncApp.navigate).toHaveBeenCalledWith('/stock');
+  });
+
+  it('stock list markGone removes entry and posts gone event', async () => {
+    markStockGoneMock.mockResolvedValueOnce({ status: 'ok' });
+    const addAlert = vi.fn();
+    const data = stockListPageData({ addAlert, isConnected: false });
+    data.entries = [{ id: 1, uuid_b64: 'item-1', name: 'Flour' }];
+    data.editForms = { 1: { level: 'plenty', quantity: 1 } };
+    data.editErrors = {};
+
+    await data.markGone(data.entries[0]);
+
+    expect(markStockGoneMock).toHaveBeenCalledWith({ addAlert, isConnected: false }, 'item-1', 'consumed');
+    expect(data.entries).toEqual([]);
+    expect(addAlert).toHaveBeenCalledWith({
+      type: 'success',
+      message: 'Flour was marked used and removed from the list.',
+    });
+  });
+
+  it('stock list grouped markGone removes item from grouped and flat collections', async () => {
+    markStockGoneMock.mockResolvedValueOnce({ status: 'ok' });
+    listGroupedStockEntriesMock.mockResolvedValueOnce([]);
+    const addAlert = vi.fn();
+    const store = { addAlert, isConnected: true };
+    const data = stockListPageData(store);
+    data.groupedLoaded = true;
+
+    data.groupedEntries = [
+      {
+        id: 10,
+        uuid_b64: 'group-10',
+        name: 'Beans',
+        stock_type: 'measured',
+        location_initial_uuid_b64: null,
+        date: '2026-04-12',
+        expire_date: '2026-04-20',
+        items: [
+          {
+            id: 11,
+            uuid_b64: 'item-11',
+            name: 'Beans',
+            stock_type: 'measured',
+            quantity: 1,
+            location_initial_uuid_b64: null,
+            date: '2026-04-12',
+            expire_date: '2026-04-20',
+          },
+        ],
+      },
+    ].map((group) => data.indexGroup(group));
+    data.entries = [
+      data.indexEntry({
+        id: 11,
+        uuid_b64: 'item-11',
+        name: 'Beans',
+        stock_type: 'measured',
+        quantity: 1,
+        location_initial_uuid_b64: null,
+        date: '2026-04-12',
+        expire_date: '2026-04-20',
+      }),
+    ];
+    data.entriesVersion = 1;
+    data.groupedVersion = 1;
+    data.editForms = { 11: { level: 'plenty', quantity: 1 } };
+    data.editErrors = {};
+
+    await data.markGoneFromGroup(data.groupedEntries[0].items[0], data.groupedEntries[0]);
+
+    expect(data.entries).toEqual([]);
+    expect(data.groupedEntries).toEqual([]);
+    expect(addAlert).toHaveBeenCalledWith({
+      type: 'success',
+      message: 'Beans was marked used and removed from the group.',
+    });
+    expect(listGroupedStockEntriesMock).toHaveBeenCalledTimes(1);
+    expect(listGroupedStockEntriesMock).toHaveBeenCalledWith(store, { expanded: false });
+  });
+});

tests/features/stock/off-lookup-and-identifier.test.js

@@ -0,0 +1,127 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const lookupItemDetailsMock = vi.fn();
+const patchStockItemMock = vi.fn();
+const getStockEntryMock = vi.fn();
+
+vi.mock('../../../src/api/stock.js', () => ({
+  adjustStockEntry: vi.fn(),
+  getStockEntry: (...args) => getStockEntryMock(...args),
+  lookupItemDetails: (...args) => lookupItemDetailsMock(...args),
+  patchStockItem: (...args) => patchStockItemMock(...args),
+  useStockItem: vi.fn(),
+}));
+
+vi.mock('../../../src/api/labels.js', () => ({
+  printItemLabel: vi.fn(),
+  formatPrintErrorMessage: (error) => error?.message || 'Printing failed.',
+}));
+
+vi.mock('../../../src/api/locations.js', () => ({
+  fetchLocations: vi.fn(async () => ({ flat: [], tree: [] })),
+}));
+
+const { stockDetailPageData } = await import('../../../src/features/stock/stock-detail-page.js');
+
+describe('stock detail identifier and OFF lookup', () => {
+  beforeEach(() => {
+    lookupItemDetailsMock.mockReset();
+    patchStockItemMock.mockReset();
+    getStockEntryMock.mockReset();
+    globalThis.window = {
+      __loncApp: {
+        navigate: vi.fn(),
+      },
+    };
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete globalThis.window;
+  });
+
+  it('saves normalized identifier code via PATCH', async () => {
+    patchStockItemMock.mockResolvedValueOnce({
+      uuid_b64: 'item-1',
+      name: 'Milk',
+      identifier_code: '3830012345678',
+    });
+
+    const addAlert = vi.fn();
+    const store = { addAlert, isConnected: false };
+    const data = stockDetailPageData(store);
+    data.entry = { uuid_b64: 'item-1', name: 'Milk', identifier_code: '' };
+    data.identifierDraft = ' 3830 0123 45678 ';
+
+    await data.saveIdentifierCode();
+
+    expect(patchStockItemMock).toHaveBeenCalledWith(store, 'item-1', {
+      identifier_code: '3830012345678',
+    });
+    expect(data.identifierDraft).toBe('3830012345678');
+    expect(addAlert).toHaveBeenCalledWith({
+      type: 'success',
+      message: 'Identifier code saved for Milk.',
+    });
+  });
+
+  it('refreshes OFF details and surfaces stale-cache metadata', async () => {
+    lookupItemDetailsMock.mockResolvedValueOnce({
+      status: 'ok',
+      update: false,
+      updatedFields: ['name', 'nutrition_facts'],
+      staleCache: true,
+      offPayloadFetchedAt: '2026-04-11T09:00:00Z',
+      item: {
+        uuid_b64: 'item-1',
+        name: 'Milk',
+        identifier_code: '3830012345678',
+      },
+    });
+
+    const addAlert = vi.fn();
+    const store = { addAlert, isConnected: false };
+    const data = stockDetailPageData(store);
+    data.entry = { uuid_b64: 'item-1', name: 'Milk', identifier_code: '3830012345678' };
+    data.identifierDraft = '3830012345678';
+
+    await data.runItemLookup(false);
+
+    expect(lookupItemDetailsMock).toHaveBeenCalledWith(store, 'item-1', { update: false });
+    expect(data.offLookupFeedback.type).toBe('success');
+    expect(data.offLookupFeedback.message).toContain('Using stale cache data.');
+    expect(addAlert).toHaveBeenCalledWith({
+      type: 'success',
+      message: data.offLookupFeedback.message,
+    });
+  });
+
+  it('apply missing fields reloads entry after successful lookup', async () => {
+    lookupItemDetailsMock.mockResolvedValueOnce({
+      status: 'ok',
+      update: true,
+      updatedFields: ['description'],
+      staleCache: false,
+      offPayloadFetchedAt: null,
+      item: null,
+    });
+    getStockEntryMock.mockResolvedValueOnce({
+      uuid_b64: 'item-1',
+      name: 'Milk',
+      identifier_code: '3830012345678',
+      description: 'Whole milk',
+    });
+
+    const addAlert = vi.fn();
+    const store = { addAlert, isConnected: false };
+    const data = stockDetailPageData(store);
+    data.entry = { uuid_b64: 'item-1', name: 'Milk', identifier_code: '3830012345678' };
+    data.identifierDraft = '3830012345678';
+
+    await data.runItemLookup(true);
+
+    expect(getStockEntryMock).toHaveBeenCalledWith(store, 'item-1');
+    expect(data.entry.description).toBe('Whole milk');
+    expect(data.offLookupFeedback.type).toBe('success');
+  });
+});

tests/features/stock/print-label.test.js

@@ -0,0 +1,76 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const printItemLabelMock = vi.fn();
+const formatPrintErrorMessageMock = vi.fn();
+
+vi.mock('../../../src/api/labels.js', () => ({
+  printItemLabel: (...args) => printItemLabelMock(...args),
+  formatPrintErrorMessage: (...args) => formatPrintErrorMessageMock(...args),
+}));
+
+vi.mock('../../../src/api/stock.js', () => ({
+  getStockEntry: vi.fn(),
+  adjustStockEntry: vi.fn(),
+  useStockItem: vi.fn(),
+  lookupItemDetails: vi.fn(),
+  patchStockItem: vi.fn(),
+  listStockEntries: vi.fn(async () => []),
+  listGroupedStockEntries: vi.fn(async () => []),
+  updateStockItem: vi.fn(),
+}));
+
+vi.mock('../../../src/api/locations.js', () => ({
+  fetchLocations: vi.fn(async () => ({ flat: [], tree: [] })),
+}));
+
+const { stockDetailPageData } = await import('../../../src/features/stock/stock-detail-page.js');
+
+describe('stock print label actions', () => {
+  beforeEach(() => {
+    printItemLabelMock.mockReset();
+    formatPrintErrorMessageMock.mockReset();
+    globalThis.window = {
+      __loncApp: {
+        navigate: vi.fn(),
+      },
+    };
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete globalThis.window;
+  });
+
+  it('prints from stock detail and shows success alert', async () => {
+    printItemLabelMock.mockResolvedValueOnce(null);
+    const addAlert = vi.fn();
+    const store = { addAlert };
+    const data = stockDetailPageData(store);
+    data.entry = { uuid_b64: 'uuid-1', name: 'Rice' };
+
+    await data.printLabel();
+
+    expect(printItemLabelMock).toHaveBeenCalledWith(store, 'uuid-1');
+    expect(addAlert).toHaveBeenCalledWith({
+      type: 'success',
+      message: 'Rice label sent to printer.',
+    });
+  });
+
+  it('shows parsed warning when detail printing fails', async () => {
+    printItemLabelMock.mockRejectedValueOnce(new Error('boom'));
+    formatPrintErrorMessageMock.mockReturnValueOnce('Printer unavailable.');
+    const addAlert = vi.fn();
+    const store = { addAlert };
+    const data = stockDetailPageData(store);
+    data.entry = { uuid_b64: 'uuid-1', name: 'Rice' };
+
+    await data.printLabel();
+
+    expect(addAlert).toHaveBeenCalledWith({
+      type: 'warning',
+      message: 'Could not print Rice label: Printer unavailable.',
+    });
+  });
+
+});

tests/features/stock/stock-list-page-grouped.test.js

@@ -0,0 +1,443 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const listStockEntriesMock = vi.fn();
+const listGroupedStockEntriesMock = vi.fn();
+const listKitchenChangesMock = vi.fn();
+const getStockEntryMock = vi.fn();
+const updateStockItemMock = vi.fn();
+const useStockItemMock = vi.fn();
+const fetchLocationsMock = vi.fn();
+const listCategoriesMock = vi.fn();
+
+vi.mock('../../../src/api/stock.js', () => ({
+  listStockEntries: (...args) => listStockEntriesMock(...args),
+  listGroupedStockEntries: (...args) => listGroupedStockEntriesMock(...args),
+  listKitchenChanges: (...args) => listKitchenChangesMock(...args),
+  getStockEntry: (...args) => getStockEntryMock(...args),
+  updateStockItem: (...args) => updateStockItemMock(...args),
+  useStockItem: (...args) => useStockItemMock(...args),
+}));
+
+vi.mock('../../../src/api/locations.js', () => ({
+  fetchLocations: (...args) => fetchLocationsMock(...args),
+}));
+
+vi.mock('../../../src/api/categories.js', () => ({
+  listCategories: (...args) => listCategoriesMock(...args),
+}));
+
+const { stockListPageData } = await import('../../../src/features/stock/stock-list-page.js');
+
+function createGroupedSummary() {
+  return [
+    {
+      id: 10,
+      uuid_b64: 'group-10',
+      name: 'Rice',
+      description: 'Basmati',
+      stock_type: 'measured',
+      level: 'good',
+      quantity: 1,
+      uom_symbol: 'kg',
+      location_initial_uuid_b64: 'loc-root',
+      date: '2026-04-10',
+      expire_date: '2026-04-25',
+      first_expire_date: '2026-04-25',
+      first_production_date: '2026-04-10',
+      items_count: 1,
+      items: [{ id: 100 }],
+    },
+  ];
+}
+
+function createGroupedExpanded() {
+  return [
+    {
+      ...createGroupedSummary()[0],
+      items: [
+        {
+          id: 100,
+          uuid_b64: 'item-100',
+          name: 'Rice',
+          description: 'Open bag',
+          stock_type: 'measured',
+          level: 'good',
+          quantity: 1,
+          uom_symbol: 'kg',
+          location_initial_uuid_b64: 'loc-root',
+          date: '2026-04-10',
+          expire_date: '2026-04-25',
+          expire_in: 13,
+        },
+      ],
+    },
+  ];
+}
+
+function createWindowMock() {
+  const intervals = new Map();
+  let nextId = 1;
+  const storage = new Map();
+
+  return {
+    location: { hash: '#/stock' },
+    scrollY: 1,
+    setInterval: vi.fn((fn) => {
+      const id = nextId;
+      nextId += 1;
+      intervals.set(id, fn);
+      return id;
+    }),
+    clearInterval: vi.fn((id) => {
+      intervals.delete(id);
+    }),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    matchMedia: vi.fn(() => ({ matches: false })),
+    scrollTo: vi.fn(),
+    localStorage: {
+      getItem: vi.fn((key) => storage.get(key) ?? null),
+      setItem: vi.fn((key, value) => {
+        storage.set(key, value);
+      }),
+      removeItem: vi.fn((key) => {
+        storage.delete(key);
+      }),
+    },
+    __intervals: intervals,
+  };
+}
+
+describe('stock list grouped-first behavior', () => {
+  beforeEach(() => {
+    listStockEntriesMock.mockReset();
+    listGroupedStockEntriesMock.mockReset();
+    listKitchenChangesMock.mockReset();
+    getStockEntryMock.mockReset();
+    updateStockItemMock.mockReset();
+    useStockItemMock.mockReset();
+    fetchLocationsMock.mockReset();
+    listCategoriesMock.mockReset();
+    listCategoriesMock.mockResolvedValue([]);
+
+    globalThis.window = createWindowMock();
+    globalThis.requestAnimationFrame = (callback) => callback();
+    globalThis.HTMLDetailsElement = class MockDetailsElement {};
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete globalThis.window;
+    delete globalThis.requestAnimationFrame;
+    delete globalThis.HTMLDetailsElement;
+    delete globalThis.structuredClone;
+  });
+
+  it('defaults to grouped mode and loads grouped summary before lazy item list', async () => {
+    listGroupedStockEntriesMock
+      .mockResolvedValueOnce(createGroupedSummary())
+      .mockResolvedValueOnce(createGroupedExpanded());
+    listStockEntriesMock.mockResolvedValueOnce([]);
+    listKitchenChangesMock.mockResolvedValue({ since: null, nextCursor: null, changes: [] });
+    fetchLocationsMock.mockResolvedValue({ flat: [], tree: [] });
+    listCategoriesMock.mockResolvedValue([]);
+
+    const store = { isConnected: true, addAlert: vi.fn() };
+    const data = stockListPageData(store);
+    data.$nextTick = vi.fn(async () => {});
+
+    await data.init();
+
+    expect(data.viewMode).toBe('grouped');
+    expect(listGroupedStockEntriesMock).toHaveBeenNthCalledWith(1, store, { expanded: false });
+    expect(listStockEntriesMock).not.toHaveBeenCalled();
+
+    await Promise.resolve();
+
+    expect(listGroupedStockEntriesMock).toHaveBeenNthCalledWith(2, store, { expanded: true });
+
+    await data.switchView('items');
+    expect(listStockEntriesMock).toHaveBeenCalledTimes(1);
+
+    await data.switchView('grouped');
+    await data.switchView('items');
+    expect(listStockEntriesMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('hydrates grouped children in background and merges into existing groups', async () => {
+    listGroupedStockEntriesMock
+      .mockResolvedValueOnce(createGroupedSummary())
+      .mockResolvedValueOnce(createGroupedExpanded());
+
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+    await data.loadGroupedEntries({ expanded: false, resetVisible: true });
+
+    expect(data.groupDisplayItems(data.groupedEntries[0])).toEqual([]);
+    expect(data.hasGroupedChildStubs(data.groupedEntries[0])).toBe(true);
+
+    await data.hydrateGroupedEntriesInBackground();
+
+    expect(data.groupedHydrated).toBe(true);
+    expect(data.groupDisplayItems(data.groupedEntries[0])).toHaveLength(1);
+    expect(data.hasGroupedChildStubs(data.groupedEntries[0])).toBe(false);
+  });
+
+  it('preserves hydrated child details when summary refresh returns id stubs', async () => {
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+
+    data.applyGroupedSummary(createGroupedSummary());
+    data.applyGroupedHydration(createGroupedExpanded());
+
+    expect(data.groupDisplayItems(data.groupedEntries[0])).toHaveLength(1);
+
+    data.applyGroupedSummary(createGroupedSummary());
+
+    expect(data.groupDisplayItems(data.groupedEntries[0])).toHaveLength(1);
+  });
+
+  it('memoizes filtered results and invalidates when filters change', () => {
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+    data.entries = [
+      data.indexEntry({
+        id: 1,
+        uuid_b64: 'item-1',
+        name: 'Milk',
+        description: 'Fresh',
+        location_initial_uuid_b64: null,
+        stock_type: 'binary',
+        level: 'good',
+      }),
+    ];
+    data.entriesVersion = 1;
+
+    const first = data.filteredEntries;
+    const second = data.filteredEntries;
+
+    expect(second).toBe(first);
+
+    data.filters.search = 'milk';
+
+    const third = data.filteredEntries;
+    expect(third).not.toBe(first);
+    expect(third).toHaveLength(1);
+  });
+
+  it('keeps grouped data visible while background summary refresh is in progress', async () => {
+    let resolveRefresh;
+    const refreshPromise = new Promise((resolve) => {
+      resolveRefresh = resolve;
+    });
+
+    listGroupedStockEntriesMock.mockImplementationOnce(() => refreshPromise);
+
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+    data.groupedLoaded = true;
+    data.groupedEntries = createGroupedSummary().map((group) => data.indexGroup(group));
+
+    const pending = data.loadGroupedEntries({ expanded: false, background: true });
+
+    expect(data.state.isRefreshing).toBe(true);
+    expect(data.groupedEntries).toHaveLength(1);
+
+    resolveRefresh(createGroupedSummary());
+    await pending;
+
+    expect(data.state.isRefreshing).toBe(false);
+    expect(data.groupedEntries).toHaveLength(1);
+  });
+
+  it('poll refreshes view only when new changes exist', async () => {
+    listKitchenChangesMock
+      .mockResolvedValueOnce({ since: 'a', nextCursor: 'b', changes: [] })
+      .mockResolvedValueOnce({
+        since: 'b',
+        nextCursor: 'c',
+        changes: [{ type: 'stock', action: 'use', timestamp: '2026-04-12T08:00:00Z' }],
+      });
+
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+    const refreshSpy = vi.fn(async () => {});
+    data.refreshCurrentView = refreshSpy;
+
+    await data.pollKitchenChanges();
+    expect(refreshSpy).not.toHaveBeenCalled();
+
+    await data.pollKitchenChanges();
+    expect(refreshSpy).toHaveBeenCalledTimes(1);
+    expect(refreshSpy).toHaveBeenCalledWith({ background: true });
+  });
+
+  it('tracks grouped card open state from details toggle events', () => {
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+
+    class MockDetails extends HTMLDetailsElement {
+      constructor() {
+        super();
+        this.open = true;
+        this.dataset = { groupId: '10' };
+      }
+
+      querySelector() {
+        return {
+          scrollIntoView: vi.fn(),
+        };
+      }
+    }
+
+    const details = new MockDetails();
+
+    data.handleGroupedToggle({ target: details });
+    expect(data.isGroupedCardOpen(10)).toBe(true);
+
+    details.open = false;
+    data.handleGroupedToggle({ target: details });
+    expect(data.isGroupedCardOpen(10)).toBe(false);
+  });
+
+  it('restores from runtime cache on back navigation and refreshes only focused item', async () => {
+    listKitchenChangesMock.mockResolvedValue({ since: null, nextCursor: null, changes: [] });
+    getStockEntryMock.mockResolvedValueOnce({
+      id: 100,
+      uuid_b64: 'item-100',
+      name: 'Rice',
+      description: 'Open bag',
+      stock_type: 'measured',
+      level: 'good',
+      quantity: 2,
+      uom_symbol: 'kg',
+      location_initial_uuid_b64: 'loc-root',
+      date: '2026-04-12',
+      expire_date: '2026-04-20',
+      expire_in: 8,
+    });
+
+    const store = {
+      isConnected: true,
+      addAlert: vi.fn(),
+      activeKitchen: { id: 1 },
+    };
+    const firstVisit = stockListPageData(store);
+    firstVisit.entries = [
+      firstVisit.indexEntry({
+        id: 100,
+        uuid_b64: 'item-100',
+        name: 'Rice',
+        description: 'Open bag',
+        stock_type: 'measured',
+        level: 'good',
+        quantity: 1,
+        uom_symbol: 'kg',
+        location_initial_uuid_b64: 'loc-root',
+        date: '2026-04-10',
+        expire_date: '2026-04-25',
+        expire_in: 13,
+      }),
+    ];
+    firstVisit.entriesVersion = 1;
+    firstVisit.itemsLoaded = true;
+    firstVisit.groupedEntries = createGroupedExpanded().map((group) => firstVisit.indexGroup(group));
+    firstVisit.groupedVersion = 1;
+    firstVisit.groupedLoaded = true;
+    firstVisit.groupedHydrated = true;
+    firstVisit.locations = [
+      {
+        id: 1,
+        uuid_b64: 'loc-root',
+        name: 'Pantry',
+        pathLabel: 'Pantry',
+        depth: 0,
+        type: 'storage',
+        lineage_uuid_b64: ['loc-root'],
+      },
+    ];
+    firstVisit.locationsVersion = 1;
+    firstVisit.locationMap = { 'loc-root': 'Pantry' };
+    firstVisit.locationDescendants = { 'loc-root': ['loc-root'] };
+    firstVisit.locationLineage = { 'loc-root': ['loc-root'] };
+    firstVisit.viewMode = 'grouped';
+    firstVisit.filters.search = 'rice';
+    firstVisit.rememberStockListContext('item-100');
+
+    const returnVisit = stockListPageData(store);
+    returnVisit.$nextTick = vi.fn(async () => {});
+
+    await returnVisit.init();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(listGroupedStockEntriesMock).toHaveBeenNthCalledWith(1, store, { expanded: false });
+    expect(listGroupedStockEntriesMock).toHaveBeenNthCalledWith(2, store, { expanded: true });
+    expect(listStockEntriesMock).toHaveBeenCalledTimes(1);
+    expect(listStockEntriesMock).toHaveBeenCalledWith(store);
+    expect(fetchLocationsMock).not.toHaveBeenCalled();
+    expect(getStockEntryMock).toHaveBeenCalledWith(store, 'item-100');
+    expect(returnVisit.entries[0].quantity).toBe(2);
+    expect(returnVisit.groupedEntries[0].items[0].quantity).toBe(2);
+    expect(returnVisit.groupedEntries[0].quantity).toBe(2);
+    expect(returnVisit.groupedEntries[0].first_expire_date).toBe('2026-04-20');
+    expect(returnVisit.groupedEntries[0].date).toBe('2026-04-12');
+  });
+
+  it('tracks item-level refresh state while focused item refresh is in progress', async () => {
+    let resolveEntry;
+    getStockEntryMock.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveEntry = resolve;
+        }),
+    );
+
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+    data.entries = [
+      data.indexEntry({
+        id: 100,
+        uuid_b64: 'item-100',
+        name: 'Rice',
+        description: 'Open bag',
+        stock_type: 'measured',
+        level: 'good',
+        quantity: 1,
+        uom_symbol: 'kg',
+        location_initial_uuid_b64: 'loc-root',
+        date: '2026-04-10',
+        expire_date: '2026-04-25',
+      }),
+    ];
+    data.entriesVersion = 1;
+    data.itemsLoaded = true;
+
+    const pending = data.refreshFocusedItemInBackground('item-100');
+    expect(data.isItemRefreshing('item-100')).toBe(true);
+
+    resolveEntry({
+      ...data.entries[0],
+      quantity: 3,
+    });
+    await pending;
+
+    expect(data.isItemRefreshing('item-100')).toBe(false);
+    expect(data.entries[0].quantity).toBe(3);
+  });
+
+  it('falls back when structuredClone throws during runtime cache snapshot', async () => {
+    globalThis.structuredClone = vi.fn(() => {
+      throw new Error('The object can not be cloned.');
+    });
+
+    listGroupedStockEntriesMock
+      .mockResolvedValueOnce(createGroupedSummary())
+      .mockResolvedValueOnce(createGroupedExpanded());
+    listKitchenChangesMock.mockResolvedValue({ since: null, nextCursor: null, changes: [] });
+    fetchLocationsMock.mockResolvedValue({ flat: [], tree: [] });
+
+    const store = { isConnected: true, addAlert: vi.fn() };
+    const data = stockListPageData(store);
+    data.$nextTick = vi.fn(async () => {});
+
+    await data.init();
+    await Promise.resolve();
+
+    expect(data.state.error).toBe('');
+    expect(data.groupedEntries.length).toBeGreaterThan(0);
+  });
+});

vite.config.js

@@ -1,6 +1,32 @@
 import { defineConfig } from 'vite';
+import packageJson from './package.json';
+
+function appVersionAssetPlugin() {
+  return {
+    name: 'app-version-asset',
+    apply: 'build',
+    generateBundle() {
+      this.emitFile({
+        type: 'asset',
+        fileName: 'version.json',
+        source: JSON.stringify(
+          {
+            version: packageJson.version,
+            buildTime: new Date().toISOString(),
+          },
+          null,
+          2,
+        ),
+      });
+    },
+  };
+}
 
 export default defineConfig({
+  define: {
+    __APP_VERSION__: JSON.stringify(packageJson.version),
+  },
+  plugins: [appVersionAssetPlugin()],
   server: {
     port: 4173,
   },