* autoFixSpec prunes children references to undefined elements
Dangling references are the dominant remaining first-attempt validation
failure in benchmarks, and models frequently fail to repair them even given
the exact error (observed: three repair turns, same dangling footer each
time). The renderer already skips missing children at runtime, so pruning
yields the identical rendered output while letting the spec validate. Each
removal is reported in fixes.
* Classify autoFixSpec fixes as lossy or lossless
Pruning a dangling child reference changes what renders; relocating a
misplaced field does not. Callers with a repair loop need to tell these
apart: accept lossless fixes silently, prefer re-prompting over lossy fixes,
and keep the lossy-fixed spec as a last resort. Adds fixDetails alongside the
existing fixes strings (additive, no signature break).
* Validate visible conditions in validateSpec; document filtered-list pattern
Malformed visible conditions (e.g. mixing $state and $item in one object)
silently evaluate to hidden at runtime: evaluateCondition dispatches on the
first recognized key and non-strict parsing strips the rest, so whole regions
of UI disappear with a valid-looking spec. Benchmarked worst case: a kanban
board that rendered zero task cards.
- core: VisibilityConditionStrictSchema (strict objects, exported)
- core: validateSpec rejects malformed visible with a repairable message
listing the valid forms (code: invalid_visible)
- framework prompts: FILTERED LISTS rule showing the repeat + per-item
visible pattern models keep reaching for and inventing syntax around
* Support filtered lists: repeat + $item visible on the same element
Models across vendors consistently write {repeat, visible: {$item: ...}} on
one container to mean a filtered list (kanban columns, status sections).
Previously $item had no meaning outside the repeat scope, the condition
evaluated false, and the whole region silently disappeared — the worst
visual failures in benchmarks were boards rendering zero cards this way.
Outside a repeat scope that spelling was always broken, so claiming it is
backward compatible: the renderer now applies such a condition per item,
preserving original indices for item state paths. Container-level $state
conditions and per-child $item conditions behave as before.
- core: conditionUsesItemScope helper (exported)
- react: RepeatChildren filters items by the container's $item condition
- framework prompts: FILTERED LISTS rule teaches the container spelling
- react: repeat-filter test suite (filtering, no-filter, $state container
visibility, per-child $item)
Other framework renderers (vue, svelte, solid, react-native) still evaluate
the container condition outside scope and should adopt the same semantics.
* Validate repeat containers: require children and matching state arrays
Two silent empty-region failures seen repeatedly in benchmarks, both passing
validation today: a repeat element with no children (nothing to clone per
item) and a repeat statePath pointing at a missing or non-array state value.
Both now fail validateSpec with repairable messages (repeat_without_children,
repeat_state_mismatch). State checks only run when the spec provides state;
runtime-fed state is unaffected.
* Address review: lossy-aware hook repair, react-only filtered-list rule, reuse getByPath
- ink/react-native useUIStream repair loops no longer accept lossy autofixes
unconditionally: lossless relocations apply immediately, pruned content
holds back while retries remain (so validation fails and the model repairs
the missing elements) and applies only as a last resort.
- FILTERED LISTS prompt rule removed from schemas whose renderers do not
implement the per-item filter yet (everything except react). Renderer
parity tracked as follow-up.
- repeat_state_mismatch validation reuses getByPath instead of a local JSON
Pointer lookup that skipped ~0/~1 unescaping.
* Address review: split mixed repeat visibility, apply lossless fixes eagerly
- splitRepeatVisibility (core, exported): AND-composed conditions on a repeat
container partition into a container gate ($state conjuncts, hides the
shell) and a per-item filter ($item/$index conjuncts). Mixed $or cannot
partition soundly and stays fully per-item, documented.
- react renderer uses the split, so {$and: [{$state gate}, {$item filter}]}
hides the empty shell when the gate is false instead of rendering a husk.
- autoFixSpec gains { lossy?: boolean } (default true, additive): ink and
react-native repair loops now apply lossless relocations immediately and
withhold only the pruning until retries are exhausted, matching the stated
intent.
* Address review: RN final-validation error path, repeat prune guard, docs
- react-native useUIStream mirrors ink: when retries are exhausted and the
spec still fails validation, report through onError instead of silently
calling onComplete with an invalid spec.
- autoFixSpec never prunes a repeat container to zero children; that would
trade missing_child for repeat_without_children and leave the last-resort
spec unrenderable. The dangling template reference stays visible to repair.
- Docs for the new surface: core README + skill (validateSpec issue codes,
fixDetails, lossy option), react README + skill and web visibility docs
(filtered-list pattern, mixed-condition splitting, framework support note).
* Fix visible validation depending on consumer zod version; strengthen children prompt rule
catalog.validate() behavior changed under consumers' zod resolution: z.any()
object keys are optional on zod 4.3 but nonoptional on zod 4.4+, so a spec
omitting an element's visible field validates on 4.3 and fails on 4.4. The
core test suite (zod 4.3.6) asserts the optional behavior, so optional is the
intent; pin it explicitly with .optional() so all zod 4.x agree.
children stays required (long-standing, zod-version-independent contract;
relaxing it would change InferSpec types for consumers). Instead the default
prompt rules now state explicitly that every element must include a children
array, with [] for leaves, which benchmarking shows models otherwise omit on
roughly a third of first attempts.
- core: InferSpecObject honors SchemaType.optional at the type level (additive;
no schema used optional before)
- all framework schemas: visible marked ...s.optional()
- framework prompt defaultRules: REQUIRED FIELDS rule for children
- core: regression tests locking visible-optional and children-required
* Fix Next schema optional fields
Bump all @json-render/* packages to 0.19.0, add changelog entry for
custom directives API and @json-render/directives package, and update
the web app changelog page.
* feat: add @json-render/ink terminal renderer and ink-chat example
Adds a new `@json-render/ink` package that brings json-render specs to
terminal UIs via Ink (React for CLIs). Includes 24 standard components
(layout, text, inputs, markdown, etc.), context providers for state,
validation, visibility, actions, focus, and repeat scopes, plus a
streaming JSONL hook for progressive spec rendering.
Also adds an `ink-chat` example app demonstrating an AI chat interface
in the terminal with streaming responses, tool calls, and interactive
wizard flows.
Includes 76 tests (24 unit + 52 e2e), docs page, and web app integration.
* feat: show live spec preview during streaming
Render the spec progressively as JSONL patches arrive instead of only
showing a spinner. The preview disappears when streaming completes and
the finalized message replaces it in history.
* feat: clip streaming preview to 6 lines
* refactor: move spinner into input box, show full streaming preview
* fix: skip spacer during streaming to prevent clipping tall previews
* fix: strip invisible colors on dark terminal backgrounds
Drop foreground colors like "black" and "#000000" from AI-generated
specs so text remains readable on dark terminals. Removed hardcoded
color="black" from Badge and added safeColor() guard to all components
that accept user-specified color props.
* fix: always show spacer to keep input pinned to bottom
* fix: show dash placeholder for empty values in Table and KeyValue
Empty or null values in Table cells and KeyValue now render as "—"
instead of blank space. Also removed dimColor from ListItem subtitle
and trailing for better readability on dark terminals.
* fix: division by zero in Sparkline sampling when maxWidth is 1
* fix: Review feedback
Signed-off-by: Alexis Rico <sferadev@gmail.com>
* fix: Update readme
Signed-off-by: Alexis Rico <sferadev@gmail.com>
---------
Signed-off-by: Alexis Rico <sferadev@gmail.com>
Chris Tate