Next Release PRD

This document tracks the next pre-alpha release after v0.1.0-alpha.4. Alpha.4 proved the first app/content declaration layer, direct panel and tab targeting, shell/content key validation, model-backed content builders, and release automation. The next release should reduce the remaining app-local orchestration that still makes real examples too large.

Release Theme

Ship a coherent app-shell declaration release:

1. make common lazy-cuh apps feel declared instead of hand-wired,
2. reduce the number of concepts needed before rendering a useful shell,
3. keep advanced primitives available through package paths,
4. make examples read like framework usage, not framework internals.

This is still pre-alpha. Prefer cleaner public API shape over compatibility when a boundary, name, or composition model is wrong.

Current Problem

The framework has strong primitives, but app authors still need to wire too many runtime details themselves:

• shell declarations,
• content slots,
• widget creation,
• action maps,
• keybars and help views,
• focus graph behavior,
• Textual bindings,
• modal editing callbacks,
• option state updates.

The full demo has improved, but it is still too large for the amount of UI it shows. That is a product signal: the framework exposes useful lower-level parts, but the recommended app-author path is not high-level enough yet.

Goals

1. Coherent App Shell API

Refine lc.composition.app into the recommended entry point for common apps.

The target shape should be close to:

import lazy_cuh as lc

app = lc.composition.app.declare(...)

The app declaration should derive or own the common runtime wiring for:

• shell panels and tabs,
• content declarations and widget ids,
• shell and content navigation presets,
• action metadata,
• keybar and keybinding help projections,
• modal entry points for editable options,
• Textual adapter creation.

Lower-level APIs should remain available as escape hatches, but examples should not require them for ordinary use.

2. Smaller Typed Content Declarations

Make common content declarations smaller and more typed.

The next release should improve declarations for:

• list content,
• tree content,
• text content,
• editable options.

Option declarations should stay especially ergonomic: field name, value, parser or value type, validation, and edit behavior should be enough for simple cases.

3. Example Size Reduction

Refactor examples around progressive complexity:

• minimal list app,
• tree app,
• editable options app,
• shell app with direct panel and tab targeting,
• help/keybar behavior app,
• full demo as a richer showcase.

The full demo may remain larger, but repeated orchestration should move into framework helpers.

4. Documentation Alignment

Docs should present the layered model clearly:

1. declare content,
2. declare shell,
3. attach behavior,
4. run through Textual adapters,
5. drop to lower layers only when needed.

Contributor docs should keep internals and architecture. User guides should start with the recommended app declaration path.

5. View Settings Direction

Document the intended app/panel/tab/content settings cascade so presentation defaults do not grow as one-off keyword arguments.

The next release includes the first cascade slice: app-shell defaults, panel-level overrides, tab-level overrides, and content-slot overrides through ViewSettings. Common view settings should be built through lc.builders.view helpers in guides and examples, with ViewSettings remaining the explicit model for advanced use.

Non-Goals

• Stable API compatibility.
• Domain-specific application behavior.
• A custom rendering engine outside Textual.
• Full text editing or insert mode.
• Replacing Textual’s app lifecycle.
• Reworking release automation unless it blocks this release.

API Principles

• Prefer import lazy_cuh as lc with domain package paths.
• Keep pure models free of Textual imports.
• Keep Textual widgets as runtime adapters.
• Make presets ordinary values that apps can inspect and replace.
• Make validation explicit and callable.
• Optimize for app-author concept count and example size.
• Avoid app authors needing raw widget ids unless they are doing advanced work.

Acceptance Criteria

The release is ready when:

• A small two-panel shell app can be declared with substantially less glue than the alpha.4 demo.
• Editable options can use modal editing without app-local parser/validation plumbing for common value types.
• Direct panel/tab targeting remains available through declarations.
• Compact keybars stay sparse; expanded help shows hidden/common movement.
• Examples are updated to show the recommended path first.
• Public exports are updated intentionally and covered by snapshot tests.
• Docs explain the app declaration layer and link to lower layers.
• Release checks pass: tests, lint, type checks, docs check, package build, and twine check.

Ergonomics Budget

Use these as review targets:

• minimal list app: 20-40 lines,
• tree example: 35-60 lines,
• editable options example: 45-75 lines,
• two-panel shell example: 55-90 lines,
• full demo: larger is fine, but repeated framework orchestration should be treated as a missing helper.

Milestones

Milestone 1: API Audit And Branch Plan

• Review current examples and demo for repeated orchestration.
• Create a feature/refactor branch.
• Create a working document under docs/working/.
• Decide which repeated wiring belongs in lc.composition.app.

Milestone 2: App Declaration Improvements

• Add or refine helpers that derive runtime pieces from an app declaration.
• Keep shell/content/action boundaries explicit.
• Add focused tests around pure declaration output.
• Update at least one small example.

Progress:

• Added lc.composition.app.shell(...) to declare shell and content together.
• Kept mode-specific key behavior under lc.presets.shell instead of adding app-level lazygit / lazyvim wrappers.
• Added app/panel/tab/content view-settings cascade support for line-number mode.
• Added lc.builders.view helpers so examples can use concise settings such as lc.builders.view.relative_lines().
• Updated the app-shell example to use lc.composition.app.shell(...) with a lc.presets.shell.lazygit(...) action factory instead of separately declaring a shell and then wrapping it in AppSpec.

Milestone 3: Options Editing Ergonomics

• Reduce app-local modal editing plumbing for editable options.
• Keep parser and validation errors explicit to the app/user.
• Add tests for accepted and rejected edits.
• Update the options example and demo if applicable.

Milestone 4: Docs And Release Gate

• Update user guides for the recommended declaration path.
• Update public API docs and snapshots.
• Run release checks.
• Archive this PRD after release.

Deferred Questions

• Should app declarations own all Textual bindings, or only derive suggested bindings?
• Should semantic actions such as open, edit, and select be content-owned or app-owned by default?
• Should option value types be Python callables, explicit type objects, or both?
• How much layout declaration belongs in lazy-cuh versus ordinary Textual CSS?
• Which presentation settings should join line-number mode in the cascade next: wrapping, scrolloff, redaction, density, or a smaller focused subset?