Releases: lbliii/kida
Release list
kida-templates 0.12.0
v0.12.0
Released 2026-07-13.
Kida 0.12.0 gives frameworks and developer tools stronger compile-time facts.
Blocks and fragments can carry typed literal metadata, diagnostics have a
public programmatic model with JSON and SARIF surfaces, and safe edits can be
applied only when their source snapshot still matches. The release also
expands Kida's Python 3.14t evidence and keeps the runtime dependency-free.
Added
Literal block and fragment metadata
- Framework-owned modifiers —
{% block chart enhanced="sse" fallback="table" %}and{% fragment updates transport="sse" %}attach
ordered literal metadata to existing render units. - Typed, source-located introspection —
BlockMetadata.modifierscontains
immutableBlockModifierMetadatarecords with scalar values and exact
declaration locations.get_modifier()provides direct lookup. - Compile-time rejection — Duplicate names, dynamic expressions,
collections, and malformed assignments fail during parsing. Kida validates
the generic shape only; frameworks own their supported vocabulary. - No render or cache drift — Modifiers do not alter rendered bytes,
dependency analysis, inheritance, composition, or structural block hashes.
Programmatic diagnostics
- Public diagnostic model —
kida.diagnosticsexposes immutable findings,
source spans, confidence, related locations, snippets, and reports for
editors and framework adapters without giving policy decisions to the model. - Unsaved-source diagnosis —
diagnose_source()analyzes an editor buffer
directly, whilediagnose_directory()matcheskida checkcollection. - Machine-readable CLI output —
kida check --format text,json, and
sarifshare one deterministic, deduplicated collection and preserve the
existing0/1/2exit policy. - Verified safe edits — Strict unified closers can carry exact replacements.
apply_safe_edits()rejects stale, incomplete, and overlapping edits before
changing source; advisory migrations remain non-fixing. - Extension diagnostics — Namespaced
Extension.diagnose()hooks receive
immutable source, AST, and visible-component metadata. Invalid ownership,
locations, or snapshots are rejected, and extension failures make the report
partial instead of breaking rendering.
Migration and downstream evidence
- Block-sensitive Jinja migration warning — K-WARN-002 now detects a
{% set %}binding read after anif, including nested branches, named
blocks, and later reads in the same loop iteration. - Pinned downstream canaries — Report-only chirp-ui and Milo jobs prove
their Kida source override, run on Python 3.14t withPYTHON_GIL=0, and keep
public-fork permissions read-only.
Changed
- Release-note collection is typed — GitHub PR collection follows
pagination, validates its report contract, and fails explicitly for malformed
responses and invalid ref ranges. - CLI phases are smaller — Argument parsing, lazy dispatch, execution, and
presentation moved into command-owned modules behind the unchanged
kida.cli:mainentry point. - Compiler phases are explicit — Lowering, callable plans, block variants,
analysis, and partial-evaluation tests are split into focused modules while
retaining generated-output and render-surface parity. - Free-threading claims link evidence — Public docs name the no-GIL PR lane,
scheduled seeded stress window, stable loader-source boundary, and read-only
metadata boundary.
Fixed
- Shared analyzers isolate traversal state — Concurrent analysis no longer
shares mutable walker state across calls. - Migration warnings match Jinja scope — Outer-name shadows inside
non-scopingifblocks warn; loop-localforassignments no longer produce
the same false positive. - Live updates serialize publication — Terminal live rendering protects
shared update state on free-threaded builds. - Streaming block fallbacks stay intact — Error boundaries inside named
blocks preserve fallback behavior on synchronous and asynchronous surfaces.
Upgrade Notes
- No existing template needs to add modifiers. Unannotated block and fragment
syntax compiles and renders as before. - Frameworks should read
BlockMetadata.modifiers; do not parse template
source or comments as a parallel metadata channel. - Modifier values are literal strings, integers, floats, booleans, or
None.
Put runtime decisions in template expressions or framework code instead. - Consumers that snapshot
kida.__all__orBlockMetadatafields should add
BlockModifierMetadataandmodifiers. - Diagnostic consumers should branch on stable codes and structured fields,
not rendered terminal wording.
Downstream checkpoint
Chirp's adapter pilot failed on Kida 0.11 because modifier syntax could not
compile and passed against the 0.12 candidate with typed block/fragment
metadata plus byte-identical full and block rendering. Chirp still owns its
enhancement vocabulary, fallback graph, severity policy, and browser-level
no-JavaScript proof; Kida does not assign those semantics.
kida-templates 0.11.0
v0.11.0
Released 2026-07-07.
Kida 0.11.0 is a checkpoint release for the server-side component system. It
makes the existing-framework path runnable and tested, hardens release and CI
gates, and splits the largest partial-evaluation phases into focused modules
without changing Kida's public API or runtime dependency contract.
Added
- Framework-first quickstarts — Current Flask, Django, and FastAPI/Starlette
guides now show typed components, full-page rendering, named fragment routes,
form handling, and the Jinja2 scoping migration path. - Runnable integration examples — Flask, Django, and FastAPI component apps
exercise real framework clients, fragment rendering, and output escaping in
the standard test suite. - Pyodide playground direction — The planning record now recommends a
worker-isolated, JSON-context browser playground, with compatibility and
safety gates required before implementation.
Changed
- Component-first product documentation — The README, package metadata,
landing page, and documentation navigation now lead with typed props, named
slots, and static call validation rather than generic template-engine copy. - Python components ecosystem framing — Public pages no longer present
Bengal as the identity of the stack. Bengal remains the current documentation
build tool and a supported legacy integration while the broader stack evolves. - Phase-owned partial evaluation — Constant folding, dead-code elimination,
expression transforms, loop unrolling, component inlining, and temporary-node
flattening now live in focused modules. The main evaluator fell from 2,307 to
1,247 lines, with free-threaded stability and benchmark gates unchanged. - One authoritative CI contract — Local and CI Ruff scopes now agree, public
examples run in the standard suite, and duplicate type-check lanes were
consolidated into the report-producingType Check (ty)job. - Release automation fails early —
make gh-releaseverifies a clean tree,
the exact remotemaincommit, curated release notes, and tag consistency
before creating a release that triggers trusted PyPI publishing.
Fixed
- Published install commands use the real distribution name — Site snippets
installkida-templates; Python code continues toimport kida. - Design-system example imports components correctly — The example uses
explicit{% from ... import ... %}declarations instead of relying on
isolated{% include %}scope. - Fallback failures are diagnosable — Cache cleanup, loader discovery,
README detection, terminal width, and related best-effort paths retain their
graceful behavior while exposing useful debug context.
Upgrade Notes
- No runtime API, template syntax, or CLI migration is required from 0.10.x.
- Install with
uv add kida-templatesorpip install kida-templates; import
the package askida. - Python 3.14 remains the minimum supported version, with Python 3.14t used for
the project's free-threaded verification and release gates. - Framework integrations remain optional development/test dependencies. The
installed Kida runtime still has zero dependencies.
Why this checkpoint
The work since 0.10.0 strengthens adoption and maintainability rather than
expanding public surface area. Publishing now gives framework users a stable,
tested checkpoint before the surrounding stack shifts into its next phase.
kida-templates 0.10.0
v0.10.0
Released 2026-05-30.
Kida 0.10.0 is a focused diagnostics release. It gives framework debug pages a
structured error payload for undefined values, tightens source attribution across
optimized and streaming render paths, and keeps the broader large-app roadmap out
of this release until its public contracts are ready.
Added
- Structured undefined diagnostics -
UndefinedError.to_diagnostic()returns
a surface-neutral payload with code, kind, location, source snippet, ordered
hints, docs URL, metadata, template stack, and component stack. - HTML and Markdown diagnostic renderers - The diagnostic payload can render
escaped HTML fragments/pages or GitHub-flavored Markdown without downstream
frameworks parsing terminal-formatted exception strings.
Fixed
- Optimized templates keep source locations - F-string coalescing preserves
the template line marker used by undefined diagnostics, so optimized output
still points at the source line users can edit. - Imported component slot failures point at caller source - Errors raised
inside slot bodies passed to imported components now report the caller template
as the primary diagnostic location while retaining component-stack context. - Streaming runtime errors match full render diagnostics - Generic Python
exceptions raised during streaming are wrapped with template name and line
information consistently with full render.
Upgrade Notes
- Framework debug pages should prefer
UndefinedError.to_diagnostic()over
parsingstr(exc)orformat_compact(). - If a test expected raw exceptions from async streaming, update it to assert
TemplateRuntimeErrorand inspect__cause__for the original exception. - If you maintain compiler AST snapshots, regenerate them for the coalescing
line-marker contract.
Why this change
Kida's diagnostic strings are optimized for terminal output. Frameworks need the
same facts as plain data so they can render their own debug UI safely. This
release makes undefined errors inspectable without scraping styled terminal
text, and it closes a few attribution gaps that made optimized or streaming
renders harder to debug than full renders.
kida-templates 0.9.0
0.9.0 (2026-05-10)
+5055 / -926 across 167 files
New Features
- feat: add large app ergonomics analysis (#129)
Details
## Summary
Bug Fixes
- fix: stop over-escaping inline chars in markdown autoescape (#119)
Details
## Summary
Documentation
- docs: add review packet adoption demos (#128)
Details
## Summary
- docs: sharpen adoption roadmap and validation (#127)
Details
## Summary
Maintenance
- chore(deps): Bump actions/upload-pages-artifact from 4 to 5 (#102)
Details
Bumps [actions/upload-pages-artifact](https://github.com/actions/upload\-pages\-artifact\) from 4 to 5.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a href="https://github.com/actions/upload\-pages\-artifact/releases\"\>actions/upload\-pages\-artifact's releases</a>.</em></p>
<blockquote>
Other Changes
- [codex] update agent steward system (#125)
Details
## Summary
- [codex] repair docs Pages build (#124)
Details
## Summary
- Upgrade Bengal docs dependency and switch CI to the current CLI (#123)
Details
## Summary
- Bumped the docs extra to `bengal>=0.3.2` and refreshed `uv.lock` to match.
- Updated docs build entrypoints to use the current Bengal CLI: `bengal build` and `bengal serve`.
- Updated GitHub Pages CI to build the site with `bengal build --environment production`.
- Harden report contracts across templates, schemas, markdown, and GitHub docs (#122)
Details
## Summary
- Added explicit report-contract metadata and inventory checks for built-in templates and snapshots.
- Added AMP fixture/schema validation, readability assertions, and a GitHub Action contract guard for PR comment markers and template-copy drift.
- Hardened markdown rendering for report-s...
- Set up AGENTS.md steward hierarchy for Kida (#121)
Details
## Summary
- Upgraded the root `AGENTS.md` into a compact repo constitution and routing guide.
- Added scoped steward files for the main Kida domains: runtime, parser, compiler, environment, analysis, terminal, markdown, tests, benchmarks, examples, docs, planning, site, templates, schemas, and GitH...
- Fix stale AST cache crash in fragile-path lint (#120)
Details
## Summary
- Version bytecode cache entries with a Kida cache ABI tag so old pickled ASTs are not reused after AST shape changes
- Reject incompatible cached ASTs at load time and fall back to recompilation instead of crashing the visitor
- Preserve `Filter.parenthesized` through partial evaluation ...
- Update README for clearer positioning and structure (#118)
Details
## Summary
- Reworked the README to lead with Kida’s core thesis: pure-Python components with static validation and free-threaded rendering.
- Moved static validation, use cases, and the Python 3.14t story earlier so the page reads as a product narrative instead of a feature dump.
- Updated examples...
Details
## Summary
Contributors
@app/dependabot |
@lbliii
Full diff: 0.8.0...0.9.0
kida-templates 0.8.0
0.8.0 (2026-04-24)
+4938 / -350 across 74 files
New Features
- feat: agent-UX — point K-PAR-001 end-tag errors at `kida check` (#112)
Details
## Summary
- feat: relative + alias template resolution (./, ../, @alias/) (#111)
Details
## Summary
- feat: v0.7.1 — warn-once, upgrade tutorial, null-safe hint (#109)
Details
## Summary
- Dedup the `from_string()`-without-`name=` UserWarning per distinct source per Environment (was firing ~1000× in a downstream suite).
- Add `docs/tutorials/upgrade-to-v0.7.md` with three fix patterns for strict-by-default, the escape hatch, and `?.` / `| get` idioms — cross-linked from R...
Other Changes
Details
## Summary
- Tighten benchmark suites and regression gating (#116)
Details
## Summary
- Split benchmark helper scripts into `core`, `product`, and `exploratory` suites, with `core` as the default CI/release path.
- Switch benchmark regression comparison to `median` by default and keep `mean` as an override for investigation.
- Batch the compile-pipeline benchmark so it mea...
- Add core benchmark regression probes (#115)
Details
## Summary
- Add a Kida-only regression benchmark suite for the hottest render, helper, escape, sandbox, and compile paths.
- Wire the new suite into the benchmark baseline and compare scripts so it participates in regular regression checks.
- Document the new suite in the benchmarks README.
- Update Kida component validation and stability gates (#114)
Details
## Summary
- Add public API, diagnostics, and component contract snapshot tests to freeze current framework behavior
- Tighten component validation and metadata coverage, including CLI JSON and imported def checks
- Add a stability gate workflow with package smoke testing and updated docs for releas...
- Update component validation and render parity (#113)
Details
## Summary
- Add structured component-call diagnostics with `K-CMP-*` codes and warning categories
- Validate literal `{% from "..." import ... %}` component calls across templates and surface them in the CLI
- Fix render-surface parity issues in sync, streaming, and async block/region compilation
-...
- release: v0.8.0 — ?. soft-on-mappings (#110)
Details
## Summary
- release: prepare v0.7.0 — strict-by-default (#108)
Details
## Summary
Contributors
Full diff: 0.7.0...0.8.0
kida-templates 0.7.0
0.7.0 (2026-04-20)
+6842 / -703 across 87 files
New Features
- feat: agent-UX — narrow {% set %} warning, parser trap hints, docs truth (#106)
Details
## Summary
- feat: reject non-top-level {% def %}/{% region %}, retarget Undefined hint (#100)
Details
## Summary
- Compile-time check (**K-TPL-004**) rejects `{% def %}` / `{% region %}` nested inside any control-flow construct (`if`, `for`, `with`, `provide`, `try`, `match`, `cache`, `capture`, `push`, `spaceless`, `filter`, `while`), where `_globals_setup` cannot bind the name for `render_block()`...
- feat: RenderCapture — block-level capture, search indexing, freeze cache (#99)
Details
## Summary
- feat: adopt Python 3.14+ patterns — TypedDict, match/case, slots (#98)
Details
## Summary
Bug Fixes
- fix: extend CoercionWarning to collection/number filters, add lint gates (#97)
Details
## Summary
- fix: suppress PrecedenceWarning when nullish fallback is parenthesized (#96)
Details
## Summary
- fix: bump action default python-version from 3.12 to 3.14 (#94)
Details
The release-notes workflow failed because the action's default `python-version` was `3.12`, but every `kida-templates` release on PyPI requires `>=3.14`. This bumps the default to `3.14` so `pip install kida-templates` succeeds.
Documentation
- docs: add AGENTS.md — contributor safety/values guide (#104)
Details
## Summary
Adds `AGENTS.md` at the repo root as a contributor-facing values/safety guide, complementing `CLAUDE.md` (tactical syntax/API reference). Covers Kida's north star (component model in pure Python, statically validated, on free-threaded 3.14t), design philosophy, blast radius by subsystem, ...
Refactoring
- refactor: leaf-node hardening — bug fixes, dead code, test gap closure (#105)
Details
## Summary
Other Changes
- feat!: flip strict_undefined default to True (#107)
Details
## Summary
- Render-surface hardening: parity corpus, fragment scaffold, sandbox fuzz (#103)
Details
## Summary
- **Sprint 1 — parity corpus.** 32-case corpus across 7 render methods pins three latent bugs (def-as-generator in full streams, let-cellvar in async block stream, region returning async_generator) under strict xfail so any fix flips XPASS → FAIL.
- **Sprint 2 — fragment scaffold.** `rend...
- release: prepare v0.6.0 — version bump, changelog, and docs (#93)
Details
## Summary
Direct commits (1)
Contributors
Full diff: 0.6.0...0.7.0
kida-templates 0.6.0
v0.6.0
Released 2026-04-13.
Kida 0.6.0 evolves Kida from a template engine into a component framework with full def introspection, typed prop validation, and the kida components CLI. This release also adds the kida readme auto-generator and closes dozens of silent-failure and missing-validation sharp edges.
Added
- Component framework — Def introspection API (
DefMetadata,DefParamInfo,list_defs,
def_metadata), component call stack in error reporting,kida componentsCLI command, type-aware
prop validation withTypeMismatchdiagnostics, Components Guide and Jinja2-vs-Kida comparison
docs. (#90) kida readmeCLI — Auto-generates README.md from project metadata (pyproject.toml, filesystem,
git). Ships 4 preset templates (default, minimal, library, cli) with--setoverrides and--json
debug mode. (#89)
Fixed
- Sandbox
max_output_sizeenforcement — Was declared but never checked; now enforced. (#91) - Block capture rejection —
{% set x %}...{% endset %}block capture rejected at parse time. (#91) - Error codes for all SecurityError raises — K-SEC-001 through K-SEC-005. (#91)
- Autoescape validation at construction — Invalid mode rejected at
Environment()creation. (#91) - Structured errors — All bare
RuntimeErrorraises replaced withTemplateRuntimeError. (#91) - Optional chaining display —
?.renders""instead of"None"in display context. (#91) - Broken
exceptclauses — Fixed 32except X, Y:clauses (Python 2 syntax). (#92) render_with_blocks()validation — Unknown block names raise with did-you-mean suggestions. (#92)- Unknown compiler node types — Now raises instead of silently ignoring. (#92)
- CLI check error reporting — Errors no longer swallowed silently. (#92)
_Undefined.get()API — Fixed to match expected semantics. (#92)
Changed
- New warnings —
PrecedenceWarning(K-WARN-001),CoercionWarning, andMigrationWarning
(K-WARN-002) for common migration traps and silent coercion. (#91) strict_undefinedmode — Opt-inEnvironment(strict_undefined=True)for catching attribute
typos at render time. (#92)UndefinedErrorcontext — Attribute/key lookups now say "Undefined attribute/key" instead of
"Undefined variable". (#92)- ErrorCode coverage — Pushed from 21 to 73+ raise sites with docs for all 38 ErrorCode
values. (#91)
Upgrade Notes
- No breaking changes. Drop-in upgrade from 0.5.x.
- New warnings (
PrecedenceWarning,CoercionWarning,MigrationWarning) may surface in code that previously ran silently. These are Python warnings and can be filtered withwarnings.filterwarnings. - GitHub Action version tag updated to
@v0.6.0.
Links
kida-templates 0.5.0
v0.5.0
Released 2026-04-12.
Kida 0.5.0 is a minor release adding the tojson(attr=true) attribute mode, the plain() t-string tag, Milo integration, GitHub App token support, and compile-time performance improvements.
Added
tojsonattribute mode —{{ value | tojson(attr=true) }}HTML-entity-encodes JSON for safe
use in double-quoted HTML attributes (e.g. Alpinex-data). Defaulttojsonbehavior is
unchanged for<script>tags and JSON-in-script contexts. (#81)plain()t-string tag — Newplain(t"...")tag for t-string inline templates that renders
without HTML escaping. (#84)- Kida x Milo integration — Saga benchmarks, terminal tutorial, and vision rewrite for the Milo
integration layer. (#85) - GitHub App token support — Branded PR comments now support GitHub App tokens for
authentication. (#83)
Fixed
- Partial evaluator preserves loop var bindings — Unrolled
for-loops no longer lose loop
variable bindings when the partial evaluator inlines the loop body. (#78, #79)
Changed
- Performance — Cache
str.joinas local variable and enable built-in pure filter folding for
faster template compilation. (#80) - Dispatch-dict compiler refactor — Expression compilation in
_compile_exprnow uses a dispatch
dictionary instead of if/elif chains. (#87) - Documentation audit — Comprehensive accuracy, IA, and completeness pass across all docs. (#86)
- CI dependency bumps — Updated
actions/upload-artifactto v7,actions/setup-pythonto v6,
andactions/download-artifactto v8.
Upgrade Notes
- No breaking changes. Drop-in upgrade from 0.4.x.
- GitHub Action version tag updated to
@v0.5.0.
Links
kida-templates 0.4.1
v0.4.1
Released 2026-04-10.
Kida 0.4.1 is a patch release with two bug fixes for the partial evaluator and scoped slot bindings
introduced in v0.4.0.
Fixed
- Partial evaluator folds all static_context types — Dicts, lists, and custom objects from
static_contextare now correctly folded at compile time. Types that Python'scompile()rejects
inast.Constantnodes are emitted as precomputed module-level bindings (_pc_N), injected into
the exec namespace at template load time. (#68) - Scoped slot
let:bindings with repeated references —let:binding variables that appear
more than once in a slot body no longer raiseUndefinedError. The CSE optimisation previously
hoisted the variable lookup to function entry, before_slot_kwargswere pushed onto the scope
stack. Slot bodies are now excluded from eager caching. (#70)
Upgrade Notes
- No breaking changes. Drop-in upgrade from 0.4.0.
- GitHub Action version tag updated to
@v0.4.1.
Links
kida-templates Added Changed Deprecated Removed Fixed Security 0.4.0
v0.4.0
Released 2026-04-10.
Kida 0.4.0 is the biggest feature release since the project's inception — list comprehensions,
error boundaries, i18n with Babel extraction, scoped slots, and a two-phase partial evaluator
that widens the compile-time optimization surface.
Highlights
- List comprehensions —
[x.name for x in users if x.active]works natively in template expressions. - Error boundaries —
{% boundary %}blocks catch render errors and fall back to safe defaults without aborting the whole page. - i18n
{% trans %}blocks — Full internationalization support with pluralization, variable interpolation, and Babel-compatible message extraction. - Scoped slots — Components can expose data back to the caller via
{% slot name expose x, y %}. - Two-phase partial evaluator — Constant folding, dead branch elimination, and loop unrolling at compile time for measurable render speedups.
Added
Expressions
- List comprehensions —
[expr for var in iterable if condition]with full parser, compiler,
analysis (dependency tracking, purity), and CLI integration. (#62)
Template Control Flow
- Error boundaries —
{% boundary %}...{% fallback %}...{% endboundary %}catches exceptions
during rendering and substitutes fallback content. Integrates with the environment's error handler. (#61) - Scoped slots —
{% slot name expose x, y %}lets parent components bind slot-exposed variables,
enabling inversion-of-control patterns. (#61)
Internationalization
{% trans %}/{% pluralize %}blocks — Mark translatable strings with variable interpolation
and plural forms. The compiler generatesgettext/ngettextcalls. (#61)- Babel extraction —
kida.babel.extractentry point letspybabel extractpull translatable
strings from Kida templates. (#63) kida i18nCLI —kida i18n extractandkida i18n analyzecommands for standalone message
extraction and translation coverage analysis. (#63)- Analysis integration — i18n analysis module tracks translatable strings, detects missing
translations, and integrates with the dependency and purity analyzers. (#63)
Compiler
- Partial evaluator phase 1 — Constant folding, filter inlining for pure built-in filters,
dead branch elimination, and loop unrolling for small static iterables. Configurable via
Environment(partial_eval=True)with per-strategy controls. (#64) - Partial evaluator phase 2 — Extends optimization to conditional expressions, nested structures,
string operations, comprehension folding, and cross-block constant propagation. (#65) kida compile --optimizeCLI — Inspect the optimized AST and see before/after comparisons. (#64, #65)
Changed
- Performance docs — Updated to cover partial evaluation strategies and benchmarks. (#64)
- Compiler docs — New sections on the optimization pipeline and custom filter purity. (#64)
- Configuration docs — Documents
partial_evaland related environment options. (#64)
Upgrade Notes
- No breaking changes. Drop-in upgrade from 0.3.4.
- Partial evaluation is opt-in — enable with
Environment(partial_eval=True). - i18n requires no new dependencies; Babel integration is optional.
- GitHub Action version tag updated to
@v0.4.0.