tablefacts 0.1.0 → 0.3.0

package/src/menu/lib/db.mjs

@@ -1,5 +1,8 @@
 // Writes a menu (see lib/menu.mjs) into the Supabase tables of
 // supabase/migrations/0001_menu.sql over a direct Postgres connection.
+// The tables are the restaurant's own set (lib/tables.mjs): on a shared
+// database each restaurant has a `<prefix>_menu_*` set, and assertTarget()
+// refuses to guess before anything is written.
 //
 // The connection string (SUPABASE_DB_URL) is a privileged credential: it
 // bypasses row level security, which only allows public reads. It lives in
@@ -8,6 +11,7 @@
 import { randomUUID } from "node:crypto";
 import { resolveEnv } from "../../lib/env.mjs";
 import { TablefactsError } from "../../lib/errors.mjs";
+import { menuTables, validateTablePrefix } from "./tables.mjs";
 
 /** Opens the connection. `label` names the target without the credentials. */
 export async function connect(url, { env } = {}) {
@@ -15,7 +19,7 @@ export async function connect(url, { env } = {}) {
   if (!/^postgres(ql)?:\/\//i.test(url ?? "")) {
     throw new TablefactsError(
       "SUPABASE_DB_URL is not set to a postgres:// connection string.\n" +
-        "Copy .env.example to .env and paste the pooler URL from the Supabase dashboard (Connect > Transaction pooler).",
+        "Copy .env.example to .env and paste the pooler URL from the Supabase dashboard (Connect > Session pooler).",
       "ECONFIG",
     );
   }
@@ -42,31 +46,89 @@ export async function connect(url, { env } = {}) {
 }
 
 /** Says what is wrong when the migration has not been applied to this database. */
-function explain(error) {
+function explain(error, tables) {
   if (error.code === "42P01") {
-    error.message = "The menu tables do not exist. Apply supabase/migrations/0001_menu.sql to this database first.";
+    error.message = `The menu tables do not exist. Apply supabase/migrations/0001_menu.sql to this database first (expected ${Object.values(tables).join(", ")}).`;
   }
   return error;
 }
 
+/**
+ * Refuses to touch another site's tables before anything is written.
+ *
+ * Checks the three target tables exist (pointing at the migration when they do not). Then, when
+ * no prefix is set, lists the other restaurants' `<prefix>_menu_categories` tables: any of them
+ * means this database is shared, so the import stops unless the caller confirmed it targets the
+ * one unprefixed set with `allowUnprefixed`. A whole-menu `replaceAll` is refused in that case
+ * whatever the flags say, because deleting every unprefixed row could destroy another site.
+ * Only reads; returns `{ prefix, tables, others }`.
+ * @param {any} client
+ * @param {{ tablePrefix?: string, allowUnprefixed?: boolean, replaceAll?: boolean }} [options]
+ */
+export async function assertTarget(client, { tablePrefix = "", allowUnprefixed = false, replaceAll = false } = {}) {
+  const prefix = validateTablePrefix(tablePrefix);
+  const tables = menuTables(prefix);
+  const short = Object.values(tables).map((name) => name.replace(/^public\./, ""));
+
+  const { rows } = await client.query(
+    "select table_name from information_schema.tables where table_schema = 'public' and table_name = any($1::text[])",
+    [short],
+  );
+  const present = new Set(rows.map((row) => row.table_name));
+  const missing = short.filter((name) => !present.has(name));
+  if (missing.length) {
+    throw new TablefactsError(
+      `The menu tables do not exist. Apply supabase/migrations/0001_menu.sql to this database first (expected ${Object.values(tables).join(", ")}; missing ${missing.map((name) => `public.${name}`).join(", ")}).`,
+      "ECONFIG",
+    );
+  }
+
+  if (prefix) return { prefix, tables, others: [] };
+
+  // `_` is a LIKE wildcard, so the query is only a coarse filter: it can also return names such as
+  // "xmenu_categories". The endsWith check keeps only real `<prefix>_menu_categories` tables (and
+  // excludes the unprefixed "menu_categories" itself); without it a table like "xmenu_categories"
+  // would be mistaken for another restaurant's set.
+  const existing = await client.query(
+    "select table_name from information_schema.tables where table_schema = 'public' and table_name like '%_menu_categories' order by table_name",
+  );
+  const others = existing.rows.map((row) => row.table_name).filter((name) => name.endsWith("_menu_categories"));
+  if (!others.length) return { prefix, tables, others };
+
+  if (replaceAll) {
+    throw new TablefactsError(
+      `Refusing to replace the whole menu: this database has other restaurants' menu tables (${others.join(", ")}). Set \`tablePrefix\` in your config so the delete targets only this restaurant's tables.`,
+      "ECONFIG",
+    );
+  }
+  if (!allowUnprefixed) {
+    throw new TablefactsError(
+      `This database has other restaurants' menu tables (${others.join(", ")}). Set tablePrefix in your config or pass --table-prefix so the import cannot touch the wrong tables.`,
+      "ECONFIG",
+    );
+  }
+  return { prefix, tables, others };
+}
+
 /** What an import would replace: the categories it writes, or the whole menu. */
-export async function inspect(client, menu, { replaceAll = false } = {}) {
+export async function inspect(client, menu, { replaceAll = false, tablePrefix = "" } = {}) {
+  const tables = menuTables(tablePrefix);
   const slugs = replaceAll ? null : menu.map((category) => category.slug);
   try {
     const { rows } = await client.query(
       `select count(distinct c.id)::int as categories, count(p.id)::int as products
-         from public.menu_categories c
-         left join public.menu_sections s on s.category_id = c.id
-         left join public.menu_products p on p.section_id = s.id
+         from ${tables.categories} c
+         left join ${tables.sections} s on s.category_id = c.id
+         left join ${tables.products} p on p.section_id = s.id
         where $1::text[] is null or c.slug = any($1)`,
       [slugs],
     );
     const kept = slugs
-      ? (await client.query("select slug from public.menu_categories where slug <> all($1) order by sort_order", [slugs])).rows.map((row) => row.slug)
+      ? (await client.query(`select slug from ${tables.categories} where slug <> all($1) order by sort_order`, [slugs])).rows.map((row) => row.slug)
       : [];
     return { ...rows[0], kept };
   } catch (error) {
-    throw explain(error);
+    throw explain(error, tables);
   }
 }
 
@@ -75,9 +137,11 @@ export async function inspect(client, menu, { replaceAll = false } = {}) {
  * one and a failure changes nothing. By default only the categories in `menu`
  * are replaced (deleting a category cascades to its sections and products);
  * `replaceAll` empties the menu first. Ids are generated here so the rows can
- * be inserted in bulk, a column at a time.
+ * be inserted in bulk, a column at a time. `tablePrefix` is the restaurant's
+ * own table set; the delete is scoped to it, never to another site's tables.
  */
-export async function replaceMenu(client, menu, { replaceAll = false } = {}) {
+export async function replaceMenu(client, menu, { replaceAll = false, tablePrefix = "" } = {}) {
+  const tables = menuTables(tablePrefix);
   const categories = menu.map((c, i) => ({ id: randomUUID(), slug: c.slug, name: c.name, sort_order: i + 1 }));
   const sections = menu.flatMap((c, ci) =>
     c.sections.map((s, si) => ({ id: randomUUID(), category_id: categories[ci].id, name: s.name, sort_order: si + 1, products: s.products })),
@@ -88,20 +152,20 @@ export async function replaceMenu(client, menu, { replaceAll = false } = {}) {
 
   try {
     await client.query("begin");
-    if (replaceAll) await client.query("delete from public.menu_categories");
-    else await client.query("delete from public.menu_categories where slug = any($1::text[])", [column(categories, "slug")]);
+    if (replaceAll) await client.query(`delete from ${tables.categories}`);
+    else await client.query(`delete from ${tables.categories} where slug = any($1::text[])`, [column(categories, "slug")]);
 
     const inserted = [
       await client.query(
-        "insert into public.menu_categories (id, slug, name, sort_order) select * from unnest($1::uuid[], $2::text[], $3::text[], $4::int[])",
+        `insert into ${tables.categories} (id, slug, name, sort_order) select * from unnest($1::uuid[], $2::text[], $3::text[], $4::int[])`,
         ["id", "slug", "name", "sort_order"].map((key) => column(categories, key)),
       ),
       await client.query(
-        "insert into public.menu_sections (id, category_id, name, sort_order) select * from unnest($1::uuid[], $2::uuid[], $3::text[], $4::int[])",
+        `insert into ${tables.sections} (id, category_id, name, sort_order) select * from unnest($1::uuid[], $2::uuid[], $3::text[], $4::int[])`,
         ["id", "category_id", "name", "sort_order"].map((key) => column(sections, key)),
       ),
       await client.query(
-        `insert into public.menu_products (section_id, name, description, price, currency, image_url, recommended, sort_order)
+        `insert into ${tables.products} (section_id, name, description, price, currency, image_url, recommended, sort_order)
          select * from unnest($1::uuid[], $2::text[], $3::text[], $4::numeric[], $5::text[], $6::text[], $7::boolean[], $8::int[])`,
         ["section_id", "name", "description", "price", "currency", "image_url", "recommended", "sort_order"].map((key) => column(products, key)),
       ),
@@ -114,6 +178,6 @@ export async function replaceMenu(client, menu, { replaceAll = false } = {}) {
     return { categories: categories.length, sections: sections.length, products: products.length };
   } catch (error) {
     await client.query("rollback").catch(() => {});
-    throw explain(error);
+    throw explain(error, tables);
   }
 }

package/src/menu/lib/import.mjs

@@ -7,8 +7,9 @@ import { resolveEnv } from "../../lib/env.mjs";
 import { optionError, TablefactsError } from "../../lib/errors.mjs";
 import { normalizeLog } from "../../lib/log.mjs";
 import { projectRoot, resolveIn } from "../../lib/project.mjs";
-import { connect, inspect, replaceMenu } from "./db.mjs";
+import { assertTarget, connect, inspect, replaceMenu } from "./db.mjs";
 import { countMenu, validateMenu } from "./menu.mjs";
+import { validateTablePrefix } from "./tables.mjs";
 
 /** Things the site needs that this menu does not give it, read from the template's own files. */
 export async function templateHints(menu, { projectDir } = {}) {
@@ -67,6 +68,9 @@ export async function importMenu({
   json,
   replaceAll = false,
   force = false,
+  tablePrefix = "",
+  allowUnprefixed = false,
+  yes = false,
   databaseUrl,
   env,
   projectDir,
@@ -74,6 +78,8 @@ export async function importMenu({
 } = {}) {
   const log = normalizeLog(logOption);
   databaseUrl ??= resolveEnv(env).SUPABASE_DB_URL;
+  // Before anything is opened: an invalid prefix must never reach the SQL builder.
+  const prefix = validateTablePrefix(tablePrefix);
   let client;
   try {
     validateMenu(menu);
@@ -98,14 +104,25 @@ export async function importMenu({
       log("\nDry run: SUPABASE_DB_URL is not set, so the database was not checked. Nothing was written.", "warn");
       return result;
     }
+    // A whole-menu replace empties every row of the target tables: it needs an explicit confirmation.
+    if (replaceAll && !yes && !dryRun) {
+      throw optionError("yes", "`replaceAll` empties every row in the target tables and needs confirmation: pass `yes`.", "EUSAGE");
+    }
+
+    // Only the fields that are set: this keeps the default call shape unchanged for callers and tests.
+    const scope = { replaceAll: !!replaceAll, ...(prefix ? { tablePrefix: prefix } : {}) };
 
-    const scope = { replaceAll: !!replaceAll };
     let label;
     ({ client, label } = await connect(databaseUrl, { env }));
+    const target = await assertTarget(client, { tablePrefix: prefix, allowUnprefixed: !!allowUnprefixed, replaceAll: !!replaceAll });
     const current = await inspect(client, menu, scope);
-    result.database = { label, current };
+    result.database = { label, tables: Object.values(target.tables), current };
     log(`\nDatabase ${label}`);
+    log(`  Target tables: ${Object.values(target.tables).join(", ")}`);
     log(`  ${scope.replaceAll ? "Replaces the whole menu" : `Replaces the categories this import writes`}: ${current.categories} categories and ${current.products} products now, ${totals.categories} and ${totals.products} after.`);
+    if (scope.replaceAll) {
+      log(`  --replace-all will empty ${target.tables.categories}, ${target.tables.sections} and ${target.tables.products} (${current.categories} categories, ${current.products} products).`, "warn");
+    }
     if (current.kept.length) log(`  Left untouched (not part of this import): ${current.kept.join(", ")}. Use \`replaceAll\` to remove them.`, "warn");
 
     if (current.products > 0 && totals.products < current.products / 2 && !force) {

package/src/menu/lib/run.mjs

@@ -12,6 +12,12 @@ export const menuFlags = {
   provider: "--provider",
   model: "--model",
   minWidth: "--min-width",
+  imageDir: "--images <folder>",
+  imageBaseUrl: "--image-base-url <url>",
+  imageBoxes: "--image-boxes <auto|always>",
+  tablePrefix: "--table-prefix <prefix>",
+  allowUnprefixed: "--allow-unprefixed",
+  yes: "--yes",
   replaceAll: "--replace-all",
   force: "--force",
   dryRun: "--dry-run",
@@ -34,7 +40,10 @@ const commonOptions = `
 Options:
   --dry-run       extract and check, show what would change, write nothing
   --json <file>   also save the extracted menu as JSON
+  --table-prefix <prefix>  this restaurant's table prefix (e.g. makibar_); overrides the config
+  --allow-unprefixed       write the unprefixed menu_* tables on a single-restaurant database
   --replace-all   replace the whole menu, not only the categories in this import
+  --yes           confirm --replace-all (it empties the target tables)
   --force         write even if the import has far fewer products than it replaces
   -h, --help      show this help
 
@@ -54,7 +63,10 @@ export async function runImport({ usage, options = {}, fetchMenu }) {
       options: {
         "dry-run": { type: "boolean" },
         json: { type: "string" },
+        "table-prefix": { type: "string" },
+        "allow-unprefixed": { type: "boolean" },
         "replace-all": { type: "boolean" },
+        yes: { type: "boolean" },
         force: { type: "boolean" },
         help: { type: "boolean", short: "h" },
         ...options,
@@ -67,12 +79,18 @@ export async function runImport({ usage, options = {}, fetchMenu }) {
 
     loadEnv();
     const fetched = await fetchMenu({ values, positionals });
+    // `tablePrefix` is only passed when the flag is given, so it overrides the source's config
+    // instead of replacing it with undefined.
+    const overrides = values["table-prefix"] === undefined ? {} : { tablePrefix: values["table-prefix"] };
     await importMenu({
       ...fetched,
       dryRun: !!values["dry-run"],
       json: values.json,
       replaceAll: !!values["replace-all"],
       force: !!values.force,
+      allowUnprefixed: !!values["allow-unprefixed"],
+      yes: !!values.yes,
+      ...overrides,
       log: cliLog,
     });
   } catch (error) {

package/src/menu/lib/tables.mjs

@@ -0,0 +1,44 @@
+// The table names a menu import writes. Several restaurants can share one
+// Supabase database, so each restaurant's tables carry its own prefix
+// (`cannario_menu_categories`, `makibar_menu_categories`, ...). The prefix is
+// restaurant-specific and lives in the source's `config.mjs`; the CLI's
+// `--table-prefix` overrides it for one run.
+import { optionError } from "../../lib/errors.mjs";
+
+// The only prefixes accepted: empty, or lowercase letters, digits and
+// underscores ending in "_". A value that passed this allow-list is safe to
+// build the table names from; nothing else is ever put into the SQL text.
+const PREFIX = /^[a-z][a-z0-9_]*_$|^$/;
+
+/**
+ * `tablePrefix` when it is empty or a safe `<name>_` prefix (an ECONFIG error otherwise).
+ * @param {string} [tablePrefix]
+ * @returns {string}
+ */
+export function validateTablePrefix(tablePrefix) {
+  const value = tablePrefix ?? "";
+  if (!PREFIX.test(value)) {
+    throw optionError(
+      "tablePrefix",
+      `${JSON.stringify(value)} is not a valid table prefix: \`tablePrefix\` must be empty or lowercase letters, digits and underscores ending in "_", such as "makibar_".`,
+      "ECONFIG",
+    );
+  }
+  return value;
+}
+
+/**
+ * The three `public` menu tables for a prefix, e.g.
+ * `{ categories: "public.makibar_menu_categories", sections: "public.makibar_menu_sections", products: "public.makibar_menu_products" }`.
+ * The default (empty prefix) is the unprefixed `public.menu_*` set.
+ * @param {string} [tablePrefix]
+ * @returns {{ categories: string, sections: string, products: string }}
+ */
+export function menuTables(tablePrefix) {
+  const prefix = validateTablePrefix(tablePrefix);
+  return {
+    categories: `public.${prefix}menu_categories`,
+    sections: `public.${prefix}menu_sections`,
+    products: `public.${prefix}menu_products`,
+  };
+}

package/src/menu/raw/config.mjs

@@ -1,8 +1,14 @@
 // Everything restaurant-specific about the image-menu import. Edit this file,
 // not the other scripts, when the menu is organised differently.
 export default {
-  // The page that shows the menu pictures, or direct image URLs.
-  // `tablefacts menu raw <url> [<url>...]` overrides it for one run.
+  // This restaurant's tables in a shared Supabase database: the import writes
+  // public.mombasa_menu_categories / _menu_sections / _menu_products. Change
+  // it (or pass `--table-prefix`) when importing another restaurant; leave it
+  // empty only when this restaurant owns the unprefixed menu_* tables.
+  tablePrefix: "mombasa_",
+
+  // The page that shows the menu pictures, a direct image URL, or a PDF file
+  // path/URL. `tablefacts menu raw <url> [<url>...]` overrides it for one run.
   url: "https://www.mombasa.co/carta-restaurante-espanol/",
 
   // Currency of the prices, an ISO code. Colombian menus print pesos as
@@ -14,6 +20,10 @@ export default {
   // for 95.000).
   scale: 1,
 
+  // Resolution a PDF page is rendered at before its printed product photos are
+  // screenshotted (2 means twice the page's size). Only used with `--images`.
+  imageScale: 2,
+
   // Each section the model reads is tagged food or drink (or other, which is
   // left out), and goes into the category that lists its group. The site's
   // default categories are cocina and bar.

package/src/menu/raw/extract.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-// Imports a restaurant's menu from pictures of its pages into the Supabase
-// menu tables. See src/menu/README.md. Run from the project's folder:
+// Imports a restaurant's menu from pictures of its pages, or from a PDF, into
+// the Supabase menu tables. See src/menu/README.md. Run from the project's folder:
 //   tablefacts menu raw --list
 //   tablefacts menu raw --dry-run
+//   tablefacts menu raw carta.pdf --images ./photos --image-base-url https://cdn.example.com/menu/ --dry-run
 import { parseArgs } from "node:util";
 import { cliLog, menuFlags, runImport } from "../lib/run.mjs";
 import { cliMessage, exitCodeFor } from "../../lib/errors.mjs";
@@ -14,25 +15,32 @@ const providerTable = Object.entries(providers)
   .map(([name, { keyName, defaultModel }]) => `  ${name.padEnd(10)} ${keyName.padEnd(18)} ${defaultModel}`)
   .join("\n");
 
-const usage = `Usage: tablefacts menu raw [page-or-image-url...] [options]
+const usage = `Usage: tablefacts menu raw [page-or-image-url...] [pdf-file-or-url...] [options]
 
-Reads a menu that is only pictures (one image per page) by transcribing each
-page with a vision model, and replaces the menu in Supabase.
-The URLs are pages to scan for menu images, or direct image URLs
-(default: config.mjs). The key of the provider that reads the pages goes in
-.env:
+Reads a menu that is only pictures (one image per page) or a PDF, and replaces
+the menu in Supabase. A PDF page is transcribed from its text when it has one,
+and from a render of the page when it is a scan. The URLs are pages to scan for
+menu images, or direct image URLs; an argument ending in .pdf is a PDF file
+(local path) or URL. Default: config.mjs. The key of the provider that reads the
+pages goes in .env:
 
   provider   key                default model
 ${providerTable}
 
-Image menu options:
-  --list              show the pictures found and stop; nothing is read or written
+Picture and PDF options:
+  --list              show the pages found and stop; nothing is read or written
   --only <pages>      only these pages, numbered as --list shows them (e.g. 1,3-5)
   --provider <name>   who reads the pages: ${providerNames}
                       (default: MENU_VISION_PROVIDER in .env, else ${defaultProvider})
   --model <id>        model of that provider (default: see the table)
   --min-width <px>    ignore images declaring a smaller width (default: 500)
-  --refresh           read the pages again instead of using the saved transcriptions`;
+  --refresh           read the pages again instead of using the saved transcriptions
+  --images <folder>   also save the dish photos printed on a PDF page
+  --image-base-url <url>  https folder you will publish them at; fills image_url
+  --image-boxes <auto|always>  auto (default) reads the page as text and matches
+                      photos by position; always reads every page as a picture so
+                      the model boxes every dish's photo (a vision call per page)
+`;
 
 const shared = {
   "min-width": { type: "string", default: "500" },
@@ -41,10 +49,17 @@ const shared = {
 
 if (process.argv.includes("--list")) {
   try {
-    const { values, positionals } = parseArgs({ args: process.argv.slice(2), allowPositionals: true, options: { ...shared, list: { type: "boolean" }, help: { type: "boolean", short: "h" } }, strict: false });
-    const { pages, chosen } = await findPages({ urls: positionals, only: values.only, minWidth: values["min-width"] });
-    console.log(`${pages.length} images found:\n`);
-    for (const page of chosen) console.log(`  ${String(page.number).padStart(2)}  ${page.url}${page.alt ? `\n      ${page.alt.slice(0, 100)}` : ""}`);
+    const { values, positionals } = parseArgs({ args: process.argv.slice(2), allowPositionals: true, options: { ...shared, list: { type: "boolean" }, help: { type: "boolean", short: "h" }, images: { type: "string" }, "image-base-url": { type: "string" }, "image-boxes": { type: "string" } }, strict: false });
+    const { pages, chosen, close } = await findPages({ urls: positionals, only: values.only, minWidth: values["min-width"] });
+    try {
+      console.log(`${pages.length} pages found:\n`);
+      for (const page of chosen) {
+        const detail = page.kind === "pdf" ? (page.chars >= 40 ? `${page.chars} characters of text` : "scanned; read as a picture") : page.alt?.slice(0, 100) ?? "";
+        console.log(`  ${String(page.number).padStart(2)}  ${page.url}${detail ? `\n      ${detail}` : ""}`);
+      }
+    } finally {
+      await close();
+    }
   } catch (error) {
     console.error(`\n${cliMessage(error, menuFlags)}`);
     process.exitCode = exitCodeFor(error);
@@ -57,6 +72,9 @@ if (process.argv.includes("--list")) {
       provider: { type: "string" },
       model: { type: "string" },
       refresh: { type: "boolean" },
+      images: { type: "string" },
+      "image-base-url": { type: "string" },
+      "image-boxes": { type: "string" },
     },
     fetchMenu: ({ values, positionals }) =>
       fetchImageMenu({
@@ -66,6 +84,9 @@ if (process.argv.includes("--list")) {
         model: values.model,
         minWidth: values["min-width"],
         refresh: values.refresh,
+        imageDir: values.images,
+        imageBaseUrl: values["image-base-url"],
+        imageBoxes: values["image-boxes"],
         log: cliLog,
       }),
   });

package/src/menu/raw/images.mjs

@@ -0,0 +1,109 @@
+// Places the product photos found on a menu page onto the products read from it.
+//
+// Two page kinds feed this:
+//   - a digital PDF page: pdf.mjs reports where each image sits on the page
+//     (`placed` crops with a rectangle), and the product's name is found among
+//     the page's text items to pick the nearest photo;
+//   - a scanned page: the vision model was asked for each item's photo box
+//     (`direct` crops already tied to an item name).
+//
+// Matching is pure, so it is tested with made-up pages; raw/import.mjs saves the
+// crops and turns them into `image_url`s.
+import { matchKey } from "../lib/menu.mjs";
+
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** The gap between two rectangles, 0 when they touch or overlap. */
+const gap = (a, b) => {
+  const dx = Math.max(a.x0 - b.x1, b.x0 - a.x1, 0);
+  const dy = Math.max(a.y0 - b.y1, b.y0 - a.y1, 0);
+  return Math.hypot(dx, dy);
+};
+
+const listShort = (names) => names.slice(0, 6).join(", ") + (names.length > 6 ? `, and ${names.length - 6} more` : "");
+
+const textRect = (item) => ({
+  x0: item.x ?? 0,
+  y0: item.y ?? 0,
+  x1: (item.x ?? 0) + Math.abs(item.width ?? 0),
+  y1: (item.y ?? 0) + Math.abs(item.height ?? 0),
+});
+
+/**
+ * The page's text item that best matches `name`: an exact match first, then a
+ * line that contains it (preferring the shortest such line). null when no line
+ * holds the name, which happens when a heading was drawn as an outline.
+ */
+export function findNameItem(items, name) {
+  const wanted = matchKey(name);
+  if (!wanted) return null;
+  // Whole words only, so "Ana" does not match inside "Banana".
+  const bounded = new RegExp(`(^|[^\\p{L}\\p{N}])${escapeRegExp(wanted)}(?=$|[^\\p{L}\\p{N}])`, "u");
+  let best = null;
+  for (const item of items ?? []) {
+    const key = matchKey(item.str);
+    const exact = key === wanted;
+    const contains = !exact && bounded.test(key);
+    if (!exact && !contains) continue;
+    const score = exact ? -1 : key.length;
+    if (!best || score < best.score) best = { item, score };
+  }
+  return best?.item ?? null;
+}
+
+/**
+ * One crop per product, in page order. `pages` maps a page number to
+ * `{ width, items, placed, direct }` (see the file comment). A crop is used
+ * once, so a single photo between two items goes to the closer one. Returns
+ * `{ matches, notes }`; matches carry the placement and the crop it won.
+ * @param {{ page: number, name: string, box: number[] | null, products: any[] }[]} placements
+ * @param {Map<number, any>} pages
+ * @returns {{ matches: { placement: any, crop: any }[], notes: string[] }}
+ */
+export function matchPlacements(placements, pages) {
+  const notes = [];
+  const matches = [];
+  const used = new Set();
+  const ambiguous = [];
+
+  for (const placement of placements) {
+    const page = pages.get(placement.page);
+    if (!page) continue;
+    let crop = null;
+
+    // A scanned page already tied each crop to the model's item name.
+    const direct = (page.direct ?? []).filter((c) => !used.has(c.id));
+    if (direct.length) crop = direct.find((c) => matchKey(c.name) === matchKey(placement.name)) ?? null;
+
+    if (!crop && (page.placed ?? []).length) {
+      const item = findNameItem(page.items, placement.name);
+      if (item) {
+        const rect = textRect(item);
+        const limit = (page.width ?? 0) * 0.2; // a photo farther than a fifth of the page is not this item's
+        const ranked = (page.placed ?? [])
+          .filter((c) => !used.has(c.id))
+          .map((c) => ({ c, d: gap(rect, c.rect) }))
+          .sort((a, b) => a.d - b.d);
+        if (ranked.length && ranked[0].d <= limit) {
+          crop = ranked[0].c;
+          // A near tie means the same photo could belong to either item: say so.
+          if (ranked[1] && ranked[0].d > 0 && Math.abs(ranked[1].d - ranked[0].d) < (page.width ?? 0) * 0.01) {
+            ambiguous.push(`${placement.name} (page ${placement.page})`);
+          }
+        }
+      }
+    }
+
+    if (crop) {
+      used.add(crop.id);
+      matches.push({ placement, crop });
+    }
+  }
+
+  // A dish without a photo is normal; only a photo with no dish is worth saying.
+  const allCrops = [...pages.values()].flatMap((page) => [...(page.placed ?? []), ...(page.direct ?? [])]);
+  const unused = allCrops.filter((crop) => !used.has(crop.id));
+  if (unused.length) notes.push(`${unused.length} printed photo(s) could not be matched to an item and were left out.`);
+  if (ambiguous.length) notes.push(`A printed photo sat between items and may be attached to the wrong one: ${listShort(ambiguous)}.`);
+  return { matches, notes };
+}