Coverage checks

type MarkedBlock = {
  blockType: string
  blockId?: string
  paths: string[]
  /** Paths whose marker sits on a void element — an <img>, most of the time. */
  voidPaths?: string[]
  /** The block's props, when you have them. Supply these — see below. */
  props?: Record<string, unknown>
}

type EditableCoverage = {
  expected: number
  marked: number
  gaps: BlockCoverageGap[]
  unknownBlockTypes: string[]
}

type BlockCoverageGap = {
  blockType: string
  exampleBlockId?: string
  missing: string[]              // top-level fields that draw something and carry no marker
  missingItemFields: string[]    // as "cards[].title", for a list present but under-marked
  markedOnVoidElement: string[]  // marked where no button can ever mount
  unmarkedLists: string[]        // no marked path at all — empty list, or uninstrumented
}

editable fields marked: 2/3 (67%)
  TwoColumn (e.g. b1)
    marked on a void element (no button can mount)  left[].imageUrl

type PanelCoverage = {
  rowsExamined: number   // list rows across every page
  rowsLabelled: number   // rows the panel can label from their own content
  findings: PanelFinding[]
  unknownBlockTypes: string[]
}

import { getAllBlockMeta } from "@avocadostudio-ai/site-sdk/blocks"

panelCoverage(manifest, pages, { builtinTypes: getAllBlockMeta() })

list rows the panel can label: 2/3 (67%)

colliding_type:
  TwoColumn — the editor also ships a built-in "TwoColumn" with a different shape
  (only in yours: heading; only in the built-in: variant, headingLevel, right).
  Anything your manifest does not declare explicitly is taken from the built-in.

unmatched_branch:
  TwoColumn.left[].type=quote (e.g. /pricing) — no itemFieldsByType entry for "quote",
  so this row is edited against the union of every branch

unlabelled_row:
  TwoColumn.left[].type=quote (e.g. /pricing) — the panel labels this row "Item N" …

orphan_prop:
  TwoColumn.tracking (e.g. /pricing) — held in content, described by neither fields
  nor listFields — the panel cannot show or edit it

filename_row_label:
  TwoColumn.left[].imageAlt (e.g. /pricing) — labelled by image filename because
  "imageAlt" is empty …

phantom_field:
  TwoColumn.left[].image — declared for these rows and never present in one: imageAlt, caption

import {
  extractMarkedBlocks,
  editableCoverage,
  formatEditableCoverage,
  panelCoverage,
  formatPanelCoverage,
} from "@avocadostudio-ai/site-sdk/coverage"

import type {
  MarkedBlock,
  BlockCoverageGap,
  EditableCoverage,
  PanelCoverage,
  PanelFinding,
  PanelFindingCode,
} from "@avocadostudio-ai/site-sdk/coverage"

// scripts/check-editing-surface.mjs
import {
  extractMarkedBlocks,
  editableCoverage,
  formatEditableCoverage,
  panelCoverage,
  formatPanelCoverage,
} from "@avocadostudio-ai/site-sdk/coverage"
import { getAllBlockMeta } from "@avocadostudio-ai/site-sdk/blocks"

const SITE = process.env.SITE_URL ?? "http://localhost:3000"
const SITE_ID = process.env.SITE_ID ?? "my-site"
const MIN = Number(process.env.MIN_COVERAGE ?? 100)

const json = async (url) => {
  const res = await fetch(url)
  if (!res.ok) throw new Error(`${url} → ${res.status}`)
  return res.json()
}

const manifest = await json(`${SITE}/api/editor/blocks`)
const { pages } = await json(`${SITE}/api/editor/pages`)

// 1. The preview half: fetch each page in editor mode and read its markers.
const marked = []
for (const page of pages) {
  // Slug-to-URL is your own convention; the sample content uses paths already,
  // like "/" and "/blog/building-with-blocks".
  const path = page.slug.startsWith("/") ? page.slug : `/${page.slug}`
  const url = new URL(path, SITE)
  url.searchParams.set("__editor", "1")
  url.searchParams.set("siteId", SITE_ID)
  // Required in production; unnecessary against a dev server.
  if (process.env.DRAFT_MODE_SECRET) {
    url.searchParams.set("secret", process.env.DRAFT_MODE_SECRET)
  }

  const html = await (await fetch(url)).text()
  for (const block of extractMarkedBlocks(html)) {
    // Supplying props is what keeps empty fields out of the denominator.
    block.props = page.blocks.find((b) => b.id === block.blockId)?.props
    marked.push(block)
  }
}

const editable = editableCoverage(manifest, marked)
console.log(formatEditableCoverage(editable))

// 2. The panel half: measure the manifest against the real content.
const panel = panelCoverage(manifest, pages, { builtinTypes: getAllBlockMeta() })
console.log("")
console.log(formatPanelCoverage(panel))

const pct = editable.expected === 0 ? 100 : (editable.marked / editable.expected) * 100
const blocking = panel.findings.filter((f) => f.code !== "phantom_field")

if (pct < MIN || blocking.length > 0) {
  console.error(`\nediting surface below threshold: ${pct.toFixed(0)}% marked, ` +
    `${blocking.length} panel findings (min ${MIN}%)`)
  process.exit(1)
}

{
  "scripts": {
    "check:editing-surface": "node scripts/check-editing-surface.mjs"
  }
}

import { editableProps } from "@avocadostudio-ai/site-sdk/markers"

<div className="hero__media" {...editableProps("imageUrl", { kind: "image" })}>
  <Image src={props.imageUrl} alt={props.imageAlt} />
</div>

import { editableScopeProps } from "@avocadostudio-ai/site-sdk/markers"

{props.items.map((item, i) => (
  <li key={item.id} {...editableScopeProps(`items[${i}]`)}>
    <FaqRow item={item} />   {/* marks a bare "question"; needs no prefix */}
  </li>
))}

<div className="flex flex-col gap-6">
  {props.items.map((item, i) => (
    <div key={item.id} {...editableScopeProps(`items[${i}]`, { display: "contents" })}>
      <FaqRow item={item} />
    </div>
  ))}
</div>