@nitpicker/crawler 0.20.0 → 0.22.0

package/lib/archive/meta/types.d.ts

@@ -125,6 +125,8 @@ export interface PageDenormalizedColumns {
  *   main_content_custom_element_count: 0,
  *   scroll_height_desktop: 3200,
  *   scroll_height_mobile: 5400,
+ *   image_scan_desktop: 0,
+ *   image_scan_mobile: 1,
  * };
  */
 export interface MainContentsDenormalizedColumns {
@@ -172,6 +174,28 @@ export interface MainContentsDenormalizedColumns {
     scroll_height_desktop: number | null;
     /** `document.body.scrollHeight` at the mobile-small preset, or `null`. */
     scroll_height_mobile: number | null;
+    /**
+     * `@d-zero/beholder`'s `IMAGE_SCAN_CODE` outcome for the desktop-compact
+     * `<img>` element scan (0=ok, 1=degraded, 2=nav-unsettled, 3=frame-lost,
+     * 4=scroll-height-exceeded, 255=unknown), or `null` when not attempted
+     * (page not fully rendered, or the archive predates this column).
+     */
+    image_scan_desktop: number | null;
+    /** Same as {@link MainContentsDenormalizedColumns.image_scan_desktop}, for the mobile-small preset. */
+    image_scan_mobile: number | null;
+}
+/**
+ * Per-viewport `@d-zero/beholder` `IMAGE_SCAN_CODE` outcome, as passed into
+ * `computeMainContentsDenormalized`. Deliberately plain `number | null`
+ * rather than beholder's `ImageScanCode` type — this shape is written by
+ * `@nitpicker/crawler` independently of which `@d-zero/beholder` version is
+ * currently installed (see `compute-main-contents-denormalized.ts`).
+ */
+export interface ImageScanColumns {
+    /** Outcome for the desktop-compact viewport, or `null` when not attempted. */
+    desktop: number | null;
+    /** Outcome for the mobile-small viewport, or `null` when not attempted. */
+    mobile: number | null;
 }
 /**
  * One row in the `page_main_content_headings` table.

package/lib/archive/migrate-content-items-is-metadata-only.d.ts

@@ -0,0 +1,44 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `content_items.is_metadata_only` column to archives created
+ * before this feature.
+ *
+ * `content_items` is provisioned via a bare `CREATE TABLE IF NOT EXISTS` in
+ * {@link import('./create-entity-tables.js').createEntityTables}, which
+ * self-heals a *missing table* on every `initSchema` call but is a no-op
+ * against an *existing* table — adding a column to the DDL string never
+ * reaches an archive whose `content_items` predates this change. This
+ * mirrors {@link import('./migrate-content-items-dedupe-cap-event-id.js').migrateContentItemsDedupeCapEventId}'s
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * Unlike that migration, this column is `NOT NULL DEFAULT 0` (not nullable):
+ * SQLite requires a `DEFAULT` on `ALTER TABLE ... ADD COLUMN ... NOT NULL`,
+ * and the fresh-archive DDL carries the same `DEFAULT 0` so both paths stay
+ * bit-for-bit identical (see `createEntityTables`'s DDL comment). Existing
+ * rows backfill to `0` (not metadata-only) — a strict-pending row from
+ * before this migration was always resumed as a full-scrape target anyway
+ * (the bug this column fixes), so `0` preserves that prior behaviour rather
+ * than silently reclassifying already-crawled archives.
+ *
+ * No index: the only reader (`getCrawlingState`) already filters to
+ * `scraped = 0 AND is_external = 0` first, a small set. See
+ * `createEntityTables`'s DDL comment for the same "no speculative index"
+ * reasoning applied to `dedupe_cap_event_id`.
+ *
+ * Idempotent: adding the column is a no-op once it exists. Guards on
+ * `content_items`'s existence defensively, though by the time this runs
+ * (after `initSchema`, itself after `assertCompatibleVersion` rejects
+ * pre-0.13 archives) the table is always present.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ * @example
+ * ```ts
+ * await migrateContentItemsIsMetadataOnly(knex);
+ * ```
+ */
+export declare function migrateContentItemsIsMetadataOnly(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/archive/migrate-content-items-is-metadata-only.js

@@ -0,0 +1,60 @@
+/**
+ * Adds the `content_items.is_metadata_only` column to archives created
+ * before this feature.
+ *
+ * `content_items` is provisioned via a bare `CREATE TABLE IF NOT EXISTS` in
+ * {@link import('./create-entity-tables.js').createEntityTables}, which
+ * self-heals a *missing table* on every `initSchema` call but is a no-op
+ * against an *existing* table — adding a column to the DDL string never
+ * reaches an archive whose `content_items` predates this change. This
+ * mirrors {@link import('./migrate-content-items-dedupe-cap-event-id.js').migrateContentItemsDedupeCapEventId}'s
+ * catch-up: a `hasColumn`-guarded `ALTER TABLE` for the one column
+ * `CREATE TABLE IF NOT EXISTS` cannot retrofit.
+ *
+ * Unlike that migration, this column is `NOT NULL DEFAULT 0` (not nullable):
+ * SQLite requires a `DEFAULT` on `ALTER TABLE ... ADD COLUMN ... NOT NULL`,
+ * and the fresh-archive DDL carries the same `DEFAULT 0` so both paths stay
+ * bit-for-bit identical (see `createEntityTables`'s DDL comment). Existing
+ * rows backfill to `0` (not metadata-only) — a strict-pending row from
+ * before this migration was always resumed as a full-scrape target anyway
+ * (the bug this column fixes), so `0` preserves that prior behaviour rather
+ * than silently reclassifying already-crawled archives.
+ *
+ * No index: the only reader (`getCrawlingState`) already filters to
+ * `scraped = 0 AND is_external = 0` first, a small set. See
+ * `createEntityTables`'s DDL comment for the same "no speculative index"
+ * reasoning applied to `dedupe_cap_event_id`.
+ *
+ * Idempotent: adding the column is a no-op once it exists. Guards on
+ * `content_items`'s existence defensively, though by the time this runs
+ * (after `initSchema`, itself after `assertCompatibleVersion` rejects
+ * pre-0.13 archives) the table is always present.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ * @example
+ * ```ts
+ * await migrateContentItemsIsMetadataOnly(knex);
+ * ```
+ */
+export async function migrateContentItemsIsMetadataOnly(instance, onLog) {
+    const hasContentItems = await instance.schema.hasTable('content_items');
+    if (!hasContentItems) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('content_items', 'is_metadata_only');
+    if (!hasColumn) {
+        await instance.raw('ALTER TABLE content_items ADD COLUMN is_metadata_only INTEGER NOT NULL DEFAULT 0');
+        const message = '[migrate] content_items.is_metadata_only column added';
+        if (onLog) {
+            onLog(message);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.error(message);
+        }
+    }
+}

package/lib/archive/migrate-info-created-cwd.d.ts

@@ -0,0 +1,17 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `info.createdCwd` column to archives created before it existed.
+ * `CREATE TABLE IF NOT EXISTS` (used for `info` itself) cannot retrofit a new
+ * column onto an already-existing table, so this lightweight,
+ * `hasColumn`-guarded `ALTER TABLE` runs on every `initSchema` call —
+ * idempotent, and self-healing for archives whose provisioning crashed
+ * partway through. A stub missing this column simply falls back to
+ * `Archive.resume`'s own `process.cwd()`, same as before this column existed.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migrateInfoCreatedCwd(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/archive/migrate-info-created-cwd.js

@@ -0,0 +1,36 @@
+/**
+ * Adds the `info.createdCwd` column to archives created before it existed.
+ * `CREATE TABLE IF NOT EXISTS` (used for `info` itself) cannot retrofit a new
+ * column onto an already-existing table, so this lightweight,
+ * `hasColumn`-guarded `ALTER TABLE` runs on every `initSchema` call —
+ * idempotent, and self-healing for archives whose provisioning crashed
+ * partway through. A stub missing this column simply falls back to
+ * `Archive.resume`'s own `process.cwd()`, same as before this column existed.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migrateInfoCreatedCwd(instance, onLog) {
+    const hasInfo = await instance.schema.hasTable('info');
+    if (!hasInfo) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('info', 'createdCwd');
+    if (hasColumn) {
+        return;
+    }
+    await instance.schema.table('info', (t) => {
+        t.string('createdCwd');
+    });
+    const message = '[migrate] info.createdCwd column added';
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/archive/migrate-inventory-runs-to-list-reconcile-runs.d.ts

@@ -0,0 +1,34 @@
+import type { Knex } from 'knex';
+/**
+ * Renames the legacy `inventory_runs` table to `list_reconcile_runs` for
+ * archives created before the rename (issue #354: the old name implied
+ * `--inventory`-only despite `--recrawl` writing to the same table via the
+ * same {@link import('./db-ops/list-reconcile/record-list-reconcile-run.js').recordListReconcileRun}
+ * path).
+ *
+ * Must run BEFORE {@link import('./init-schema.js').initSchema} in the boot
+ * sequence, not alongside the other column-adding `migrate*` functions
+ * that run after it. `initSchema` unconditionally re-runs
+ * `createAdjunctTables`, which creates `list_reconcile_runs` fresh
+ * (`CREATE TABLE IF NOT EXISTS`) if it doesn't see the new name yet — so if
+ * this rename ran after `initSchema`, it would find `list_reconcile_runs`
+ * already present (empty) and skip, silently orphaning the old table's
+ * rows. Running first guarantees `initSchema` sees the already-renamed
+ * table and its `IF NOT EXISTS` guard is a no-op.
+ *
+ * A straight `renameTable` (not the convert-then-drop pattern used for
+ * `page_tags` → `technology_signals`/`page_technologies`) because this is a
+ * pure name change with no data-shape change — the row shape is identical
+ * before and after.
+ *
+ * Idempotent: a no-op once `inventory_runs` is gone (either because this
+ * function already ran, or the archive was created after the rename
+ * shipped and never had the old name).
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migrateInventoryRunsToListReconcileRuns(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/archive/migrate-inventory-runs-to-list-reconcile-runs.js

@@ -0,0 +1,51 @@
+/**
+ * Renames the legacy `inventory_runs` table to `list_reconcile_runs` for
+ * archives created before the rename (issue #354: the old name implied
+ * `--inventory`-only despite `--recrawl` writing to the same table via the
+ * same {@link import('./db-ops/list-reconcile/record-list-reconcile-run.js').recordListReconcileRun}
+ * path).
+ *
+ * Must run BEFORE {@link import('./init-schema.js').initSchema} in the boot
+ * sequence, not alongside the other column-adding `migrate*` functions
+ * that run after it. `initSchema` unconditionally re-runs
+ * `createAdjunctTables`, which creates `list_reconcile_runs` fresh
+ * (`CREATE TABLE IF NOT EXISTS`) if it doesn't see the new name yet — so if
+ * this rename ran after `initSchema`, it would find `list_reconcile_runs`
+ * already present (empty) and skip, silently orphaning the old table's
+ * rows. Running first guarantees `initSchema` sees the already-renamed
+ * table and its `IF NOT EXISTS` guard is a no-op.
+ *
+ * A straight `renameTable` (not the convert-then-drop pattern used for
+ * `page_tags` → `technology_signals`/`page_technologies`) because this is a
+ * pure name change with no data-shape change — the row shape is identical
+ * before and after.
+ *
+ * Idempotent: a no-op once `inventory_runs` is gone (either because this
+ * function already ran, or the archive was created after the rename
+ * shipped and never had the old name).
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migrateInventoryRunsToListReconcileRuns(instance, onLog) {
+    const hasOldTable = await instance.schema.hasTable('inventory_runs');
+    if (!hasOldTable) {
+        return;
+    }
+    const hasNewTable = await instance.schema.hasTable('list_reconcile_runs');
+    if (hasNewTable) {
+        return;
+    }
+    await instance.schema.renameTable('inventory_runs', 'list_reconcile_runs');
+    const message = '[migrate] inventory_runs renamed to list_reconcile_runs';
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/archive/{migrate-inventory-runs-exclude-skipped.d.ts → migrate-list-reconcile-runs-exclude-skipped.d.ts}

@@ -1,11 +1,11 @@
 import type { Knex } from 'knex';
 /**
- * Adds the `inventory_runs.exclude_skipped` column to archives created
- * before it existed. `CREATE TABLE IF NOT EXISTS` (used for `inventory_runs`
- * itself) cannot retrofit a new column onto an already-existing table, so
- * this lightweight, `hasColumn`-guarded `ALTER TABLE` runs on every
- * `initSchema` call — idempotent, and self-healing for archives whose
- * provisioning crashed partway through.
+ * Adds the `list_reconcile_runs.exclude_skipped` column to archives created
+ * before it existed. `CREATE TABLE IF NOT EXISTS` (used for
+ * `list_reconcile_runs` itself) cannot retrofit a new column onto an
+ * already-existing table, so this lightweight, `hasColumn`-guarded
+ * `ALTER TABLE` runs on every `initSchema` call — idempotent, and
+ * self-healing for archives whose provisioning crashed partway through.
  *
  * Pre-migration rows stay `NULL`: those runs predate ingestion-side
  * exclusion (issue #260), so their excluded URLs were imported as real
@@ -13,7 +13,7 @@ import type { Knex } from 'knex';
  * measured", not `0`.
  *
  * The column is pure audit output: written once per run and read back
- * only by `listInventoryRuns` display surfaces, never consumed by any
+ * only by `listReconcileRuns` display surfaces, never consumed by any
  * runtime decision — matching `scope_skipped` / `invalid_skipped`.
  * @param instance - The Knex query builder instance connected to the database.
  * @param onLog - Called instead of `console.error` when this migration
@@ -22,4 +22,4 @@ import type { Knex } from 'knex';
  *   `Archive.open`, corrupting its cursor tracking). Falls back to
  *   `console.error` when omitted (direct/test callers).
  */
-export declare function migrateInventoryRunsExcludeSkipped(instance: Knex, onLog?: (message: string) => void): Promise<void>;
+export declare function migrateListReconcileRunsExcludeSkipped(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/archive/{migrate-inventory-runs-exclude-skipped.js → migrate-list-reconcile-runs-exclude-skipped.js}

@@ -1,10 +1,10 @@
 /**
- * Adds the `inventory_runs.exclude_skipped` column to archives created
- * before it existed. `CREATE TABLE IF NOT EXISTS` (used for `inventory_runs`
- * itself) cannot retrofit a new column onto an already-existing table, so
- * this lightweight, `hasColumn`-guarded `ALTER TABLE` runs on every
- * `initSchema` call — idempotent, and self-healing for archives whose
- * provisioning crashed partway through.
+ * Adds the `list_reconcile_runs.exclude_skipped` column to archives created
+ * before it existed. `CREATE TABLE IF NOT EXISTS` (used for
+ * `list_reconcile_runs` itself) cannot retrofit a new column onto an
+ * already-existing table, so this lightweight, `hasColumn`-guarded
+ * `ALTER TABLE` runs on every `initSchema` call — idempotent, and
+ * self-healing for archives whose provisioning crashed partway through.
  *
  * Pre-migration rows stay `NULL`: those runs predate ingestion-side
  * exclusion (issue #260), so their excluded URLs were imported as real
@@ -12,7 +12,7 @@
  * measured", not `0`.
  *
  * The column is pure audit output: written once per run and read back
- * only by `listInventoryRuns` display surfaces, never consumed by any
+ * only by `listReconcileRuns` display surfaces, never consumed by any
  * runtime decision — matching `scope_skipped` / `invalid_skipped`.
  * @param instance - The Knex query builder instance connected to the database.
  * @param onLog - Called instead of `console.error` when this migration
@@ -21,19 +21,19 @@
  *   `Archive.open`, corrupting its cursor tracking). Falls back to
  *   `console.error` when omitted (direct/test callers).
  */
-export async function migrateInventoryRunsExcludeSkipped(instance, onLog) {
-    const hasTable = await instance.schema.hasTable('inventory_runs');
+export async function migrateListReconcileRunsExcludeSkipped(instance, onLog) {
+    const hasTable = await instance.schema.hasTable('list_reconcile_runs');
     if (!hasTable) {
         return;
     }
-    const hasColumn = await instance.schema.hasColumn('inventory_runs', 'exclude_skipped');
+    const hasColumn = await instance.schema.hasColumn('list_reconcile_runs', 'exclude_skipped');
     if (hasColumn) {
         return;
     }
-    await instance.schema.table('inventory_runs', (t) => {
+    await instance.schema.table('list_reconcile_runs', (t) => {
         t.integer('exclude_skipped');
     });
-    const message = '[migrate] inventory_runs.exclude_skipped column added';
+    const message = '[migrate] list_reconcile_runs.exclude_skipped column added';
     if (onLog) {
         onLog(message);
     }

package/lib/archive/migrate-list-reconcile-runs-invalid-skipped.d.ts

@@ -0,0 +1,16 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `list_reconcile_runs.invalid_skipped` column to archives created
+ * before it existed. `CREATE TABLE IF NOT EXISTS` (used for
+ * `list_reconcile_runs` itself) cannot retrofit a new column onto an
+ * already-existing table, so this lightweight, `hasColumn`-guarded
+ * `ALTER TABLE` runs on every `initSchema` call — idempotent, and
+ * self-healing for archives whose provisioning crashed partway through.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migrateListReconcileRunsInvalidSkipped(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/archive/migrate-list-reconcile-runs-invalid-skipped.js

@@ -0,0 +1,35 @@
+/**
+ * Adds the `list_reconcile_runs.invalid_skipped` column to archives created
+ * before it existed. `CREATE TABLE IF NOT EXISTS` (used for
+ * `list_reconcile_runs` itself) cannot retrofit a new column onto an
+ * already-existing table, so this lightweight, `hasColumn`-guarded
+ * `ALTER TABLE` runs on every `initSchema` call — idempotent, and
+ * self-healing for archives whose provisioning crashed partway through.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migrateListReconcileRunsInvalidSkipped(instance, onLog) {
+    const hasTable = await instance.schema.hasTable('list_reconcile_runs');
+    if (!hasTable) {
+        return;
+    }
+    const hasColumn = await instance.schema.hasColumn('list_reconcile_runs', 'invalid_skipped');
+    if (hasColumn) {
+        return;
+    }
+    await instance.schema.table('list_reconcile_runs', (t) => {
+        t.integer('invalid_skipped');
+    });
+    const message = '[migrate] list_reconcile_runs.invalid_skipped column added';
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/archive/migrate-page-meta-image-scan.d.ts

@@ -0,0 +1,27 @@
+import type { Knex } from 'knex';
+/**
+ * Adds the `page_meta.image_scan_desktop` / `page_meta.image_scan_mobile`
+ * columns to archives created before this feature.
+ *
+ * `page_meta` is provisioned via a bare `CREATE TABLE IF NOT EXISTS` in
+ * {@link import('./create-entity-tables.js').createEntityTables}, which
+ * self-heals a *missing table* on every `initSchema` call but is a no-op
+ * against an *existing* table — adding a column to the DDL string never
+ * reaches an archive whose `page_meta` predates this change. Same catch-up
+ * shape as {@link import('./migrate-page-meta-console-error-count.js').migratePageMetaConsoleErrorCount}.
+ *
+ * Both columns are added in the same migration since they are always
+ * written together (one `@d-zero/beholder` `imageScan` result per page).
+ * There is no backfill: a page that has never been re-scraped since this
+ * feature shipped has no recorded outcome, so `NULL` (not attempted) is
+ * already the correct value.
+ *
+ * Idempotent: adding a column that already exists is a no-op.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export declare function migratePageMetaImageScan(instance: Knex, onLog?: (message: string) => void): Promise<void>;

package/lib/archive/migrate-page-meta-image-scan.js

@@ -0,0 +1,52 @@
+/**
+ * Adds the `page_meta.image_scan_desktop` / `page_meta.image_scan_mobile`
+ * columns to archives created before this feature.
+ *
+ * `page_meta` is provisioned via a bare `CREATE TABLE IF NOT EXISTS` in
+ * {@link import('./create-entity-tables.js').createEntityTables}, which
+ * self-heals a *missing table* on every `initSchema` call but is a no-op
+ * against an *existing* table — adding a column to the DDL string never
+ * reaches an archive whose `page_meta` predates this change. Same catch-up
+ * shape as {@link import('./migrate-page-meta-console-error-count.js').migratePageMetaConsoleErrorCount}.
+ *
+ * Both columns are added in the same migration since they are always
+ * written together (one `@d-zero/beholder` `imageScan` result per page).
+ * There is no backfill: a page that has never been re-scraped since this
+ * feature shipped has no recorded outcome, so `NULL` (not attempted) is
+ * already the correct value.
+ *
+ * Idempotent: adding a column that already exists is a no-op.
+ * @param instance - The Knex query builder instance connected to the database.
+ * @param onLog - Called instead of `console.error` when this migration
+ *   actually applies (issue #294: a bare `console.error` here can fire
+ *   while a `@d-zero/dealer` `Lanes`/`TaskList` display is mid-redraw during
+ *   `Archive.open`, corrupting its cursor tracking). Falls back to
+ *   `console.error` when omitted (direct/test callers).
+ */
+export async function migratePageMetaImageScan(instance, onLog) {
+    const hasPageMeta = await instance.schema.hasTable('page_meta');
+    if (!hasPageMeta) {
+        return;
+    }
+    const hasDesktopColumn = await instance.schema.hasColumn('page_meta', 'image_scan_desktop');
+    const hasMobileColumn = await instance.schema.hasColumn('page_meta', 'image_scan_mobile');
+    if (hasDesktopColumn && hasMobileColumn) {
+        return;
+    }
+    await instance.schema.table('page_meta', (t) => {
+        if (!hasDesktopColumn) {
+            t.integer('image_scan_desktop');
+        }
+        if (!hasMobileColumn) {
+            t.integer('image_scan_mobile');
+        }
+    });
+    const message = '[migrate] page_meta.image_scan_desktop/image_scan_mobile columns added';
+    if (onLog) {
+        onLog(message);
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.error(message);
+    }
+}

package/lib/archive/page.d.ts

@@ -239,6 +239,18 @@ export default class Page {
      * aggregate written at scrape time), or null.
      */
     get scrollHeightMobile(): number | null;
+    /**
+     * `@d-zero/beholder`'s `IMAGE_SCAN_CODE` outcome for the desktop-compact
+     * `<img>` element scan (denormalised aggregate written at scrape time), or
+     * null when not attempted.
+     */
+    get imageScanDesktop(): number | null;
+    /**
+     * `@d-zero/beholder`'s `IMAGE_SCAN_CODE` outcome for the mobile-small
+     * `<img>` element scan (denormalised aggregate written at scrape time), or
+     * null when not attempted.
+     */
+    get imageScanMobile(): number | null;
     /**
      * The reason this page was skipped during crawling, or null if it was not skipped.
      */

package/lib/archive/page.js

@@ -417,6 +417,22 @@ export default class Page {
     get scrollHeightMobile() {
         return this.#raw.scroll_height_mobile;
     }
+    /**
+     * `@d-zero/beholder`'s `IMAGE_SCAN_CODE` outcome for the desktop-compact
+     * `<img>` element scan (denormalised aggregate written at scrape time), or
+     * null when not attempted.
+     */
+    get imageScanDesktop() {
+        return this.#raw.image_scan_desktop;
+    }
+    /**
+     * `@d-zero/beholder`'s `IMAGE_SCAN_CODE` outcome for the mobile-small
+     * `<img>` element scan (denormalised aggregate written at scrape time), or
+     * null when not attempted.
+     */
+    get imageScanMobile() {
+        return this.#raw.image_scan_mobile;
+    }
     /**
      * The reason this page was skipped during crawling, or null if it was not skipped.
      */