tablefacts 0.2.0 → 0.3.0

package/.env.example

@@ -2,7 +2,7 @@
 # Bypasses row level security: keep it here, never in a browser-exposed variable.
 SUPABASE_DB_URL=SUPABASE_DB_POOLER_URL
 
-# Menus that are only pictures (tablefacts menu raw) are read by a vision model. Fill in
+# Menus that are only pictures or a PDF (tablefacts menu raw) are read by a vision model. Fill in
 # the key of the provider you use: Claude, Gemini or Groq
 ANTHROPIC_API_KEY=
 GEMINI_API_KEY=

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.3.0
+
+### Menu (`tablefacts menu raw`)
+
+- The source now reads **PDF menus** as well as pictures. An argument ending in `.pdf` is a local file
+  (resolved against the project) or an http(s) URL. A page that carries its own text is transcribed from that
+  text (a two-column layout is read column by column); a page with no text layer (a scan) is rendered and read
+  like a picture. `--list` shows which each page is. New optional dependencies: `pdfjs-dist` for reading,
+  `@napi-rs/canvas` for rendering (loaded lazily, with an `EDEPENDENCY` error naming the install command when
+  missing).
+- New options `--images <folder>` and `--image-base-url <url>` (`imageDir`, `imageBaseUrl` on
+  `importImageMenu`): the dish photos printed on a PDF page are screenshotted and saved. When the page places
+  each photo separately they are matched to the nearest printed dish name; when it does not (a flattened export,
+  vector art, a scan) the model is asked for each item's photo box instead, so photos can come from any page.
+  The new `--image-boxes auto|always` option controls this: `auto` (default) only reads a page as a picture when
+  it has no separately placed photo, while `always` reads every page as a picture so the model boxes each dish.
+  With a base URL each product's `image_url` is filled; without it the crops are saved and `image_url` stays
+  empty.
+- `findPages`, `listMenuImages` and `normalizePages` now also know about PDF pages: `listMenuImages` reports
+  `kind` and `chars`, and `normalizePages` returns `placements` (which products each item built) so photos can
+  be attached.
+
 ## 0.2.0
 
 - The menu importers no longer write hardcoded `public.menu_*` tables. A restaurant's config (or the

package/README.md

@@ -2,7 +2,7 @@
 
 Data extraction tools for restaurant sites, shared by every Cannario template. Give it a restaurant's name and
 place and it gathers the public facts; point it at an Instagram or TripAdvisor page and it downloads the photos;
-point it at a Cluvi menu (or pictures of a paper menu) and it loads the menu into Supabase.
+point it at a Cluvi menu, a PDF menu, or pictures of a paper menu and it loads the menu into Supabase.
 
 Research needs no key: Google Places and OpenStreetMap run first, and a key-free web search (DuckDuckGo) fills in
 candidate links when they find no place or no website, so a bare name and place still produces a useful report.
@@ -16,7 +16,7 @@ Everything works two ways: as a **command line** (`tablefacts <tool>`) and as a
 | Instagram photos | `tablefacts photos instagram` | `downloadInstagram()` | [src/instagram](src/instagram/README.md) |
 | TripAdvisor photos | `tablefacts photos tripadvisor` | `downloadTripadvisor()` | [src/tripadvisor](src/tripadvisor/README.md) |
 | Menu from Cluvi | `tablefacts menu cluvi` | `importCluvi()` | [src/menu](src/menu/README.md) |
-| Menu from pictures | `tablefacts menu raw` | `importImageMenu()` | [src/menu](src/menu/README.md) |
+| Menu from pictures or a PDF | `tablefacts menu raw` | `importImageMenu()` | [src/menu](src/menu/README.md) |
 
 Contents: [Requirements](#requirements) · [Install](#install) · [Quick start](#quick-start) ·
 [Command line](#command-line) · [Configuration](#configuration) · [Library](#use-it-as-a-library) ·
@@ -27,6 +27,9 @@ Contents: [Requirements](#requirements) · [Install](#install) · [Quick start](
 
 - **Node.js 24 or newer** (`engines` in `package.json`). The tools use the built-in `fetch` and `util.parseArgs`.
 - **Playwright** (optional) for the photo tools and `research --render`: `npm install --save-dev playwright`.
+- **pdfjs-dist** and **@napi-rs/canvas** (optional) for PDF menus with `tablefacts menu raw`:
+  `npm install pdfjs-dist @napi-rs/canvas`. Only reading a PDF page's text needs `pdfjs-dist`; rendering a scanned
+  page or a product photo also needs the canvas package (it comes with `@napi-rs/canvas` on Windows, macOS and Linux).
 - **Microsoft Edge on Windows** for the photo tools. They attach to a normal Edge window because the sites
   guard their pages with bot checks that automated browsers fail (see the photo tool READMEs). Starting Edge
   for you only works with Edge installed in its usual `Program Files` folder; elsewhere, start it yourself with
@@ -41,7 +44,8 @@ npx tablefacts --help
 ```
 
 Playwright is an **optional** peer dependency. Without it the photo tools and `research --render` stop with an
-`EDEPENDENCY` error that tells you to install it; everything else works.
+`EDEPENDENCY` error that tells you to install it; everything else works. `pdfjs-dist` (and `@napi-rs/canvas` for
+scans and product photos) is likewise optional and only `menu raw` with a PDF needs it.
 
 ## Quick start
 
@@ -124,10 +128,19 @@ Both share these options (and replace the menu in Supabase unless `--dry-run`):
 | `--replace-all` | Replace the whole menu, not only the categories in this import. Requires `--yes` (except with `--dry-run`) |
 | `--yes` | Confirm `--replace-all`, which empties the target tables (`<prefix>menu_categories`, `<prefix>menu_sections`, `<prefix>menu_products`) |
 | `--force` | Write even if the import has fewer than half the products it replaces |
+| `--images <folder>` | With a PDF, also save the dish photos printed on its pages |
+| `--image-base-url <url>` | https folder those photos will be published at; fills each product's `image_url` |
+| `--image-boxes <auto\|always>` | How photos are found. `auto` (default) reads the page as text and matches separately placed photos by position, using the model's boxes only when the page has none; `always` reads every page as a picture so the model boxes every dish's photo |
 
 `tablefacts menu cluvi [menu-url] [--service on_table|delivery|take_away] [--lang es]`
 
-`tablefacts menu raw [page-or-image-url...] [--list] [--only 1,3-5] [--provider anthropic|gemini|groq] [--model <id>] [--min-width 500] [--refresh]`
+`tablefacts menu raw [page-or-image-url...] [menu.pdf...] [--list] [--only 1,3-5] [--provider anthropic|gemini|groq] [--model <id>] [--min-width 500] [--refresh] [--images <folder>] [--image-base-url <url>] [--image-boxes auto|always]`
+
+For a PDF, an argument ending in `.pdf` is a local file (resolved against the project) or an http(s) URL. A page
+with text is transcribed from that text (a two-column layout is read column by column); a scanned page is rendered
+and read like a picture. `--images` also saves the printed product photos: a page that places each photo
+separately is matched by dish name, and a page that does not (a flattened export, vector art, a scan) is read as a
+picture so the model can box each dish — `--image-boxes always` does that on every page.
 
 Both read the restaurant-specific part (URL, category mapping, currency) from a `config.mjs` next to the tool.
 **The shipped configs hold another restaurant's values: edit them first.** See [src/menu/README.md](src/menu/README.md).
@@ -196,8 +209,8 @@ default output folder, browser profiles, the menu transcription cache, and where
 | `downloadTripadvisor({ links, out, cdp, edgeDir, max, dryRun, debug, projectDir, log })` | Downloads a restaurant page's photos. Same result | Playwright |
 | `importMenu({ menu, notes, title, dryRun, json, tablePrefix, allowUnprefixed, replaceAll, yes, force, databaseUrl, env, projectDir, log })` | Validates a menu and writes it to Supabase. Returns `{ totals, notes, written, dryRun, database }`, `database` being `{ label, tables, current: { categories, products, kept } }` or `null` when it was not reached | `SUPABASE_DB_URL` unless `dryRun` |
 | `importCluvi({ url, service, lang, config, ...importMenu options })` | Reads a Cluvi menu, then `importMenu` | `SUPABASE_DB_URL` unless `dryRun` |
-| `importImageMenu({ urls, only, provider, model, minWidth, refresh, apiKey, config, ...importMenu options })` | Transcribes menu pictures with a vision model, then `importMenu` | A vision key (see [Configuration](#configuration)) |
-| `listMenuImages({ urls, only, minWidth, config })` | Lists the menu pictures found on pages (numbered as `--list` shows) | none |
+| `importImageMenu({ urls, only, provider, model, minWidth, refresh, imageDir, imageBaseUrl, imageBoxes, apiKey, config, ...importMenu options })` | Transcribes menu pictures or a PDF with a model, then `importMenu`. A PDF page uses its text when it has one, a render when it is a scan. `imageDir` also saves the printed product photos (`imageBaseUrl` fills their links; `imageBoxes` is `'auto'` or `'always'`) | A vision key (see [Configuration](#configuration)); a PDF needs `pdfjs-dist` (`@napi-rs/canvas` too for scans or photos) |
+| `listMenuImages({ urls, only, minWidth, projectDir, config })` | Lists the pages found (pictures or PDF pages, numbered as `--list` shows) | none |
 | `loadEnv({ projectDir, files, env })` | Loads `.env` files into `env` (default `process.env`); returns the files it read | none |
 
 Also exported: `validateMenu`, `countMenu`, `parsePrice`, `normalizePages`, `providers`, `defaultProvider`,
@@ -233,7 +246,7 @@ Failures the library raises on purpose throw `TablefactsError`, which has a `cod
 | --- | --- |
 | `EUSAGE` | A missing or invalid argument (no `out`, no valid links, no `name`). CLIs exit with `2` |
 | `ECONFIG` | Missing configuration: database URL, API key, unknown provider, no menu URL |
-| `EDEPENDENCY` | An optional dependency is not installed (Playwright) |
+| `EDEPENDENCY` | An optional dependency is not installed (Playwright, or `pdfjs-dist`/`@napi-rs/canvas` for a PDF menu) |
 | `EFAILED` | A source failed or was blocked, data did not validate, or an import was refused (invalid menu, no products, far fewer products than it replaces) |
 
 When the error is about one option, `err.option` names it (`'out'`, `'links'`, `'force'`...) and the message writes
@@ -263,6 +276,7 @@ folder tablefacts is installed in, so one install serves every template.
 | `.env` | `<project>/.env`, then `<project>/data/.env` (older templates) |
 | Research output | `<project>/.tablefacts/research/<slug>/`, with `latest.json` next to the folders |
 | Menu transcription cache and downloaded page images | `<project>/.tablefacts/cache/<host>/` |
+| Product photos saved from a PDF | The `--images` folder, or `<project>/.tablefacts/menu-images` |
 | Fallback browser profile | `<project>/.tablefacts/instagram-profile` |
 | Photos | The `--out` folder you give |
 | Edge profile for the photo tools | `C:\ig-edge` (`--edge-dir` changes it) |
@@ -313,6 +327,12 @@ tables — is in [docs/MENU_TABLE_PREFIX.md](docs/MENU_TABLE_PREFIX.md).
   past bot protection: a blocked source is reported, not worked around.
 - Cluvi has no public API; the importer calls the two JSON endpoints its web app uses, which can change.
 - Prices read from pictures can be wrong. Read the dry run against the original before writing.
+- A PDF page with text is read as text; a scan is rendered and read as a picture, so small print can still be
+  misread. A two-column page is read column by column when the layout is clear, but an unusual layout is
+  flattened into single lines, so check the dry run. Product photos are screenshots cropped from the page: a
+  separately placed photo is matched to the nearest dish, and when the page has none (a flattened export, or
+  vector art) the model is asked for each dish's photo box instead — pass `--image-boxes always` to do that on
+  every page too. Boxes are approximate, so check the dry run.
 - Only download photos the restaurant owns or has allowed you to use. Guest photos on TripAdvisor and
   Instagram belong to their authors.
 
@@ -330,9 +350,9 @@ and its declarations fails the tests. Document options with JSDoc in `src/lib/ty
 CI (`.github/workflows/ci.yml`) runs the tests on Ubuntu and Windows with Node 24 and checks `npm pack --dry-run`
 on every push to `main` and every pull request. Dependabot (`.github/dependabot.yml`) keeps dependencies current.
 
-**Release:** bump `version` in `package.json`, commit, then push a matching tag, e.g. `git tag v0.1.1 && git push origin v0.1.1`.
-`.github/workflows/release.yml` checks the tag equals the version, runs the tests, publishes to npm with provenance
-(needs an `NPM_TOKEN` repository secret) and creates a GitHub release with generated notes.
+**Release:** publishing is manual. Bump `version` in `package.json`, add the entry to `CHANGELOG.md`, commit, then
+run `npm publish` from a clean checkout of that commit. Publishing is not automated in CI; `prepublishOnly` builds
+`types/` and runs the tests first. Optionally tag the release commit (`git tag v0.1.1 && git push origin v0.1.1`).
 
 For how the code is organised and how to add a source or a tool, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "tablefacts",
-  "version": "0.2.0",
-  "description": "Data extraction tools for restaurant sites: public-facts research, photos (Instagram, TripAdvisor) and menu import",
+  "version": "0.3.0",
+  "description": "Data extraction tools for restaurant sites: public-facts research, photos (Instagram, TripAdvisor) and menu import from Cluvi, pictures or PDFs",
   "keywords": [
     "restaurant",
     "menu",
+    "pdf",
     "scraper",
     "tripadvisor",
     "instagram",
@@ -61,15 +62,25 @@
     "pg": "^8.23.1"
   },
   "devDependencies": {
+    "@napi-rs/canvas": "^1.0.10",
     "@types/node": "^26.6.4",
+    "pdfjs-dist": "~6.2.108",
     "playwright": "^1.63.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.3"
   },
   "peerDependencies": {
+    "@napi-rs/canvas": "^1.0.10",
+    "pdfjs-dist": "~6.2.108",
     "playwright": "^1.63.0"
   },
   "peerDependenciesMeta": {
+    "@napi-rs/canvas": {
+      "optional": true
+    },
+    "pdfjs-dist": {
+      "optional": true
+    },
     "playwright": {
       "optional": true
     }

package/src/lib/types.mjs

@@ -179,6 +179,7 @@
  * @property {string} [thousands] Thousands separator the menu prints. Default ".".
  * @property {string} [decimal] Decimal separator the menu prints. Default ",".
  * @property {number} [scale] Multiplies every price. Default 1.
+ * @property {number} [imageScale] Resolution a PDF page is rendered at before its product photos are screenshot. Default 2.
  * @property {{ slug: string, name: string, groups?: ('food' | 'drink')[] }[]} [categories] Category that lists each group.
  * @property {Record<string, string>} [placeIn] Section title to category slug.
  * @property {Record<string, string>} [sections] Section title to the name stored.
@@ -199,13 +200,16 @@
 
 /**
  * @typedef {object} ImageMenuReadOptions
- * @property {string[]} [urls] Pages or image URLs. Default: the config's url.
+ * @property {string[]} [urls] Pages or image URLs, or PDF file paths/URLs. Default: the config's url.
  * @property {string | number[]} [only] Pages to read, e.g. '1,3-5' or [1, 3, 4, 5].
  * @property {string} [provider] Vision provider, see `providers`. Default MENU_VISION_PROVIDER or `defaultProvider`.
  * @property {string} [model]
  * @property {number} [minWidth] Ignore images declaring a smaller width. Default 500.
  * @property {string} [apiKey] Default: the provider's key in env.
  * @property {boolean} [refresh] Read the pages again instead of using the saved transcriptions.
+ * @property {string} [imageDir] Also save the dish photos printed on a PDF page here (resolved against projectDir). Enables photo extraction.
+ * @property {string} [imageBaseUrl] https folder the saved photos will be published at; fills each product's image_url with it plus the file name.
+ * @property {'auto' | 'always'} [imageBoxes] How photos are found: 'auto' (default) reads a PDF page from its text and matches placed photos by position, using the model's boxes only when the page has none; 'always' reads every PDF page as a picture so the model boxes every dish's photo. Default 'auto'.
  * @property {RawConfig} [config] Default: the raw config.mjs.
  */
 
@@ -216,14 +220,17 @@
  * @property {string[]} [urls]
  * @property {string | number[]} [only]
  * @property {number} [minWidth]
+ * @property {string} [projectDir] Project folder. Default: TABLEFACTS_PROJECT or the current folder.
  * @property {RawConfig} [config]
  */
 
 /**
  * @typedef {object} MenuImage
  * @property {number} number Position as the CLI's --list numbers it.
- * @property {string} url
+ * @property {string} url The image URL, or "<pdf path or URL>#<page number>" for a PDF page.
  * @property {string} alt
+ * @property {'image' | 'pdf'} [kind] Where the page came from. Default: 'image'.
+ * @property {number} [chars] Characters of text a PDF page has (0 means it is a scan).
  */
 
 /**

package/src/menu/README.md

@@ -6,6 +6,7 @@ Scripts that read a restaurant's menu from the website that hosts it and write i
 | --- | --- | --- |
 | Cluvi (`<restaurant>.cluvi.co`) | `cluvi/` | working |
 | Menu that is only pictures (one image per page) | `raw/` | working, API calls untested |
+| Menu as a PDF (text layer or scan) | `raw/pdf.mjs` | working, optional `pdfjs-dist` |
 
 The same code is available as functions: `importCluvi`, `importImageMenu`, `listMenuImages` and `importMenu` (see the [main README](../../README.md#use-it-as-a-library)). Each source's `config.mjs` can be replaced with the `config` option, so a script can import a menu without editing the package:
 
@@ -23,10 +24,11 @@ const pictures = await listMenuImages({ urls: ['https://example.com/carta'], con
 ```
 
 - **Cluvi `config`**: `{ tablePrefix?, url?, categories: [{ slug, name, from[] }], sections: { 'Cluvi subcategory': 'SECTION NAME' } }`.
-- **Picture `config`**: `{ tablePrefix?, url?, currency, thousands, decimal, scale, categories: [{ slug, name, groups: ['food' | 'drink'] }], placeIn, sections, skipSections }`. `currency` is required.
+- **Picture `config`**: `{ tablePrefix?, url?, currency, thousands, decimal, scale, imageScale?, categories: [{ slug, name, groups: ['food' | 'drink'] }], placeIn, sections, skipSections }`. `currency` is required; `imageScale` is the PDF render resolution for product photos (default 2).
+- **Picture/PDF read options** (`importImageMenu`): `provider`, `model`, `minWidth`, `refresh`, `apiKey`, and the photo options `imageDir` (save the printed product photos), `imageBaseUrl` (fill their `image_url`) and `imageBoxes` (`'auto'` default, or `'always'`).
 - **Options every import takes**: `dryRun`, `json` (relative paths resolve against `projectDir`), `tablePrefix` (overrides the config's; the restaurant's table set on a shared database), `allowUnprefixed` (override the shared-database check and write the unprefixed `menu_*` tables, only when this restaurant owns them), `replaceAll`, `yes` (confirms a whole-menu `replaceAll`), `force`, `databaseUrl` (default `env.SUPABASE_DB_URL`), `env`, `projectDir` and `log(message, level)` (`'info'`, `'warn'` for notes, `'error'`).
 - **Result**: `{ totals, notes, written, dryRun, database }`; `database` is `{ label, tables, current: { categories, products, kept } }` once the database was inspected, and `null` when it was not reached (a dry run without a URL).
-- **Errors** are `TablefactsError`: `ECONFIG` (no URL, unknown provider, no key, bad currency, a bad `tablePrefix`, another restaurant's tables on an unprefixed import), `EFAILED` (invalid menu, no products, import refused without `force`), `EUSAGE` (bad `only`, `replaceAll` without `yes`). `err.option` names the option; the CLI shows the flag (`--force`, `--only`) and exits `2` for `EUSAGE`, `1` otherwise.
+- **Errors** are `TablefactsError`: `ECONFIG` (no URL, unknown provider, no key, bad currency, a bad `tablePrefix`, another restaurant's tables on an unprefixed import), `EDEPENDENCY` (`pdfjs-dist`/`@napi-rs/canvas` missing for a PDF), `EFAILED` (invalid menu, no products, import refused without `force`), `EUSAGE` (bad `only`, a bad `imageBoxes`, `replaceAll` without `yes`). `err.option` names the option; the CLI shows the flag (`--force`, `--only`) and exits `2` for `EUSAGE`, `1` otherwise.
 
 ## Setup
 
@@ -71,9 +73,9 @@ tablefacts menu cluvi --help
 
 Edit `cluvi/config.mjs` first: the menu URL, how Cluvi's main categories fold into the site's categories, and section renames. The run prints what the site still needs (dictionary keys, `content/qr.ts`).
 
-## Run (menu that is only pictures)
+## Run (menu that is only pictures or a PDF)
 
-For a restaurant whose site shows the menu as a gallery of page images, such as <https://www.mombasa.co/carta-restaurante-espanol/>. Each page is transcribed by a vision model from one of three providers, so it needs that provider's key in `.env`:
+For a restaurant whose site shows the menu as a gallery of page images, such as <https://www.mombasa.co/carta-restaurante-espanol/>, or that offers it as a PDF. Each page is transcribed by a model from one of three providers, so it needs that provider's key in `.env`:
 
 | `--provider` | Key in `.env` | Default `--model` |
 | --- | --- | --- |
@@ -92,12 +94,32 @@ tablefacts menu raw                           # replace this restaurant's menu i
 tablefacts menu raw <page-or-image-url>... # another restaurant
 tablefacts menu raw --table-prefix makibar_ # override the config's table prefix for one run
 tablefacts menu raw --replace-all --yes     # empty this restaurant's tables first, then write
+tablefacts menu raw carta.pdf --list        # pages of a PDF file (a .pdf URL works too)
+tablefacts menu raw carta.pdf --dry-run     # text pages from their text, scans from a render
+tablefacts menu raw carta.pdf --images ./carta-fotos --image-base-url https://cdn.example.com/carta/ --dry-run
+tablefacts menu raw carta.pdf --images ./carta-fotos --image-boxes always --dry-run
 ```
 
-Edit `raw/config.mjs` first: the URL, the currency, how the menu prints prices (`$95.000` is `thousands: "."`, `decimal: ","`) and which category each section goes to.
+A PDF argument ends in `.pdf` and is a local file or an http(s) URL. A page that carries its own text is
+transcribed from that text (cheaper and exact); a page with no text layer is rendered and read like a picture
+(`chars` in `--list` tells them apart). Rendering needs `@napi-rs/canvas`; text-only PDFs need only `pdfjs-dist`.
+
+`--images <folder>` also saves the dish photos printed on a PDF page, as PNG crops of the page render. Two ways
+the crop finds its dish: when the page places each photo separately, each is matched to the product whose printed
+name is nearest it; when it does not (a flattened export, vector art, a scan), the model is asked for each dish's
+photo box instead. That fallback reads the page as a picture, so asking for photos adds a vision call to pages
+with no separately placed photo. `--image-boxes always` reads **every** PDF page as a picture so the model boxes
+each dish even when the page also places some photos separately (one vision call per page); `auto` (the default)
+only does that when the page has no separately placed photo. `--image-base-url https://host/path/` then fills
+each product's `image_url` with that URL plus the file name, so the import can use it. Without it the photos are
+saved but `image_url` stays empty until you host them and re-run with the base URL.
+
+Edit `raw/config.mjs` first: the URL (a PDF path/URL works there too), the currency, how the menu prints prices (`$95.000` is `thousands: "."`, `decimal: ","`) and which category each section goes to.
 
 - `raw/source.mjs` takes the large JPG/PNG/WebP images of the page in document order (full size, not the thumbnails; logos and icons are skipped by width) and downloads them. A site that builds its gallery with JavaScript shows up as "no images": pass the image URLs instead.
-- `raw/vision.mjs` has the model transcribe each page into sections and dishes with one request: a forced tool call for Anthropic, JSON held to the same schema for Gemini (`generateContent`) and Groq (strict structured output), so every provider hands back the same shape. Prices come back as printed text and `raw/normalize.mjs` parses them, so a thousands separator is never guessed by the model. Adding a provider is one more entry in `providers` there.
+- `raw/pdf.mjs` reads a PDF (a local file or URL) with the optional `pdfjs-dist`: a page's text and text positions, where each printed image sits on the page, and a render of the page. A page with enough text is sent to the model as text (a two-column layout is read column by column); a scan is rendered and sent as a picture. `raw/pdfjs.mjs` loads the dependency on use and turns a missing one into an `EDEPENDENCY` error with the install command.
+- `raw/vision.mjs` has the model transcribe each page into sections and dishes with one request: a forced tool call for Anthropic, JSON held to the same schema for Gemini (`generateContent`) and Groq (strict structured output), so every provider hands back the same shape. The same providers read a PDF page's text (no picture) and can return each item's photo box. Prices come back as printed text and `raw/normalize.mjs` parses them, so a thousands separator is never guessed by the model. Adding a provider is one more entry in `providers` there.
+- `raw/images.mjs` ties a product photo to a dish: by the model's box (a scan, or a page with no separately placed photo), or by matching the dish name to the page's text and taking the nearest placed image. `raw/import.mjs` saves the crops and fills `image_url` when a base URL is given.
 - Groq serves a single vision model, `qwen/qwen3.8-27b`, and it is a preview one: if Groq retires it, pass its successor with `--model`.
 - Rate limits (HTTP 429) are retried after the wait the service asks for, up to a minute; for a longer wait the run stops with the service's message. Pages already read are saved (below), so run it again later.
 - The model tags each section food, drink or other; `config.categories` maps those to the site's categories. A section with no heading continues the one before it, even across pages. A dish with several price columns (bottle and glass) becomes one product per column, "Name (Botella)".

package/src/menu/lib/run.mjs

@@ -12,6 +12,9 @@ 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",

package/src/menu/raw/config.mjs

@@ -7,8 +7,8 @@ export default {
   // empty only when this restaurant owns the unprefixed menu_* tables.
   tablePrefix: "mombasa_",
 
-  // The page that shows the menu pictures, or direct image URLs.
-  // `tablefacts menu raw <url> [<url>...]` overrides it for one run.
+  // 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
@@ -20,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 };
+}