Koder Document eXchange Format (.kdx)
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).
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ê)
| Camada | Peça | Papel |
|---|---|---|
| Significado | KMD (engines/lang/kmd) |
prosa, estrutura, tabelas, refs, dados, forms |
| Marcas/gráfico | KVG (engines/lang/kvg) |
toda marca visual + projeção de página fixa |
| Página/tema | extensão do KMD (kmd-RFC-001) | page-sizemargensmasters/capa + theme: verge |
| Container | ZIP+manifesto classe-kpkg [F3] |
fontesimagensICC/dados embutidos |
| Render | render-core (engines/lang/kdx) |
reflow · paginado-fixo · export |
Regra de fronteira (normativa): o texto flui como texto (fonte embutida, selecionávelbuscávelacessí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 asuperfície.
Backends de render implementados (todos do mesmo parseKdx AST → paridade de significado por construção):
| Backend | API | Projeção | Saída |
|---|---|---|---|
pdf_writer.dart |
writePdf(PagedResult) |
paged |
PDF nativo (fonte embarcada/subset, ToUnicode, links, outline) |
kdx_wasm.dart + <koder-kdx> |
kdxLayoutJson(src) |
paged |
box-tree JSON → pintura em <canvas> (web/Dok), byte-fiel ao PDF |
html_writer.dart |
writeHtml(doc, {fragment}) |
reflow |
HTML semânticoacessível (h1-6, table colspanrowspan, figure, code, <mark>/<sup>/<sub>, footnotes, stylesheet Verge); guard de scheme javascript: |
5. Perfis (conformância progressiva)
| Perfil | Adiciona | Degradação |
|---|---|---|
| Core | texto+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] |
CMYKspotoverprint, 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 → HTMLEPUB / import (PDFDOCXHTMLMD): [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.