Files
waozi 017d3565d3 Build on Ziran 0.5.0 and Kryon's namespaced widgets, with the Tao picture page
Pin only pushed commits, with no local overrides: Ziran v0.5.0
(f9f92b46), Kryon b45cc524 (one lock entry, ref master, shared with the
Css and Plot master edges), Apps 352901e, Entity b30dd4a and practices
893e5b6f, whose sharpened banners and regenerated Lumi guide clips the
narration check now matches.

The Library opens each Tao Te Ching chapter on its own picture page: the
chapter art and its title, centered together; the text pages follow.
The reader keeps the picture page across reflow, and a chapter start or
a Contents pick opens it. The 81 approved chapter pictures are included.

Breeze now uses Kryon's namespaced widgets (Text.Draw/Text.Props,
Button, Image, Modal.ActionModal, Layout, TabBar, LoadingScreen,
LoadingIndicator, Shape.Circle) instead of the removed Kryon/Widgets
facades. Hosted apps import std/text explicitly, since a short "text"
import now names Kryon's widget. AGENTS.md and the Text/Button API checks
describe the namespaced forms; two unused test doubles are removed.

Build fixes for the new toolchain: the bundle runtime carries Ziran's
instruction engine (no BOOTSTRAP=1) and takes the pinned host zi2c for
cross builds; the Apps controller's lock context has the manifest's
module roots; the app codec generator lists Kryon's raw modules only;
the package scripts read ZX revision 28 bundle assets. The Apps
controller digest matches the Apps 352901e build.

Also included: the stopped lanes' work in this tree (Radio download,
Photos install, Lists, Lumi, Habits shop rewards, astral exercise
selection, appearance and download recovery) and the raylib-free desktop
lane's host modules (app_trace, host_input, host_window, host_clock),
inactive unless DESKTOP_HOST is defined.

Not included: the crash-recovery lane's picture-window and storage
crash-safety changes, which that lane commits itself.

Local tests: zi-check (510 modules), native and Android source checks,
hosted app checks, build-laws, clean-text-api-check, button-api-check,
library-reader-test, library-ui-test, storage-crash-zi-test and
native-image-decode-test pass. The bundled Arcade is still ZX revision 26
and waits for an Arcade build on these pins.
2026-11-16 14:20:12 -03:00

109 lines
6.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Inbe repository rules
## Ownership and releases
- Dependencies are Ziran packages pinned in `ziran.toml`/`ziran.lock` and
linked under `build/packages/`; there is no `vendor/`. Never edit a package
checkout. Change Kryon (or any dependency) in its own repository on `master`,
commit and push there, then run `ziran update NAME` here and commit
`ziran.lock`. Run `make package-check` after dependency changes. For local
debugging, map a package to a working repository in the ignored
`ziran.local.toml`; release builds use `PACKAGE_FLAGS=--locked`.
- Practice media (pictures, course data, recordings) lives in the
`practices` package (waozixyz/practices), not under
`assets/`. Commit media there, then update the lock here.
- Bump versions only for a release actually being made. Until then, note
every change under one `## [Unreleased]` section of `CHANGELOG.md` (and of
`apps/<app>/CHANGELOG.md`); App packages waits for the next version. At
release, number that section, then run `./update_version.sh`.
The canonical macros are `APP_VERSION_STRING`, `APP_VERSION_MAJOR`,
`APP_VERSION_MINOR`, and `APP_VERSION_PATCH`; do not create aliases.
Only the GitHub Actions release workflow creates or pushes release tags.
- A new version publishes only with a passing phone check of its exact app
content (`app_tree` over `APP_PATHS` in `scripts/phone-check.py`). Release
with `RELEASE_READY_REVISION=COMMIT make release-ready`, then
`make release REVISION=COMMIT APK=PATH BUILD_RECEIPT=PATH` with the development
Moto connected. The APK and its provenance come from the same fixed-source
overlay. Master, locks and peer edits keep changing freely. The release
commit retains the tested source; if master advanced, a merge preserves
all newer source and history. The workflow can release that exact commit
through its `revision` input. Never freeze the checkout for testing.
See [docs/apps.md](docs/apps.md#verification).
- Packages declare the oldest host interface they run on (`host_api` per app
in `apps/versions.json`); the host runs `oldest_host_api` to `host_api`.
Raise `host_api` when the host interface changes and `oldest_host_api` only
when it can no longer run older packages. `make package-compat-test` runs
the node's packages in this build and new packages in the last release.
`zx_revision` there is the ZX executable revision the host runs; update
checks send it and the node offers only packages whose `.zx` header has
it, and the publisher refuses a payload of another revision. Change it
with the Ziran pin, together with `oldest_host_api` and `host_api`.
- Goal (owner, 2026-10-11): every app updates through its own package
without a new APK. Work toward it in small steps alongside requested work;
discuss larger moves with the owner first. Put app screens, rules and text
in `apps/<app>/`, not in the host under `src/`. Practices draws its
screen layouts in `apps/practice/`; its native figure painters and
platform effects remain host capabilities (see [docs/apps.md](docs/apps.md)).
Keep the host interface small and generic (storage, network, locale,
platform effects), because
each new host call needs an APK before a package can use it. Apps share
data only through the host interface, never another app's internals.
- Translate changed strings in every affected locale; no English placeholders.
- Keep Breeze/Lumi/store notes to 2–3 short core, Practices or Habits lines, without links or Android versions; game changes belong only in their package changelogs.
- `make locale-translated-test` fails on any locale string that still equals
its English text. Translate it; add it to `tests/locale_same_as_english.txt`
only when it is a real brand name, loanword, or format string.
## Machine-checked contracts
- `make build-laws` is mandatory for native, web, and Windows artifacts;
Gradle and CMake enforce the same version and proof checks independently.
Never bypass a failed gate.
- Laws are Ziran `#law` obligations checked by `ziran check`. Retry behavior
lives in `src/app/sync_retry.zi` with its laws in `sync_retry_laws.zi`;
private-data names live in `src/storage/storage_layout.zi` with laws in
`storage_layout_laws.zi`. Change the implementation freely, but do not
weaken laws to make an implementation pass. Contract changes require
explicit product intent and separate review from implementation changes.
- Run `make proof-test sync-recovery-test version-test` for these contracts.
Coverage, trust boundaries, and the next proof migrations are described in
[docs/build-laws.md](docs/build-laws.md).
## Public UI and sync boundaries
- Use Kryon's namespaced widgets directly, each imported by package
(`Text :: #import "kryon/text";`): `Text.Draw(session, Text.Props)`,
`Image.Draw(session, Image.Props)` and `Button.Draw(session, Button.Props)`.
Semantic images use the same `Image` surface; file pictures come with
`kryon/image` and button icons with `kryon/icon`. No positional Text,
`Kryon`/`Widgets` facades, legacy drawing calls, alternate widgets, or thin
local forwarding wrappers. Keep meaningful compositions and gestures; use
standard `Checkbox.Draw` and `Toggle.Draw`.
Run `make clean-text-api-check button-api-check` for UI changes.
- If a required widget capability is missing, implement the reusable primitive
upstream first. Do not work around it in Inbe or generated code.
- Use sync protocol v6 and the clean Kryon API; no new `Ksync` names or wrappers.
Remove old wire projections and format fallbacks as the storage and sync
modules are converted to current Ziran. Keep the current protocol and data
model in Inbe rather than adding compatibility adapters.
- Keep on-disk schema and user-data upgrade paths. Convert their implementation
to checked Ziran; do not delete a migration merely because it handles an old
database. An upgrade must preserve existing data, and its replacement needs
a test using an older database fixture before the prior path is removed.
- A `.zi` filename is not a completed migration. All owned application
behavior, including storage upgrades, must compile as current Ziran. Prefer
direct Ziran foreign imports for native libraries; migrate owned C adapters
as Ziran gains the required ABI support. Never keep application policy in C.
## Product behavior and readability
- Desktop focus loss must not pause practices, freeze animation, suppress
updates, or enter the mobile background-timer path. Preserve mobile/web
lifecycle handling and explicit user pause as separate behavior.
- Preserve hover, press, and focus transitions. Session audio controls have
44-unit targets (24-unit icons plus 10-unit padding), scaled and spaced.
- Lists starts with list tabs, without a separate title bar or dropdown.
- Use descriptive names, explicit control flow, and focused helpers. Never
compress multiple statements, branches, declarations, or checks onto one line.
Format changed source, inspect the final diff, and run `git diff --check`.