Generative UI via KVG (Koder Vector Graphics)

Summary

Explora se KVG (Koder Vector Graphics — formato declarativo já existente em engines/sdk/koder_kit/lib/src/kvg/) pode ser o substrato Koder-nativo para generative UI — pattern emergente onde IA emite especificações de widgets dinâmicos renderizados em runtime (e.g., Gemini Intelligence 2026, Google research generative UI 2024).

Motivation

Padrões competitivos:

• Google Gemini Intelligence (2026) anunciou "AI-generated widgets" criados por linguagem natural, com Liquid-Glass-like rendering.
• research.google generative UI (2024 blog) demonstrou LLMs emitindo HTML+CSS+JS dinâmico para responder a prompts variados.
• Vercel v0 (de-facto comercial) gera React from prompts.

Risco competitivo: se Koder não tem caminho próprio para generative UI, produtos AI Koder ficam atrás em UX.

Por que NÃO HTML+CSS+JS:

• LLMs emitindo HTML têm taxa de erro alta (markup malformado, XSS risks, runtime crashes).
• Sandbox enforcement complexo.
• Não composes bem com koder_kit widgets nativos.

Por que KVG pode ser a resposta:

• Declarativo — parseable + validável antes de render.
• Já existente — koder_kit/lib/src/kvg/ é cross-surface (Flutter, Web).
• Restritivo por design — não permite eval, network, file IO — sandbox trivial.
• Composes com Koder design system — usa tokens, color roles, type roles existentes.
• Mais fácil pra LLM — schema declarativo menor que React/HTML.

Hypothesis

H1: LLMs (Claude Opus 4.7, GPT-5, Gemini Pro) podem emitir KVG one-shot com taxa de sucesso ≥80% para prompts comuns ("show me a chart of X", "render a card for Y", "generate a diagram of Z").

H2: KVG output é validável antes de render, capturando ~95% de errors estruturais sem rodar render.

H3: Composição com tokens Koder (color-roles, typography) é zero-shot — LLM já entende surface, primary, body-medium se documentado.

Experiments (proposed)

Phase 1: schema documentation

• Document KVG schema (estendido se necessário) em meta/docs/stack/specs/kvg/generative-extensions.kmd.
• Cobrir: shapes, layouts, charts, common widget compositions (card, list, table).
• Decisão go/no-go: schema fits em <3k tokens? Sim → continua. Não → reconsider.

Phase 2: pilot prompts

10 prompts canônicos:

1. "Render a card with title 'Hello' and body 'World'"
2. "Show a bar chart of [1, 5, 3, 8, 2]"
3. "Generate a flowchart of OAuth flow"
4. "Create a button with primary color saying 'Submit'"
5. "Render a 2-column layout with image left, text right"
6. ...

Testar em 3 modelos (Opus, GPT-5, Gemini Pro). Métrica: % de outputs que renderizam corretamente sem editing.

Phase 3: integration test in Kortex

If Phase 2 ≥80% success: integrar em Kortex artifact panel (cross-link #110):

• User pede widget → AI emite KVG → artifact panel renders.
• Edit affordance: user modifies KVG; AI sees diff next message.
• Cost transparency via cost-display.kmd (#112).

Phase 4: safety bounds

Even with declarative KVG:

• No network calls from rendered widgets (no <image src="url"> fetching arbitrary).
• No eval-like — KVG não tem <script> semantics.
• Resource limits — max nodes per widget (e.g., 10k), max nested depth (32).
• Sanitization — text content sanitized; URLs whitelisted.
• Audit log — every generated widget logged for forensics.

Open questions

1. Should KVG schema be extended for AI-generative use cases (charts, forms, dynamic data)? Or keep current minimal scope and accept KVG não cobre todo widget?
2. Does the AI need access to current theme tokens to emit consistent designs? (Probably yes — include in prompt.)
3. How is interaction handled? KVG hoje é mostly static; do we add on_click actions emitted by AI that bind to Koder actions?
4. Versioning compatibility: KVG v1 vs v2 if extended for generative — backward-compat?
5. Latency budget: generative widget = full prompt round-trip. Acceptable for "show me X" but not for inline UI suggestions. Differentiate use cases.

Experimental results — Phase 1 + Phase 2 pilot (2026-06-20)

Run against the real Go toolchain (engines/lang/kvg/cmd/kvg, built GOWORK=off): kvg validate (parser + spec checks = the pre-render validator) and kvg render (CPU rasteriser → PNG = ground truth). Methodology: distill a generative-subset cheatsheet (the Phase-1 schema doc), then emit each prompt one-shot from the cheatsheet only, then validate + render + visually inspect.

Phase 1 — schema token budget (go/no-go gate: <3k tokens)

PASS. The generative subset (header + Core shapes + text + gradients + groups + Y-up rules + one worked example) is 2,576 chars ≈ 650–740 tokens — comfortably under the 3k gate. Note the full normative spec specs/kvg/format.kmd is ~80 KB ≈ ~20k tokens, but the LLM does not need it: the emittable Core surface compresses to ~700 tokens. (Cheatsheet archived with the experiment; it is the seed for the future generative-extensions.kmd.)

Phase 2 — pilot emission (Opus 4.8 arm, one-shot)

10 canonical prompts spanning the Claude-Design surface (card, bar chart, flowchart, button, 2-col layout, login wireframe, title slide, pie chart, line chart, pricing card):

On this canonical set H1 ≈ 100% for the Opus arm — decisively above the ≥80% gate criterion. Y-up coordinate handling (origin bottom-left) was emitted correctly in every case, including text baselines and bar/arc geometry.

Cross-model arm — DeepSeek (2026-06-20, partial close of H1 cross-model)

Same ~700-tok cheatsheet, 4 representative prompts (card, bar chart, login wireframe, pie) through deepseek-chat (different vendor, weaker than Opus) via the DeepSeek API:

3/4 valid+render one-shot from a non-Opus model — a usable partial confirmation of H1's cross-model claim. The 4th failure was a one-line header omission deterministically gated by kvg validate (the H2 net is exactly what makes the pipeline safe across models of varying strength). GPT-5/Gemini arms remain open (no keys provisioned); the gateway (services/ai/gateway) has the plumbing when they are.

H2 negative control (does the validator catch bad input?)

3 deliberately broken docs: missing header → caught (2 errors), dangling fill=#ref → caught with line:col, unterminated string → NOT caught (lexer swallowed to EOF). So validate is strong on headerprofileref/cycle checks but has a lexer-leniency gap on unterminated quotes → follow-up ticket against engines/lang/kvg parser (regression-tests.kmd; minor, found via this pilot).

Caveats (honest scope of the evidence)

• Single-model arm. Only the Opus 4.8 arm ran; the RFC's cross-model panel

  (GPT-5, Gemini Pro) is still open. The Opus result is decisive but H1's cross-model claim is partially untested.

• H3 (Koder color-role tokens) untested. Emission used raw hex; KVG-Core has

  no surfaceprimarybody-medium role layer yet. Mapping design-system roles into KVG is genuine Phase-1.5 work, not yet evidenced.

• Text is the ASCII bitmap font (basicfont 7x13): great for

  wireframesprototypesdiagrams, weak for polished typography. This is a renderer-maturity gap, not an emission failure.

• Static only. Interaction (on_click) was not exercised — see boundary

  resolution below.

Decision (Gate 1 — go/no-go for Phase 2)

Recommendation: GO for Phase 2. Gate 1 evidence (above) clears both suggested criteria — schema fits (<3k) and the LLM emits correct output well beyond "3 trial prompts" (10/10, with renders). Owner ratification still pending (this gate is owner-owned); the evidence is now on the table for that decision.

Boundary resolution — KVG × A2UI (resolves open question #3)

canvas-RFC-001 (A2UI, Accepted) and this RFC are orthogonal and composable, not competing:

• KVG = the visual-artifact substrate — static visuals: wireframes, slides,

  diagrams, charts, illustrations. Declarative, validable, sandbox-trivial.

• A2UI = the interactive-widget/state substrate — forms, buttons, inputs that

  round-trip actions to the agent; owns interaction + control layout + session state.

• Composition: A2UI owns interaction; KVG embeds inside A2UI as a rich visual

  node (Image/Custom) or stands alone for pure-visual artifacts. Do NOT bolt on_click onto KVG (open question #3) — let A2UI own interaction. The "Koder Design" product = KVG (visual) ⊕ A2UI (interaction) layered, reusing two already-decided substrates rather than inventing a third (reuse-first).

Suggested Phase 2 scope (post-ratification)

1. Promote the cheatsheet to specs/kvg/generative-extensions.kmd (Phase-1 doc).
2. Run the GPT-5 + Gemini arms on the same 10 prompts (close the cross-model H1).
3. Define the H3 color-role → KVG mapping and re-test composition.
4. Fix the validator lexer-leniency gap (ticket above).
5. Prototype the KVG⊕A2UI seam in the Kortex/Kanvas artifact panel (cross-link #110).

Alternatives considered

Cross-link

• Ticket umbrella: #120 em meta/docs/stack/backlog/pending/120-ai-generative-ui.md
• Backing spec (future, dependent on this RFC): meta/docs/stack/specs/ai-ui/generative-ui.kmd
• KVG SDK: engines/sdk/koder_kit/lib/src/kvg/
• Refs: Gemini Intelligence 2026, Google research Generative UI 2024, Vercel v0