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

• release: prepare v0.8.0 — bundle post-prep PRs (#111–#116) (#117)

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

@lbliii

---

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)

• 2f8ce28 release: prepare v0.7.0 — strict-by-default, agent-UX hints, render-surface hardening (#108) — @lawrence Lane

Contributors

@lbliii

---

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 components CLI command, type-aware
  prop validation with TypeMismatch diagnostics, Components Guide and Jinja2-vs-Kida comparison
  docs. (#90)
• kida readme CLI — Auto-generates README.md from project metadata (pyproject.toml, filesystem,
  git). Ships 4 preset templates (default, minimal, library, cli) with --set overrides and --json
  debug mode. (#89)

Fixed

• Sandbox max_output_size enforcement — 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 RuntimeError raises replaced with TemplateRuntimeError. (#91)
• Optional chaining display — ?. renders "" instead of "None" in display context. (#91)
• Broken except clauses — Fixed 32 except 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, and MigrationWarning
  (K-WARN-002) for common migration traps and silent coercion. (#91)
• strict_undefined mode — Opt-in Environment(strict_undefined=True) for catching attribute
  typos at render time. (#92)
• UndefinedError context — 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

1. No breaking changes. Drop-in upgrade from 0.5.x.
2. New warnings (PrecedenceWarning, CoercionWarning, MigrationWarning) may surface in code that previously ran silently. These are Python warnings and can be filtered with warnings.filterwarnings.
3. GitHub Action version tag updated to @v0.6.0.

Links

• PyPI
• GitHub
• Full Changelog

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

• tojson attribute mode — {{ value | tojson(attr=true) }} HTML-entity-encodes JSON for safe
  use in double-quoted HTML attributes (e.g. Alpine x-data). Default tojson behavior is
  unchanged for <script> tags and JSON-in-script contexts. (#81)
• plain() t-string tag — New plain(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.join as local variable and enable built-in pure filter folding for
  faster template compilation. (#80)
• Dispatch-dict compiler refactor — Expression compilation in _compile_expr now 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-artifact to v7, actions/setup-python to v6,
  and actions/download-artifact to v8.

Upgrade Notes

1. No breaking changes. Drop-in upgrade from 0.4.x.
2. GitHub Action version tag updated to @v0.5.0.

Links

• PyPI
• GitHub
• Full Changelog

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_context are now correctly folded at compile time. Types that Python's compile() rejects
  in ast.Constant nodes 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 raise UndefinedError. The CSE optimisation previously
  hoisted the variable lookup to function entry, before _slot_kwargs were pushed onto the scope
  stack. Slot bodies are now excluded from eager caching. (#70)

Upgrade Notes

1. No breaking changes. Drop-in upgrade from 0.4.0.
2. GitHub Action version tag updated to @v0.4.1.

Links

• PyPI
• GitHub
• Full Changelog

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 generates gettext/ngettext calls. (#61)
• Babel extraction — kida.babel.extract entry point lets pybabel extract pull translatable
  strings from Kida templates. (#63)
• kida i18n CLI — kida i18n extract and kida i18n analyze commands 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 --optimize CLI — 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_eval and related environment options. (#64)

Upgrade Notes

1. No breaking changes. Drop-in upgrade from 0.3.4.
2. Partial evaluation is opt-in — enable with Environment(partial_eval=True).
3. i18n requires no new dependencies; Babel integration is optional.
4. GitHub Action version tag updated to @v0.4.0.

Links

• PyPI
• GitHub
• Full Changelog

kida-templates Added Changed Deprecated Removed Fixed Security 0.3.4

v0.3.4

Released 2026-04-09.

Kida 0.3.4 adds parent-to-child render context with provide/consume, fixes the ~ operator
to preserve Markup safety, and ships agentic comment templates for the GitHub Action.

Highlights

• provide/consume render context — Pass state from parent components to children across slot boundaries without prop drilling.
• Markup-aware ~ operator — Concatenating Markup values no longer double-escapes HTML.
• Agentic comment templates — GitHub Action gains release notes rendering across multiple surfaces.

Added

Components

• provide/consume primitives — {% provide key = expr %} sets a value in the render
  context that any descendant can read with consume("key"). Stack-based nesting with try/finally
  cleanup ensures proper scoping even when errors occur.

GitHub Action

• Agentic comment templates — Support for agentic comment rendering and release notes generation
  across multiple surfaces (PR comments, step summaries, changelog).
• Release notes action — Multi-surface rendering with rich data collection for automated
  release documentation.
• AMP protocol documentation — Agent template site docs covering the AMP protocol.

Fixed

• Markup-aware ~ operator — code(x) ~ " " ~ copy_button(x) no longer double-escapes HTML.
  The ~ operator now checks whether operands are Markup instances and preserves safety
  accordingly. Also fixes the + operator's string concatenation branch.
• GitHub Action description — Shortened action.yml description to meet GitHub's 125-character
  limit.

Changed

• README — Slimmed down README and promoted Render Anywhere as the hero section.

Upgrade Notes

1. No breaking changes. Drop-in upgrade from 0.3.3.
2. GitHub Action version tag updated to @v0.3.4.

Links

• PyPI
• GitHub
• Full Changelog

kida-templates 0.3.3

v0.3.3

Released 2026-04-07.

Kida 0.3.3 adds JSON/YAML syntax highlighting for terminal output, enables CI report
posting as PR comments, and fixes a cache miss tracking bug.

Highlights

• syntax() terminal filter — Regex-based JSON and YAML highlighting in terminal mode.
• PR comment CI reports — GitHub Action now posts reports as pull request comments.
• CachedBlocksDict fix — Cache miss tracking corrected with expanded test coverage.

Added

Terminal

• syntax() filter — Regex-based syntax highlighting for JSON and YAML content in terminal
  rendering mode. Applies color tokens to keys, strings, numbers, and structural characters.

GitHub Action

• PR comment posting — post-to: pr-comment posts rendered reports directly to pull requests
  in addition to step summaries.
• Comment deduplication — comment-header identifies comments by report type so re-runs
  update the existing comment instead of creating duplicates.
• Append mode — comment-mode: append combines multiple reports (e.g., pytest + coverage)
  into a single PR comment separated by horizontal rules.
• Extra context — context input accepts a JSON string of additional template variables
  merged into the data context at render time.

Fixed

• CachedBlocksDict miss tracking — Block lookups that miss the cache are now properly
  recorded. Added comprehensive test coverage for cached blocks, purity checks, and t-strings.

Upgrade Notes

1. No breaking changes. Drop-in upgrade from 0.3.2.
2. GitHub Action version tag updated to @v0.3.3.

Links

• PyPI
• GitHub
• Full Changelog

kida-templates 0.3.2

v0.3.2

Released 2026-04-03.

Kida 0.3.2 deepens compile-time optimization, modernizes internals for Python 3.14, and
consolidates AST traversals for faster compilation.

Highlights

• Expanded partial evaluator — Handles more node types for deeper compile-time constant folding.
• Python 3.14 patterns — @final on key classes, match statements, stricter linting.
• Consolidated traversals — Single-pass dependency analysis, cached AST in bytecode cache.
• New CLI commands — kida explain shows active optimizations; kida bench measures performance.

Added

CLI

• kida explain — Print which compile-time optimizations are active for a template (f-string
  coalescing, dead code elimination, partial evaluation, component inlining, free-threading).
• kida bench — Quick benchmarking command for template compile and render performance.

Compiler

• Expanded partial evaluator — Now handles Def, FuncCall, MarkSafe, NullCoalesce,
  OptionalFilter, SafePipeline, Slot, and SlotBlock nodes. Templates with static context
  see more expressions resolved to constants before codegen.
• Partial eval benchmarks — Dedicated benchmark suite for measuring partial evaluation speedups.
• Terminal benchmarks — Dedicated benchmark suite for terminal rendering mode.

Documentation

• Kida vs Jinja2 comparison — Side-by-side document covering syntax, architecture, performance,
  and feature differences.

Changed

• Python 3.14 modernization — @final decorators on key classes; match statements replace
  if/elif chains in the partial evaluator; stricter ruff linting rules.
• Consolidated AST traversals — Dependency analysis merged into a single-pass visitor.
• Cached AST in bytecode cache — Parsed AST stored alongside compiled code for faster
  recompilation.
• Render helper consolidation — Deduplicated patterns in render_helpers.py and
  render_context.py.
• README rewrite — Concise, feature-focused README with architecture overview.
• Import path cleanup — TemplateSyntaxError imported from kida.exceptions.

Removed

• analysis/visitor.py — Consolidated into analysis/node_visitor.py.

Upgrade Notes

1. No breaking changes. Drop-in upgrade from 0.3.1.
2. If you import TemplateSyntaxError from kida.environment.exceptions, that path still works
   but kida.exceptions is now preferred.
3. GitHub Action version tag updated to @v0.3.2.

Links

• PyPI
• GitHub
• Full Changelog

kida-templates 0.3.0

v0.3.0

Released 2026-03-26.

Kida 0.3.0 is a major feature release introducing terminal rendering mode, framework integrations
for Flask/Starlette/Django, a sandboxed environment, template coverage, accessibility linting,
a template formatter, and an extension/plugin architecture.

Highlights

• Terminal rendering mode — Environment(autoescape="terminal") enables declarative CLI/TUI
  output with ANSI-safe escaping, 30+ terminal filters, built-in components, and color depth
  fallback.
• Framework integrations — Drop-in kida.contrib adapters for Flask, Starlette/FastAPI, and
  Django.
• Sandbox — SandboxedEnvironment with configurable security policies for untrusted templates.
• Coverage — CoverageCollector tracks template line execution with LCOV/Cobertura export.
• Accessibility linting — Static checks for img-alt, heading-order, html-lang,
  input-label.
• Template formatter — kida fmt for opinionated template formatting.
• Extensions — Plugin architecture for custom tags with Extension base class.

Added

Terminal Rendering

• autoescape="terminal" — One flag activates terminal mode with ANSI-safe escaping.
• 30+ terminal filters — Colors (fg, bg, bold, dim, italic, underline), layout
  (table, tree, cols, rule), data (badge, diff, progress, sparkline), and more.
• Built-in components — panel, header, footer, connector, row, cols, rule,
  banner — all width-aware with truncation safety.
• WidthStrategy — Configurable character width handling with terminal probe auto-detection,
  wcwidth support, and East Asian ambiguous width setting.
• Color depth fallback — fg()/bg() degrade gracefully across truecolor, 256-color, basic,
  and no-color terminals.
• LiveRenderer — In-place terminal re-rendering with Spinner animation support.
• stream_to_terminal() — Progressive chunk-by-chunk terminal output.
• Responsive stack() — Side-by-side when terminal is wide, stacked when narrow.
• kida render CLI — kida render template.txt --data context.json [--stream].
• Icon/box-drawing sets — Unicode and ASCII degradation with VS15 text presentation selectors.

Framework & Security

• kida.contrib.flask — Flask integration adapter.
• kida.contrib.starlette — Starlette/FastAPI integration adapter.
• kida.contrib.django — Django template backend.
• SandboxedEnvironment — Restricts collection methods to read-only by default; call-time
  safety checking blocks unsafe types; allow_mutating_methods and allow_calling allowlists.
• CSP nonce support — inject_csp_nonce() and csp_nonce_filter for Content Security Policy.

Tooling

• CoverageCollector — Tracks template line execution with LCOV and Cobertura output.
  Thread-safe with module-level locking for concurrent usage.
• Accessibility linting — img-alt, heading-order, html-lang, input-label checks.
• Template type checker — {% template %} declarations for context type annotations.
• Template formatter — kida fmt with configurable blank lines and indentation.
• Extension architecture — Extension base class with node_types registration and compiler
  dispatch via _extension_compilers.
• Content stacks/portals — {% push %} / {% stack %} for CSS/JS aggregation.
• StreamTransform — Progressive rendering transform for streaming output.
• Unified NodeVisitor/NodeTransformer — MRO-aware dispatch cache.

Changed

• Immutable AST — Frozen-dataclass nodes with structural equality.
• RenderContext — Free-threading safe, no shared mutable state.
• Exception hierarchy — Extracted to kida.exceptions with source-context-aware error classes.
• Compiler optimizations — Constant folding, output coalescing, copy-on-write AST transforms,
  hoisted dispatch tables, compile-time rebinding tracking.

Upgrade Notes

1. No breaking template or API changes for existing render() / get_template() usage.
2. Terminal mode is opt-in via autoescape="terminal" or terminal_env().
3. Framework adapters are in kida.contrib — import and configure for your framework.
4. SandboxedEnvironment is a drop-in replacement for Environment when running untrusted templates.

Links

• PyPI
• GitHub
• Full Changelog