Koder Document eXchange Format (.kdx)

kdx specs/kdx/format.kmd

Formato universal de documento da Koder Stack (.kdx) — portável, autocontido, rival do PDF e melhor-estruturado. NÃO é um formato monolítico: é a composição de KMD (significado) + KVG (marcas) + contrato de página/tema + container + perfis, sob um render-core. Esta spec é o contrato NORMATIVO de superfície; o racional profundo vive nos RFCs. v0.1 acompanha a fase F1 (Core/reflow).

When this spec applies

All triggers

Spec — Koder Document eXchange (.kdx)

v0.1 — em construção (F1). Esta spec fixa a superfície normativa do KDX conforme os 3 RFCs ratificados (2026-06-09). Seções marcadas [F2]/[F3]/[F4] serão completadas nas fases respectivas (ver backlog #133). O racional vive nos RFCs; aqui é o contrato.

1. Identidade

  • Extensão: .kdx
  • Nome/display: Koder Document · token: kdx (Koder Document eXchange)
  • Editor de referência: Koder Dok · Editor das figuras (KVG): Koder Kad
  • Render-core: engines/lang/kdx (consumido por Dok + exportadores)

2. Princípio fundador — significado é a fonte; layout é projeção

O documento KDX guarda o significado (árvore semântica = KMD-AST) como fonte da verdade. O layout fixo (caixas de página, glifos posicionados) é uma projeção derivada e cacheável. Disso decorrem, por construção: acessibilidade (a11y-tree gerada da semântica, não pode driftar), reflow e paginação a partir da mesma fonte.

3. Composição (quem é dono de quê)

CamadaPeçaPapel
SignificadoKMD (engines/lang/kmd)prosa, estrutura, tabelas, refs, dados, forms
Marcas/gráficoKVG (engines/lang/kvg)toda marca visual + projeção de página fixa
Página/temaextensão do KMD (kmd-RFC-001)page-size/margens/masters/capa + theme: verge
ContainerZIP+manifesto classe-kpkg [F3]fontes/imagens/ICC/dados embutidos
Renderrender-core (engines/lang/kdx)reflow · paginado-fixo · export

Regra de fronteira (normativa): o texto flui como texto (fonte embutida, selecionável/buscável/acessível), nunca como outline KVG. As marcas são do KVG; os objetos de documento (fontes-resource, tagged-structure, links, bookmarks, metadata) vêm do KMD-AST via o writer.

4. Projeções

  • mode: reflow — tela/mobile (responsivo). [F1]
  • mode: paged — paginado-fixo (impressão/PDF). [F2]
  • mode: adaptive (default) — a mesma fonte rende reflow ou paginado conforme a superfície.

Backends de render implementados (todos do mesmo parseKdx AST → paridade de significado por construção):

BackendAPIProjeçãoSaída
pdf_writer.dartwritePdf(PagedResult)pagedPDF nativo (fonte embarcada/subset, ToUnicode, links, outline)
kdx_wasm.dart + <koder-kdx>kdxLayoutJson(src)pagedbox-tree JSON → pintura em <canvas> (web/Dok), byte-fiel ao PDF
html_writer.dartwriteHtml(doc, {fragment})reflowHTML semântico/acessível (h1-6, table colspan/rowspan, figure, code, <mark>/<sup>/<sub>, footnotes, stylesheet Verge); guard de scheme javascript:

5. Perfis (conformância progressiva)

PerfilAdicionaDegradação
Coretexto+layout+tabelas+vetor 2D+imagens+links— (piso)
Interactive [F4]objetos interativos declarativos, forms, data-binding→ estático
Motion [F4]animação→ primeiro frame
Solid [F4]3D (KVG Solid)→ projeção 2D
Print [F2]CMYK/spot/overprint, ICC, marcas de corte (kvg-RFC-003)(alvo impressão)
Archive [F4]subset determinístico, tudo embutido, sem interatividade(preservação)

6. Autocontenção (self-hosted-first)

O .kdx persistido é autocontido: fontes, imagens, perfis ICC e dados embutidos; zero referência remota/CDN. A forma-fonte (autoria) pode referenciar vizinhos locais; o publish faz resolve-and-embed; o validador reprova referência externa/remota pendente. Fontes não-Stack ⇒ embed obrigatório; falta de fonte ⇒ fallback com aviso visível (nunca substituição silenciosa). Detalhe: kdx-RFC-001 §autocontenção. [container: F3]

7. Container [F3]

ZIP+manifesto classe-kpkg (decisão kdx-RFC-001 / #133). NÃO o .kzip (repo restic). Cripto opcional emprestando primitivos do kzip (Argon2id/X25519). Spec detalhada na fase F3.

8. Pipelines

  • KMD → KDX: layout engine + contrato de página/tema. [F1]
  • KDX → PDF: writer de 2 camadas — KVG→content-stream (kvg-RFC-003) + KMD-AST→objetos-de-documento. [F2]
  • KDX → HTML/EPUB / import (PDF/DOCX/HTML/MD): [F4]

9. Determinismo & acessibilidade

Render byte-idêntico entre máquinas (golden tests; fontes/cores pinadas — herda a disciplina do kicon). A11y-tree derivada da semântica; alt-text obrigatório por lint; ordem de leitura semântica.

10. Estado de implementação

Ver meta/docs/stack/backlog/pending/133-kdx-universal-document-format-initiative.md. F1 (Core/reflow) em andamento; nada de runtime entregue até o fechamento de F1.5.

References