tablefacts 0.1.0 → 0.3.0

package/.env.example

@@ -1,6 +1,8 @@
+# Supabase > Connect > Session pooler (this tool holds one connection and reads information_schema).
+# 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,66 @@
 # 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
+  new `--table-prefix` flag) selects the prefixed table set, so several restaurants can share one
+  Supabase database without touching each other's tables. The shipped Cluvi and picture configs now
+  set `cannario_`/`mombasa_`, so those two commands target their prefixed tables by default.
+- New safety guards before any write: the importer checks all three target tables exist, and with no
+  prefix stops when another restaurant's prefixed `_menu_categories` tables are present
+  (`--allow-unprefixed` overrides it for a single-restaurant database).
+- `replaceAll` names the exact tables it will empty and requires `--yes`; it never runs on the
+  unprefixed tables while another restaurant's tables are present. `inspect()` reports the resolved
+  tables and the row counts it would delete.
+- `--dry-run` runs the same checks and sends only `select`s (no write transaction).
+- New options `tablePrefix`, `allowUnprefixed` and `yes` on `importMenu`/`importCluvi`/
+  `importImageMenu`; new `menuTables`/`validateTablePrefix` helpers in `src/menu/lib/tables.mjs`; the
+  result's `database` now carries `tables`.
+- Docs recommend the Supabase **Session pooler** URL and explain the prefix convention; the full model,
+  checks, errors and a migration checklist are in [`docs/MENU_TABLE_PREFIX.md`](docs/MENU_TABLE_PREFIX.md).
+
+### Research (`tablefacts research`)
+
+- New key-free web-search source (DuckDuckGo Lite, with the HTML endpoint as fallback). It runs only when
+  Google Places and OpenStreetMap find no place or no website, and its candidate links (website, Instagram,
+  TripAdvisor, Maps, link-in-bio) feed the existing "sources find each other" chain, so a bare name and place
+  no longer produces an empty report.
+- Instagram is read from the public share card, the web profile API and oEmbed, and its bio/counts are filled
+  from a search-engine snippet when a surface answers without them. Requests identify honestly: no login and
+  no user-agent impersonation; a walled profile stays blocked.
+- A blocked TripAdvisor link is kept and stated at the top of the report, and its URL slug gives a name and
+  location hint without fetching the page.
+- The CLI summary separates facts discovered from sources, values only echoed from your input, and
+  low-confidence guesses. Guesses are marked "low (guess)" and left blank in `setup-answers.txt`, so setup
+  keeps the template's placeholder.
+- Similar-name runs (e.g. "Makibar" vs "Maki Bar") are noted, and `.tablefacts/research/latest.json` points at
+  the newest report; the pointer is only written in the default output layout.
+- The report leads "Ask the client" with one prioritized next question, flattens web-sourced text so it cannot
+  forge report structure, and warns when Google returns several places with the same name.
+- New shared `decodeHtml` and `instagramHandle` helpers in the research lib, reused by the website reader.
+
 ## 0.1.0
 
 First release as an npm library.

package/README.md

@@ -2,7 +2,10 @@
 
 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.
 
 Everything works two ways: as a **command line** (`tablefacts <tool>`) and as a **JavaScript library**
 (`import { research } from 'tablefacts'`). Both do the same work; the CLI is a thin layer over the functions.
@@ -13,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) ·
@@ -24,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
@@ -38,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
 
@@ -76,8 +83,8 @@ npx tablefacts photos tripadvisor --out ./photos --dry-run <restaurant-link>
 | `--no-google` | Skip Google even if `GOOGLE_PLACES_API_KEY` is set |
 | `--out <dir>` | Output folder (default `.tablefacts/research/<slug>`; relative paths are relative to the project) |
 
-Writes `report.md`, `profile.json` and `setup-answers.txt`. Details, sources and trust rules:
-[src/research/README.md](src/research/README.md).
+Writes `report.md`, `profile.json` and `setup-answers.txt`, and keeps `latest.json` next to the `<slug>` folders
+pointing at the newest run. Details, sources and trust rules: [src/research/README.md](src/research/README.md).
 
 ### `photos instagram`
 
@@ -116,12 +123,24 @@ Both share these options (and replace the menu in Supabase unless `--dry-run`):
 | --- | --- |
 | `--dry-run` | Extract and check, show what would change, write nothing |
 | `--json <file>` | Also save the extracted menu as JSON |
-| `--replace-all` | Replace the whole menu, not only the categories in this import |
+| `--table-prefix <prefix>` | This restaurant's tables in a shared database, e.g. `makibar_` (overrides the config). Required when other restaurants' tables exist |
+| `--allow-unprefixed` | Override the shared-database check and write the unprefixed `menu_*` tables, only when this restaurant owns them |
+| `--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).
@@ -143,7 +162,7 @@ environment win. [.env.example](.env.example) is the template.
 
 | Variable | Used by | Meaning |
 | --- | --- | --- |
-| `SUPABASE_DB_URL` | `menu cluvi`, `menu raw` | Postgres connection string (Supabase *Transaction pooler* URL, with the real password). **Bypasses row level security:** keep it in `.env`, never in a browser-exposed variable |
+| `SUPABASE_DB_URL` | `menu cluvi`, `menu raw` | Postgres connection string, with the real password. Use the **Session pooler** URL (Supabase dashboard > Connect > Session pooler): this tool holds one connection and reads `information_schema`, which the *Transaction pooler* is not meant for. **Bypasses row level security:** keep it in `.env`, never in a browser-exposed variable |
 | `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY` | `menu raw` | Key of the vision provider that reads the pictures |
 | `MENU_VISION_PROVIDER` | `menu raw` | Provider when `--provider` is not given: `anthropic` (default), `gemini` or `groq` |
 | `GOOGLE_PLACES_API_KEY` | `research` | Optional. Enables Google Maps (Places API (New)); without it OpenStreetMap and the web pages still work |
@@ -188,10 +207,10 @@ default output folder, browser profiles, the menu transcription cache, and where
 | `research({ name, location, country, website, instagram, tripadvisor, linktree, photos, render, google, googleKey, env, out, projectDir, log })` | Gathers public facts; writes `profile.json`, `report.md`, `setup-answers.txt`. Returns `{ profile, notes, photos, outDir, files }` | `GOOGLE_PLACES_API_KEY` is optional; `render` needs Playwright |
 | `downloadInstagram({ links, file, out, profile, pages, cdp, edgeDir, viaGoogle, browser, userDataDir, headed, dryRun, debug, projectDir, log })` | Downloads post or profile photos (give `links`, `file` or `profile`). Returns `{ saved, skipped, failed: [{ item, reason }], found? }` | Playwright |
 | `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, replaceAll, force, databaseUrl, env, projectDir, log })` | Validates a menu and writes it to Supabase. Returns `{ totals, notes, written, dryRun, database }`, `database` being `{ label, current: { categories, products, kept } }` or `null` when it was not reached | `SUPABASE_DB_URL` unless `dryRun` |
+| `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`,
@@ -227,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
@@ -255,8 +274,9 @@ folder tablefacts is installed in, so one install serves every template.
 | What | Where |
 | --- | --- |
 | `.env` | `<project>/.env`, then `<project>/data/.env` (older templates) |
-| Research output | `<project>/.tablefacts/research/<slug>/` |
+| 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) |
@@ -266,7 +286,7 @@ hosts) are read from the template's `frontend/src/content` and skipped silently
 
 ### Supabase tables
 
-`menu cluvi` and `menu raw` write to these tables, which your project must already have (the Cannario
+`menu cluvi` and `menu raw` write to three tables, which your project must already have (the Cannario
 templates ship the migration `supabase/migrations/0001_menu.sql`):
 
 | Table | Columns written |
@@ -275,9 +295,31 @@ templates ship the migration `supabase/migrations/0001_menu.sql`):
 | `public.menu_sections` | `id` (uuid), `category_id`, `name`, `sort_order` |
 | `public.menu_products` | `section_id`, `name`, `description`, `price` (numeric), `currency`, `image_url`, `recommended`, `sort_order` |
 
+**Several restaurants can share one Supabase database.** Each restaurant then keeps its own prefixed copies
+of those three tables — `cannario_menu_categories`, `cannario_menu_sections`, `cannario_menu_products`, and
+likewise `mombasa_menu_*` and `makibar_menu_*` — while the unprefixed `menu_*` tables belong to a single,
+older site. Set the restaurant's prefix in its `config.mjs` (`tablePrefix: "makibar_"`) or pass
+`--table-prefix makibar_`; the flag overrides the config. The prefix must be lowercase letters, digits and
+underscores ending in `_`, or empty.
+
+Before it writes anything, the importer **checks which menu tables exist**:
+
+- all three target tables must exist, or it stops and names the ones missing (apply the migration);
+- with **no prefix**, it lists every `public` table ending in `_menu_categories`. If another restaurant's
+  prefixed set exists, it stops with `ECONFIG` and names those tables, so an import cannot silently write
+  into the wrong site. `--allow-unprefixed` overrides that check, and is only correct when this restaurant
+  really owns the unprefixed tables.
+
 The write is **one transaction** and replaces only the categories in the import (their sections and products go
-with them), so re-running never duplicates. `--replace-all` empties the whole menu first. An import with no
-products, or with under half the products it replaces, is refused unless `--force`. Always run `--dry-run` first.
+with them), so re-running never duplicates. The run prints the resolved target tables and the row counts it
+would delete. `--replace-all` empties the whole menu and is refused without `--yes`; it also names the exact
+tables it will empty, and never runs on the unprefixed tables while another restaurant's tables are present.
+An import with no products, or with under half the products it replaces, is refused unless `--force`. Always
+run `--dry-run` first: it runs the same checks and prints what would be written without opening a write
+transaction (only `select`s are sent).
+
+The full model — prefix rules, every check, the error codes and how to migrate a restaurant to its own prefixed
+tables — is in [docs/MENU_TABLE_PREFIX.md](docs/MENU_TABLE_PREFIX.md).
 
 ## Limits
 
@@ -285,6 +327,12 @@ products, or with under half the products it replaces, is refused unless `--forc
   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.
 
@@ -302,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.1.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": {
-    "@types/node": "^24.19.1",
+    "@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

@@ -137,7 +137,10 @@
  * @typedef {object} ImportOptions
  * @property {boolean} [dryRun] Check and report, write nothing.
  * @property {string} [json] Also save the extracted menu as JSON at this path (resolved against projectDir).
- * @property {boolean} [replaceAll] Replace the whole menu, not only the categories in this import.
+ * @property {string} [tablePrefix] This restaurant's table prefix (e.g. "makibar_"); empty for the unprefixed menu_* tables. Default "": importCluvi/importImageMenu fall back to the source config's.
+ * @property {boolean} [allowUnprefixed] Write the unprefixed menu_* tables even when other restaurants' prefixed tables exist. Only for a single-restaurant database.
+ * @property {boolean} [yes] Confirm a destructive `replaceAll`, which empties the target tables.
+ * @property {boolean} [replaceAll] Replace the whole menu, not only the categories in this import. Needs `yes`.
  * @property {boolean} [force] Write even if the import has far fewer products than it replaces.
  * @property {string} [databaseUrl] Default: env.SUPABASE_DB_URL.
  * @property {Env} [env] Environment the database URL and keys are read from. Default process.env.
@@ -151,7 +154,7 @@
  * @property {string[]} notes
  * @property {boolean} written
  * @property {boolean} dryRun
- * @property {{ label: string, current: { categories: number, products: number, kept: string[] } } | null} database Null when the database was not reached.
+ * @property {{ label: string, tables: string[], current: { categories: number, products: number, kept: string[] } } | null} database Null when the database was not reached.
  */
 
 /**
@@ -161,6 +164,7 @@
 /**
  * Restaurant-specific part of the Cluvi source (src/menu/cluvi/config.mjs).
  * @typedef {object} CluviConfig
+ * @property {string} [tablePrefix] This restaurant's table prefix in a shared database (e.g. "cannario_"); empty for the unprefixed menu_* tables.
  * @property {string} [url] Any page of the restaurant's Cluvi menu.
  * @property {{ slug: string, name: string, from: string[] }[]} [categories] Cluvi main categories folded into each site category.
  * @property {Record<string, string>} [sections] Cluvi subcategory to section name.
@@ -169,11 +173,13 @@
 /**
  * Restaurant-specific part of the picture-menu source (src/menu/raw/config.mjs).
  * @typedef {object} RawConfig
+ * @property {string} [tablePrefix] This restaurant's table prefix in a shared database (e.g. "mombasa_"); empty for the unprefixed menu_* tables.
  * @property {string} [url] Page with the menu pictures, or a direct image URL.
  * @property {string} currency ISO code of the prices.
  * @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.
@@ -194,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.
  */
 
@@ -211,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:
 
@@ -22,34 +23,59 @@ await importCluvi({
 const pictures = await listMenuImages({ urls: ['https://example.com/carta'], config: { currency: 'COP' } })
 ```
 
-- **Cluvi `config`**: `{ url?, categories: [{ slug, name, from[] }], sections: { 'Cluvi subcategory': 'SECTION NAME' } }`.
-- **Picture `config`**: `{ url?, currency, thousands, decimal, scale, categories: [{ slug, name, groups: ['food' | 'drink'] }], placeIn, sections, skipSections }`. `currency` is required.
-- **Options every import takes**: `dryRun`, `json` (relative paths resolve against `projectDir`), `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, 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), `EFAILED` (invalid menu, no products, import refused without `force`), `EUSAGE` (bad `only`). `err.option` names the option; the CLI shows the flag (`--force`, `--only`) and exits `2` for `EUSAGE`, `1` otherwise.
+- **Cluvi `config`**: `{ tablePrefix?, url?, categories: [{ slug, name, from[] }], sections: { 'Cluvi subcategory': 'SECTION NAME' } }`.
+- **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), `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
 
 1. Install the package in the project (`npm install --save-dev tablefacts`); it brings `pg`. Run the commands from the project's folder.
 2. Apply the migration to your Supabase project.
-3. `cp .env.example .env` and set `SUPABASE_DB_URL` to the pooler URL from the Supabase dashboard (Connect > Transaction pooler), with the real password.
+3. `cp .env.example .env` and set `SUPABASE_DB_URL` to the pooler URL from the Supabase dashboard (Connect > **Session pooler**), with the real password. Use the Session pooler, not the Transaction pooler: the importer holds one connection and reads `information_schema`. On a shared database, also set `tablePrefix` in the source's `config.mjs` (below).
 
 `SUPABASE_DB_URL` bypasses row level security. It stays in `.env` (git-ignored). Never copy it into a browser-exposed variable (such as `NEXT_PUBLIC_*`): the site only uses the publishable key.
 
+## Shared database
+
+Several restaurants can live in one Supabase project. Each then owns prefixed tables — `cannario_menu_*`,
+`mombasa_menu_*`, `makibar_menu_*` — and the unprefixed `menu_*` tables belong to a different, older site.
+Set the restaurant's `tablePrefix` in its `config.mjs`, or pass `--table-prefix <prefix>` for one run (the
+flag wins). The prefix may be empty, or lowercase letters, digits and underscores ending in `_`.
+
+Before any write the importer:
+
+- checks all three prefixed tables exist, or stops naming the missing ones and the migration to apply;
+- with **no prefix**, lists the `public` tables ending in `_menu_categories` and, if another restaurant's set
+  is there, stops with an `ECONFIG` error that names them — rather than guessing which tables are yours.
+  `--allow-unprefixed` overrides that check only when this restaurant owns the unprefixed tables;
+- prints the resolved table names and the row counts it would delete, and refuses `--replace-all` without
+  `--yes`. A whole-menu replace never runs on the unprefixed tables while another restaurant's tables exist.
+
+`--dry-run` runs all of these checks and prints what would be written, but only sends `select`s (no `begin`).
+
+The full model — prefix rules, every check, the error codes and a migration checklist — is in
+[docs/MENU_TABLE_PREFIX.md](../../docs/MENU_TABLE_PREFIX.md).
+
 ## Run (Cluvi)
 
 ```bash
-tablefacts menu cluvi --dry-run        # extract and check, show what would change, write nothing
-tablefacts menu cluvi                     # replace the menu in Supabase
-tablefacts menu cluvi <menu-url>       # another restaurant
+tablefacts menu cluvi --dry-run                     # extract and check, show what would change, write nothing
+tablefacts menu cluvi                               # replace this restaurant's menu in Supabase
+tablefacts menu cluvi <menu-url>                    # another restaurant
+tablefacts menu cluvi --table-prefix makibar_       # override the config's table prefix for one run
+tablefacts menu cluvi --replace-all --yes           # empty this restaurant's tables first, then write
+tablefacts menu cluvi --allow-unprefixed            # the unprefixed menu_* tables (single-restaurant database only)
 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` |
 | --- | --- | --- |
@@ -64,14 +90,36 @@ tablefacts menu raw --list                 # show the pictures found; no key nee
 tablefacts menu raw --dry-run              # read the pages, show the menu and the checks, write nothing
 tablefacts menu raw --only 3,9 --dry-run   # try two pages first
 tablefacts menu raw --provider gemini --dry-run   # the same, read by Gemini
-tablefacts menu raw                           # replace the menu in Supabase
+tablefacts menu raw                           # replace this restaurant's menu in Supabase
 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)".
@@ -81,7 +129,7 @@ Edit `raw/config.mjs` first: the URL, the currency, how the menu prints prices (
 ## What it does (Cluvi)
 
 - Cluvi main category > site category, subcategory > section (name in UPPERCASE), product > product. Products keep the order Cluvi shows (its `order` field). Cluvi's "important" flag is `recommended`. Descriptions are converted from HTML to text.
-- The write is one transaction. By default only the categories in the import are replaced (their sections and products with them), so re-running never duplicates. `--replace-all` replaces the whole menu, which also removes the template's sample categories.
+- The write is one transaction. By default only the categories in the import are replaced (their sections and products with them), so re-running never duplicates. `--replace-all` empties the whole menu first, which also removes the template's sample categories; it needs `--yes` and is refused when it would empty the unprefixed tables on a shared database.
 - It refuses an import with no products, or with under half the products it replaces (`--force` overrides), so a broken extraction cannot empty the menu.
 - Photos stay on Cluvi's CDN: `image_url` holds the Cluvi URL, and your site must allow `images.cluvi.com` and `images-mini.cluvi.com` as image hosts (a template with `menuImageHosts` in `frontend/src/content/site.ts` gets a warning from the run when they are missing). If the restaurant leaves Cluvi, the photos must be re-hosted (Supabase Storage needs a different credential than the DB URL).
 

package/src/menu/cluvi/config.mjs

@@ -1,6 +1,12 @@
 // Everything restaurant-specific about the Cluvi import. Edit this file, not
 // source.mjs, when the menu is organised differently.
 export default {
+  // This restaurant's tables in a shared Supabase database: the import writes
+  // public.cannario_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: "cannario_",
+
   // Any page of the restaurant's Cluvi menu. Only the first path segment is
   // used (the supplier, here "cannario"). `tablefacts menu cluvi <url>`
   // overrides it for one run.

package/src/menu/cluvi/import.mjs

@@ -17,6 +17,8 @@ export async function fetchCluviMenu({ url, service, lang, config = defaultConfi
     menu,
     notes,
     title: `Cluvi: ${supplier.label} (id ${supplier.id}), ${fetched.service} menu in ${currency}`,
+    // The restaurant's own table set, so a shared database is never touched by accident.
+    tablePrefix: config.tablePrefix,
   };
 }
 
@@ -25,6 +27,8 @@ export async function fetchCluviMenu({ url, service, lang, config = defaultConfi
  * @param {import('../../lib/types.mjs').ImportCluviOptions} [options]
  * @returns {Promise<import('../../lib/types.mjs').ImportResult>}
  */
-export async function importCluvi({ url, service, lang, config, ...importOptions } = {}) {
-  return importMenu({ ...(await fetchCluviMenu({ url, service, lang, config })), ...importOptions });
+export async function importCluvi({ url, service, lang, config = defaultConfig, ...importOptions } = {}) {
+  const fetched = await fetchCluviMenu({ url, service, lang, config });
+  // An explicit `tablePrefix` (or the CLI's --table-prefix) wins over the config's.
+  return importMenu({ ...fetched, ...importOptions, tablePrefix: importOptions.tablePrefix ?? config.tablePrefix });
 }