@byline/cli 2.7.0 → 3.0.0

package/dist/templates/byline-examples/collections/docs/admin.tsx

@@ -200,6 +200,6 @@ export const DocsAdmin: CollectionAdminConfig = defineAdmin(Docs, {
    */
   layout: {
     main: ['tabs'],
-    sidebar: ['publishedOn', 'availableLanguages'],
+    sidebar: ['publishedOn'],
   },
 })

package/dist/templates/byline-examples/collections/docs/schema.ts

@@ -11,7 +11,6 @@ import { defineCollection, defineWorkflow } from '@byline/core'
 
 import { PhotoBlock } from '../../blocks/photo-block.js'
 import { RichTextBlock } from '../../blocks/richtext-block.js'
-import { availableLanguagesField } from '../../fields/available-languages-field.js'
 import { publishedOnField } from '../../fields/published-on-field.js'
 
 // ---- Schema (server-safe, no UI concerns) ----
@@ -38,6 +37,7 @@ export const Docs = defineCollection({
   search: { fields: ['title'] },
   useAsTitle: 'title',
   useAsPath: 'title',
+  advertiseLocales: true, // Renders the available-locales sidebar widget.
   linksInEditor: true, // See type definition for details.
   // All hooks can be a single function or an array of functions.
   // If an array is provided, the functions will be executed in sequence.
@@ -156,7 +156,6 @@ export const Docs = defineCollection({
       optional: true,
       blocks: [RichTextBlock, PhotoBlock],
     },
-    availableLanguagesField(),
   ],
 })
 

package/dist/templates/byline-examples/collections/news/admin.tsx

@@ -214,6 +214,6 @@ export const NewsAdmin: CollectionAdminConfig = defineAdmin(News, {
    */
   layout: {
     main: ['main'],
-    sidebar: ['featured', 'availableLanguages', 'publishedOn'],
+    sidebar: ['featured', 'publishedOn'],
   },
 })

package/dist/templates/byline-examples/collections/news/schema.ts

@@ -9,7 +9,6 @@
 import type { CollectionFieldData } from '@byline/core'
 import { defineCollection, defineWorkflow } from '@byline/core'
 
-import { availableLanguagesField } from '~/fields/available-languages-field.js'
 import { publishedOnField } from '~/fields/published-on-field.js'
 
 // ---- Schema (server-safe, no UI concerns) ----
@@ -34,6 +33,7 @@ export const News = defineCollection({
   search: { fields: ['title'] },
   useAsTitle: 'title',
   useAsPath: 'title',
+  advertiseLocales: true, // Renders the available-locales sidebar widget.
   linksInEditor: true, // See type definition for details.
   fields: [
     { name: 'title', label: 'Title', type: 'text', localized: true },
@@ -82,7 +82,6 @@ export const News = defineCollection({
       embedRelationsOnSave: true, // See type definition for details.
     },
     publishedOnField,
-    availableLanguagesField(),
   ],
 })
 

package/dist/templates/byline-examples/collections/pages/admin.tsx

@@ -205,6 +205,6 @@ export const PagesAdmin: CollectionAdminConfig = defineAdmin(Pages, {
    */
   layout: {
     main: ['tabs'],
-    sidebar: ['publishedOn', 'availableLanguages'],
+    sidebar: ['publishedOn'],
   },
 })

package/dist/templates/byline-examples/collections/pages/schema.ts

@@ -11,7 +11,6 @@ import { defineCollection, defineWorkflow } from '@byline/core'
 
 import { PhotoBlock } from '~/blocks/photo-block'
 import { RichTextBlock } from '~/blocks/richtext-block'
-import { availableLanguagesField } from '~/fields/available-languages-field.js'
 import { publishedOnField } from '~/fields/published-on-field'
 
 // ---- Schema (server-safe, no UI concerns) ----
@@ -36,6 +35,7 @@ export const Pages = defineCollection({
   search: { fields: ['title'] },
   useAsTitle: 'title',
   useAsPath: 'title',
+  advertiseLocales: true, // Renders the available-locales sidebar widget.
   /**
    * Pages live at the site root (no `/pages/` prefix) and may be nested
    * under an `area` segment. Same composition rule used by the admin
@@ -100,7 +100,6 @@ export const Pages = defineCollection({
       blocks: [RichTextBlock, PhotoBlock],
     },
     publishedOnField,
-    availableLanguagesField(),
   ],
 })
 

package/dist/templates/byline-examples/fields/available-languages-field.ts

@@ -13,6 +13,13 @@
  * the only imports are `@byline/core` types and the i18n locale list.
  *
  * See `docs/FIELDS.md` for the schema-vs-admin model.
+ *
+ * @deprecated **No longer needed** as of the content-locale-resolution work.
+ * The editorial "advertise these locales" control is now a core *system
+ * attribute* + ledger-aware sidebar widget (`availableLocales`) — see
+ * `docs/AVAILABLE-LOCALES.md`. This userland custom field is **left in place as
+ * a reference example** of the schema-side field-builder pattern; it is not used
+ * by the system widget and can be removed from collection schemas.
  */
 
 import type { GroupField } from '@byline/core'

package/dist/templates/byline-examples/scripts/backfill-version-locales.ts

@@ -0,0 +1,46 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * One-time maintenance: populate the version-locale availability ledger
+ * (`byline_document_version_locales`) for document versions written before
+ * the ledger existed. After this runs, `localeFallback: 'strict'` reads can
+ * see pre-existing documents; new writes keep the ledger current on their own
+ * (createDocumentVersion step 6).
+ *
+ * Idempotent — safe to re-run. Uses the installation's configured default
+ * content locale (resolved from byline/i18n.ts via the server config).
+ *
+ *   cd apps/webapp && pnpm tsx byline/scripts/backfill-version-locales.ts
+ *
+ * See docs/CONTENT-LOCALE-RESOLUTION.md.
+ */
+
+import '../load-env.js'
+import '../server.config.js'
+
+import { getServerConfig } from '@byline/core'
+import type { PgAdapter } from '@byline/db-postgres'
+
+async function run() {
+  // `backfillVersionLocales` is a Postgres-adapter housekeeping method (off
+  // the core `IDbAdapter` contract), so annotate the registered adapter as
+  // `PgAdapter` — the documented pattern for scripts that need raw handles.
+  const db = getServerConfig().db as PgAdapter
+  const { rowsInserted } = await db.backfillVersionLocales()
+  console.log(
+    `✓ version-locale ledger backfilled — ${rowsInserted} (version, locale) row(s) inserted`
+  )
+}
+
+run()
+  .then(() => process.exit(0))
+  .catch((error) => {
+    console.error('✗ version-locale backfill failed:', error)
+    process.exit(1)
+  })

package/dist/templates/byline-examples/scripts/import-docs.ts

@@ -8,10 +8,10 @@
 
 // Examples...
 //
-// pnpm tsx --env-file=.env --env-file=.env.local byline/scripts/import-docs.ts ../../docs/**/*.md --dry-run
-// pnpm tsx --env-file=.env --env-file=.env.local byline/scripts/import-docs.ts ../../docs/**/*.md --verbose
-// pnpm tsx --env-file=.env --env-file=.env.local byline/scripts/import-docs.ts '../../docs/*.md' --dry-run --verbose
-// pnpm tsx --env-file=.env --env-file=.env.local byline/scripts/import-docs.ts ../../docs/**/*.md
+// pnpm tsx byline/scripts/import-docs.ts ../../docs/**/*.md --dry-run
+// pnpm tsx byline/scripts/import-docs.ts ../../docs/**/*.md --verbose
+// pnpm tsx byline/scripts/import-docs.ts '../../docs/*.md' --dry-run --verbose
+// pnpm tsx byline/scripts/import-docs.ts ../../docs/**/*.md
 //
 // Run tests...
 //
@@ -20,14 +20,17 @@
 /**
  * Import markdown files into the `docs` collection.
  *
- *   pnpm tsx --env-file=.env --env-file=.env.local byline/scripts/import-docs.ts <path-or-glob...>
+ *   pnpm tsx byline/scripts/import-docs.ts <path-or-glob...>
  *
  * Per-file flow:
  *   1. Read the file, split frontmatter from body with gray-matter.
  *   2. Parse the body to mdast via remark-parse + remark-gfm.
- *   3. Convert mdast → Lexical SerializedEditorState.
- *   4. Resolve `featureImage` (a `media` path) to a relation envelope.
- *   5. `findByPath` to decide create vs update. On update, status and
+ *   3. Rewrite `./SIBLING.md[#hash]` links to `/docs/<imported-path>`
+ *      using a sourcePath→docPath map built from a frontmatter pre-pass.
+ *      Targets outside the batch are stripped to plain text.
+ *   4. Convert mdast → Lexical SerializedEditorState.
+ *   5. Resolve `featureImage` (a `media` path) to a relation envelope.
+ *   6. `findByPath` to decide create vs update. On update, status and
  *      publishedOn are preserved — editorial state in Byline wins.
  *
  * Flags:
@@ -44,7 +47,7 @@ import { resolve } from 'node:path'
 
 import { createSuperAdminContext } from '@byline/auth'
 import { type CollectionHandle, createBylineClient } from '@byline/client'
-import { getServerConfig, slugify } from '@byline/core'
+import { getCollectionDefinition, getServerConfig, slugify } from '@byline/core'
 import type { Root } from 'mdast'
 import remarkGfm from 'remark-gfm'
 import remarkParse from 'remark-parse'
@@ -52,10 +55,13 @@ import { unified } from 'unified'
 
 import { type DocFrontmatter, parseDocFile } from './lib/frontmatter.js'
 import { type MdastToLexicalWarning, mdastToLexical } from './lib/mdast-to-lexical.js'
+import { type DocLinkRewriteWarning, rewriteDocLinks } from './lib/rewrite-doc-links.js'
 import { stripLeadingH1IfMatches } from './lib/strip-leading-h1.js'
 
 const DOCS_COLLECTION = 'docs'
 const MEDIA_COLLECTION = 'media'
+const DOCS_URL_PREFIX = '/docs'
+const DEFAULT_IMPORT_STATUS = 'published'
 
 interface Flags {
   dryRun: boolean
@@ -101,6 +107,20 @@ function logWarnings(filePath: string, warnings: MdastToLexicalWarning[]): void
   }
 }
 
+function logLinkWarnings(filePath: string, warnings: DocLinkRewriteWarning[]): void {
+  if (warnings.length === 0) return
+  console.warn(`  - ${warnings.length} link rewrite(s) for ${filePath}:`)
+  for (const w of warnings) {
+    if (w.kind === 'rewritten-doc-link') {
+      console.warn(`      [rewrite]    ${w.href} → ${w.resolvedTo}`)
+    } else if (w.kind === 'unresolved-doc-link') {
+      console.warn(`      [unresolved] ${w.href}  (stripped to plain text)`)
+    } else {
+      console.warn(`      [empty]      '${w.href}'  (stripped to plain text)`)
+    }
+  }
+}
+
 interface ResolvedFeatureImage {
   targetCollectionId: string
   targetDocumentId: string
@@ -123,14 +143,12 @@ interface BuildPayloadArgs {
   frontmatter: DocFrontmatter
   lexicalState: unknown
   featureImage: ResolvedFeatureImage | null
-  locale: string
 }
 
 function buildDocPayload({
   frontmatter,
   lexicalState,
   featureImage,
-  locale,
 }: BuildPayloadArgs): Record<string, unknown> {
   const payload: Record<string, unknown> = {
     title: frontmatter.title,
@@ -141,11 +159,6 @@ function buildDocPayload({
         constrainedWidth: frontmatter.constrainedWidth ?? true,
       },
     ],
-    // The `availableLanguages` field's built-in validator requires at
-    // least one checked locale; without it, opening the imported doc
-    // in the admin surfaces a validation error before any save. Seed
-    // the authoring locale so editors land on a valid form.
-    availableLanguages: { [locale]: true },
   }
   if (frontmatter.summary !== undefined) payload.summary = frontmatter.summary
   if (frontmatter.publishedOn !== undefined) payload.publishedOn = frontmatter.publishedOn
@@ -158,6 +171,27 @@ function derivePath(frontmatter: DocFrontmatter, locale: string): string {
   return slugify(frontmatter.title, { locale, collectionPath: DOCS_COLLECTION })
 }
 
+/**
+ * Walk a document's status forward to `targetStatus`. The workflow only
+ * permits ±1 step transitions, so jumping draft → published has to step
+ * through any intermediate statuses (e.g. needs_review). No-op when the
+ * workflow doesn't include the target or when already at/past it.
+ */
+async function walkToStatus(
+  handle: CollectionHandle,
+  documentId: string,
+  workflowStatuses: readonly { name: string }[],
+  currentStatus: string,
+  targetStatus: string
+): Promise<void> {
+  const currentIdx = workflowStatuses.findIndex((s) => s.name === currentStatus)
+  const targetIdx = workflowStatuses.findIndex((s) => s.name === targetStatus)
+  if (currentIdx === -1 || targetIdx === -1 || targetIdx <= currentIdx) return
+  for (let i = currentIdx + 1; i <= targetIdx; i++) {
+    await handle.changeStatus(documentId, workflowStatuses[i].name)
+  }
+}
+
 interface ProcessResult {
   filePath: string
   action: 'created' | 'updated' | 'skipped'
@@ -165,17 +199,45 @@ interface ProcessResult {
   path: string
 }
 
+/**
+ * Build a map of absolute markdown source paths → imported doc paths,
+ * by reading just the frontmatter of every file in the batch. Needed so
+ * the link-rewrite step in pass 2 can resolve `./SIBLING.md` to the URL
+ * its target will be served at after import.
+ */
+function buildSourcePathMap(files: string[], defaultLocale: string): Map<string, string> {
+  const map = new Map<string, string>()
+  for (const file of files) {
+    try {
+      const source = readFileSync(file, 'utf8')
+      const parsed = parseDocFile(source, file)
+      const locale = parsed.frontmatter.locale ?? defaultLocale
+      map.set(file, derivePath(parsed.frontmatter, locale))
+    } catch {
+      // Skip — pass 2 will surface the parse error against this file.
+    }
+  }
+  return map
+}
+
 async function processFile(
   filePath: string,
   client: ReturnType<typeof createBylineClient>,
   handle: CollectionHandle,
-  flags: Flags
+  flags: Flags,
+  pathMap: Map<string, string>
 ): Promise<ProcessResult> {
   const source = readFileSync(filePath, 'utf8')
   const parsed = parseDocFile(source, filePath)
   const locale = parsed.frontmatter.locale ?? client.defaultLocale
 
   const mdast = stripLeadingH1IfMatches(parseBodyToMdast(parsed.body), parsed.frontmatter.title)
+  const linkWarnings = rewriteDocLinks(mdast, {
+    sourceFilePath: filePath,
+    pathMap,
+    urlPrefix: DOCS_URL_PREFIX,
+  })
+  if (flags.verbose) logLinkWarnings(filePath, linkWarnings)
   const { state, warnings } = mdastToLexical(mdast)
   if (flags.verbose) logWarnings(filePath, warnings)
 
@@ -193,7 +255,6 @@ async function processFile(
     frontmatter: parsed.frontmatter,
     lexicalState: state,
     featureImage,
-    locale,
   })
 
   if (flags.dryRun) {
@@ -201,6 +262,15 @@ async function processFile(
     return { filePath, action: 'skipped', path: docPath }
   }
 
+  // Re-imports default to the published status (overridable per-file via
+  // frontmatter `status:`). `update` always resets to the workflow's
+  // default status on a new version, so we walk transitions forward
+  // afterwards; `create` accepts an initial status directly.
+  const desiredStatus = parsed.frontmatter.status ?? DEFAULT_IMPORT_STATUS
+  const definition = getCollectionDefinition(DOCS_COLLECTION)
+  const workflowStatuses = definition?.workflow?.statuses ?? []
+  const defaultStatus = workflowStatuses[0]?.name ?? 'draft'
+
   const existing = await handle.findByPath(docPath, {
     locale,
     status: 'any',
@@ -208,19 +278,29 @@ async function processFile(
   })
 
   if (existing) {
-    // Editorial state wins on re-import: don't overwrite status, and
-    // don't clobber publishedOn if Byline already has one.
+    // Don't clobber publishedOn if Byline already has one.
     if (existing.fields?.publishedOn) {
       delete payload.publishedOn
     }
-    const result = await handle.update(existing.id, payload, { locale })
+    const result = await handle.update(existing.id, payload, {
+      locale,
+      // Advertise the imported locale (editorial available-locales set), merged
+      // with whatever is already advertised so a later-locale re-import doesn't
+      // clobber an earlier one. The public set is still gated by the version
+      // completeness ledger (intersection). See docs/AVAILABLE-LOCALES.md.
+      availableLocales: [...new Set([...(existing.availableLocales ?? []), locale])],
+    })
+    await walkToStatus(handle, result.documentId, workflowStatuses, defaultStatus, desiredStatus)
     return { filePath, action: 'updated', documentId: result.documentId, path: docPath }
   }
 
   const result = await handle.create(payload, {
     locale,
-    status: parsed.frontmatter.status,
+    status: desiredStatus,
     path: docPath,
+    // Advertise the authoring locale; the public advertised set is the
+    // intersection of this editorial set with the completeness ledger.
+    availableLocales: [locale],
   })
   return { filePath, action: 'created', documentId: result.documentId, path: docPath }
 }
@@ -240,6 +320,10 @@ async function run(): Promise<void> {
   const client = createBylineClient({ config, requestContext })
   const handle = client.collection(DOCS_COLLECTION)
 
+  // Pre-pass: map each source file to the path its imported doc will
+  // live at, so pass 2 can rewrite cross-doc markdown links.
+  const pathMap = buildSourcePathMap(files, client.defaultLocale)
+
   let created = 0
   let updated = 0
   let skipped = 0
@@ -247,7 +331,7 @@ async function run(): Promise<void> {
 
   for (const file of files) {
     try {
-      const result = await processFile(file, client, handle, flags)
+      const result = await processFile(file, client, handle, flags, pathMap)
       if (result.action === 'created') created += 1
       else if (result.action === 'updated') updated += 1
       else skipped += 1

package/dist/templates/byline-examples/scripts/lib/mdast-to-lexical.test.node.ts

@@ -0,0 +1,262 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { Root } from 'mdast'
+import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
+import { unified } from 'unified'
+import { describe, expect, test } from 'vitest'
+
+import { mdastToLexical } from './mdast-to-lexical.js'
+
+function parse(md: string): Root {
+  return unified().use(remarkParse).use(remarkGfm).parse(md) as Root
+}
+
+function convert(md: string) {
+  return mdastToLexical(parse(md))
+}
+
+describe('mdastToLexical', () => {
+  test('empty input yields a single empty paragraph', () => {
+    const { state, warnings } = convert('')
+    expect(warnings).toEqual([])
+    expect(state.root.type).toBe('root')
+    expect(state.root.children).toHaveLength(1)
+    expect(state.root.children[0]).toMatchObject({ type: 'paragraph', children: [] })
+  })
+
+  test('paragraph with plain text', () => {
+    const { state } = convert('hello world')
+    expect(state.root.children[0]).toMatchObject({
+      type: 'paragraph',
+      children: [{ type: 'text', text: 'hello world', format: 0 }],
+    })
+  })
+
+  test('heading depth maps to tag h1-h6', () => {
+    const { state } = convert('# h1\n\n## h2\n\n###### h6')
+    expect(state.root.children).toHaveLength(3)
+    expect(state.root.children[0]).toMatchObject({ type: 'heading', tag: 'h1' })
+    expect(state.root.children[1]).toMatchObject({ type: 'heading', tag: 'h2' })
+    expect(state.root.children[2]).toMatchObject({ type: 'heading', tag: 'h6' })
+  })
+
+  test('bold + italic compose into a single text node with bitmask format=3', () => {
+    const { state } = convert('***both***')
+    const paragraph = state.root.children[0] as unknown as {
+      children: Array<{ format: number; text: string }>
+    }
+    expect(paragraph.children).toHaveLength(1)
+    expect(paragraph.children[0]).toMatchObject({ text: 'both', format: 1 | 2 })
+  })
+
+  test('inline code carries the IS_CODE bit', () => {
+    const { state } = convert('a `b` c')
+    const paragraph = state.root.children[0] as unknown as {
+      children: Array<{ format: number; text: string }>
+    }
+    // 'a ', code 'b', ' c'
+    expect(paragraph.children.map((c) => ({ text: c.text, format: c.format }))).toEqual([
+      { text: 'a ', format: 0 },
+      { text: 'b', format: 1 << 4 },
+      { text: ' c', format: 0 },
+    ])
+  })
+
+  test('strikethrough (GFM) carries the strikethrough bit', () => {
+    const { state } = convert('a ~~b~~ c')
+    const paragraph = state.root.children[0] as unknown as {
+      children: Array<{ format: number; text: string }>
+    }
+    const struck = paragraph.children.find((c) => c.text === 'b')
+    expect(struck?.format).toBe(1 << 2)
+  })
+
+  test('unordered list emits listType=bullet, tag=ul, listitems with peeled paragraph children', () => {
+    const { state } = convert('- one\n- two')
+    const list = state.root.children[0] as unknown as {
+      type: string
+      listType: string
+      tag: string
+      children: Array<{ type: string; children: Array<{ type: string; text: string }> }>
+    }
+    expect(list).toMatchObject({ type: 'list', listType: 'bullet', tag: 'ul' })
+    expect(list.children).toHaveLength(2)
+    expect(list.children[0]).toMatchObject({
+      type: 'listitem',
+      children: [{ type: 'text', text: 'one' }],
+    })
+  })
+
+  test('ordered list propagates start and numbers values', () => {
+    const { state } = convert('3. a\n4. b')
+    const list = state.root.children[0] as unknown as {
+      listType: string
+      tag: string
+      start: number
+      children: Array<{ value: number }>
+    }
+    expect(list).toMatchObject({ listType: 'number', tag: 'ol', start: 3 })
+    expect(list.children[0].value).toBe(3)
+    expect(list.children[1].value).toBe(4)
+  })
+
+  test('nested list lives inside the parent listitem', () => {
+    const { state } = convert('- a\n  - a1\n- b')
+    const list = state.root.children[0] as unknown as {
+      children: Array<{ children: Array<{ type: string }> }>
+    }
+    const firstItemChildren = list.children[0].children
+    expect(firstItemChildren.some((c) => c.type === 'list')).toBe(true)
+  })
+
+  test('link emits link node with custom attributes envelope', () => {
+    const { state } = convert('[label](https://example.com)')
+    const paragraph = state.root.children[0] as unknown as {
+      children: Array<{
+        type: string
+        attributes?: { linkType?: string; url?: string; newTab?: boolean }
+        children?: Array<{ text: string }>
+      }>
+    }
+    const link = paragraph.children[0]
+    expect(link.type).toBe('link')
+    expect(link.attributes).toMatchObject({
+      linkType: 'custom',
+      url: 'https://example.com',
+      newTab: true,
+    })
+    expect(link.children?.[0]).toMatchObject({ text: 'label' })
+  })
+
+  test('fenced code with language stores `language` and emits code-highlight + linebreak children', () => {
+    const { state } = convert('```ts\nconst x = 1\nconst y = 2\n```')
+    const code = state.root.children[0] as unknown as {
+      type: string
+      language: string
+      children: Array<{ type: string; text?: string }>
+    }
+    expect(code).toMatchObject({ type: 'code', language: 'typescript' })
+    expect(code.children[0]).toMatchObject({ type: 'code-highlight', text: 'const x = 1' })
+    expect(code.children[1]).toMatchObject({ type: 'linebreak' })
+    expect(code.children[2]).toMatchObject({ type: 'code-highlight', text: 'const y = 2' })
+  })
+
+  test('thematic break emits horizontalrule', () => {
+    const { state } = convert('---')
+    expect(state.root.children[0]).toMatchObject({ type: 'horizontalrule' })
+  })
+
+  test('blockquote flattens single paragraph into inline children', () => {
+    const { state } = convert('> hello')
+    const quote = state.root.children[0] as unknown as {
+      type: string
+      children: Array<{ type: string; text?: string }>
+    }
+    expect(quote.type).toBe('quote')
+    expect(quote.children).toEqual([expect.objectContaining({ type: 'text', text: 'hello' })])
+  })
+
+  test('image at block level is dropped with a warning', () => {
+    const { warnings, state } = convert('![alt](https://example.com/x.png)')
+    expect(warnings.some((w) => w.kind === 'dropped-image')).toBe(true)
+    // Paragraph survives as empty (image was its only child)
+    expect(state.root.children[0]).toMatchObject({ type: 'paragraph' })
+  })
+
+  test('GFM table maps to table/tablerow/tablecell with first-row headerState', () => {
+    const md = '| a | b |\n| - | - |\n| 1 | 2 |\n'
+    const { state, warnings } = convert(md)
+    expect(warnings).toEqual([])
+
+    const table = state.root.children[0] as unknown as {
+      type: string
+      children: Array<{
+        type: string
+        children: Array<{
+          type: string
+          headerState: number
+          children: Array<{ type: string; children: Array<{ text: string }> }>
+        }>
+      }>
+    }
+    expect(table.type).toBe('table')
+    expect(table.children).toHaveLength(2)
+
+    const [headerRow, bodyRow] = table.children
+    expect(headerRow.type).toBe('tablerow')
+    expect(bodyRow.type).toBe('tablerow')
+    expect(headerRow.children[0]).toMatchObject({ type: 'tablecell', headerState: 1 })
+    expect(headerRow.children[1]).toMatchObject({ type: 'tablecell', headerState: 1 })
+    expect(bodyRow.children[0]).toMatchObject({ type: 'tablecell', headerState: 0 })
+    expect(bodyRow.children[1]).toMatchObject({ type: 'tablecell', headerState: 0 })
+
+    // Inline cell content is wrapped in a paragraph.
+    const firstHeaderCell = headerRow.children[0]
+    expect(firstHeaderCell.children[0].type).toBe('paragraph')
+    expect(firstHeaderCell.children[0].children[0]).toMatchObject({ text: 'a' })
+    expect(bodyRow.children[1].children[0].children[0]).toMatchObject({ text: '2' })
+  })
+
+  test('empty cell emits a paragraph with no children', () => {
+    const md = '| a | b |\n| - | - |\n|   | 2 |\n'
+    const { state } = convert(md)
+    const table = state.root.children[0] as unknown as {
+      children: Array<{
+        children: Array<{ children: Array<{ type: string; children: unknown[] }> }>
+      }>
+    }
+    const emptyCellParagraph = table.children[1].children[0].children[0]
+    expect(emptyCellParagraph).toMatchObject({ type: 'paragraph', children: [] })
+  })
+
+  test('inline formatting inside cells is preserved', () => {
+    const md = '| col |\n| - |\n| **bold** |\n'
+    const { state } = convert(md)
+    const table = state.root.children[0] as unknown as {
+      children: Array<{
+        children: Array<{
+          children: Array<{ children: Array<{ text: string; format: number }> }>
+        }>
+      }>
+    }
+    const bodyCellInline = table.children[1].children[0].children[0].children[0]
+    expect(bodyCellInline).toMatchObject({ text: 'bold', format: 1 })
+  })
+
+  test('code fence language is normalized to prism-known ids', () => {
+    const cases: Array<[string, string]> = [
+      ['ts', 'typescript'],
+      ['js', 'javascript'],
+      ['sh', 'bash'],
+      ['yml', 'yaml'],
+      ['tsx', 'tsx'], // already prism-known, passes through
+    ]
+    for (const [input, expected] of cases) {
+      const { state } = convert(`\`\`\`${input}\nx\n\`\`\``)
+      const code = state.root.children[0] as unknown as { language: string }
+      expect(code.language).toBe(expected)
+    }
+  })
+
+  test('hard-wrapped paragraph collapses internal newlines to spaces', () => {
+    const md =
+      'In a world where AI produces content fast,\ninto dozens of languages,\nwhy does a CMS matter?'
+    const { state } = convert(md)
+    const paragraph = state.root.children[0] as unknown as {
+      children: Array<{ text: string }>
+    }
+    // Single text node with newlines collapsed to single spaces — no
+    // <br> nodes and no embedded \n.
+    expect(paragraph.children).toHaveLength(1)
+    expect(paragraph.children[0].text).toBe(
+      'In a world where AI produces content fast, into dozens of languages, why does a CMS matter?'
+    )
+  })
+})