KMD — contrato de página/tema + embed nativo de KVG (fundação do KDX)

ratified

Summary

Extensão mínima, aditiva e retrocompatível do KMD v1.0 para servir de camada de significado do KDX (kdx-RFC-001). Três adições:

  1. Contrato de página (frontmatter): page-size, margens, orientação,

    page-masters (capadefault…), para a projeção paginada-fixa.

  2. Binding de tema (frontmatter): theme: verge[/variant] — resolve tokens

    Verge (cortipografiaespaço) de forma determinística.

  3. Embed nativo de KVG: bloco kvg (fonte inline) **e** alt`

    (referência, resolvida-e-embutida no publish), delegando o render ao runtime KVG / kicon.

O KMD já cobre o fluxo (headings, listas, tabelas com merge/largura, blockquotes, footnotes, admonitions, header/footer + vars §14, page-break §15, TOC §16, colunas §22, math §19, diagramas §20). Falta só página/tema e embed-KVG — o que este RFC adiciona.

Motivation

O KDX precisa de layout determinístico (pra projeção fixa/PDF) e de figuras vetoriais (KVG) embutidas semanticamente. Hoje:

  • KMD não tem page-sizemargenstema no frontmatter (layout não-determinístico).
  • KMD não embute KVG (grep kvg no format.kmd = 0); só imagens (![](x.png))

    e diagramas Mermaid-like (diagram type=…).

A spec do KVG já referencia engines/lang/kmd — a ponte é intencional, só não foi escrita no lado do KMD.

Proposed additions (sketch — sujeito a refinamento)

1. Frontmatter — página

page:
  size: A4            # A4 | Letter | "WIDTHxHEIGHT<unit>" (ex.: 210x297mm)
  orientation: portrait
  margin: { top: 22mm, right: 18mm, bottom: 20mm, left: 18mm }
  masters:
    cover:   { margin: 0, background: theme.accent }   # página full-bleed
    default: {}

2. Frontmatter — tema

theme: verge            # ou verge/dark, verge/<brand>

Tokens (cortipografiaespaço/sombra) resolvidos do Verge; fontes pinadas no bundle (ver kdx-RFC-001 §autocontenção).

3. Embed de KVG

# referência (resolvida-e-embutida no publish):
![Diagrama de anatomia](anatomia.kvg "Figura 1" 100%)

# OU fonte inline (fenced):

profile Core scene { ellipse 120 120 r92 fill"#3B82F6" }

O render delega ao runtime KVG (<koder-kvg> / kicon). Texto da figura segue as regras de fonte do bundle.

4. Modo de projeção

mode: adaptive          # reflow | paged | adaptive (default)

adaptive = mesma fonte rende reflow (tela) e paginado (print), conforme a superfície.

Non-goals

  • Não transformar KMD em HTML/app: sem scripting Turing-completo, sem

    elemento-set arbitrário.

  • Não fazer do KMD um formato de desenho — o embed-KVG delega ao KVG;

    KMD não ganha primitivos vetoriais.

  • Não quebrar KMD v1.0: tudo aditivo (ver compat).

Backward compatibility

  • Frontmatter novo (pagethememode) é opcional; um doc sem ele rende

    como hoje (reflow, tema default).

  • ![](x.kvg) degrada para "imagem por referência" em readers KMD v1.0 (ou

    rasteriza via kicon); o bloco kvg ` degrada para code-fence rotulado.

  • Nenhuma sintaxe existente muda de significado.

Open questions

  1. Schema exato do page/masters (reusar algo de CSS Paged Media? ou mínimo

    próprio?).

  2. Relação com ## 17. Includes e ## 18. Variables (page/theme herdados por

    include?).

  3. O contrato de página vive no KMD (este RFC) ou na camada KDX?

    (proposta: KMD-level, reusado pelo KDX — evita duplicação.)

  4. Resolução de tokens de tema: build-time (pinado) vs render-time?
  5. Embed-KVG: só CorePrint no print, MotionSolid só em reflow/interativo?

Relação com a Stack

Filho de kdx-RFC-001. Par com kvg-RFC-003 (perfil Print + KVG→PDF). Editor de referência: Dok. Tokens: Verge.

Status: RATIFICADO (kmd-RFC-001), 2026-06-09. Contrato de página/tema + embed-KVG confirmado como extensão aditiva do KMD (owner via k-arch→k-go). Implementação fatiada em metadocsstack/backlog #133.