Core API Change

core-api-change

./codegen sync does the mechanical half: regenerate, rerun bindgen / ffigen, commit core and the workspace. This skill is the other half — the decisions and checks the script cannot make. Work through the phases in order; each one ends in something you can verify before moving on.

1 design  →  2 pre-flight  →  3 core edit  →  4 regenerate + read the output
          →  5 hand-written layers  →  6 verify  →  7 commit  →  8 report

1. Design the signature first

Read specs/api-style.md and run its checklist against the signature before writing any platform code — a signature that changes after six platform files exist is six files of rework. For a new type also read specs/object-model.md (identity vs value object); for a new module, specs/architecture.md §5.

Where neighbouring headers disagree, the spec says which side is the rule. Do not copy the nearest neighbour.

2. Pre-flight: look before the script commits

./codegen sync runs git add -A in core and git add bindings/<lang> in the workspace, where every binding (dart, rust, csharp, js, python) lives. Anything lying around in those trees lands in a commit titled Sync with core <sha>.

make status                                   # dirty files + branch of every submodule
git status --short                            # workspace itself
for r in core; do
  printf '%-18s %s  behind origin/main: %s\n' "$r" \
    "$(git -C "$r" branch --show-current || echo DETACHED)" \
    "$(git -C "$r" rev-list --count HEAD..origin/main 2>/dev/null)"
done

• A binding is dirty with unrelated work (git status --short bindings/) → do not run sync. Use the manual path in §7. Ask the user only if you cannot tell whether the work is related.
• A submodule is on a detached HEAD or behind origin/main → check out main and fast-forward first. sync refuses detached HEADs, but it does not notice "on main, 10 commits behind", and committing there moves the workspace pointer backwards.
• core is dirty with files that are not part of this change → stage narrowly and commit core yourself before sync (it only commits core when core is dirty).

3. Edit core

1. Header in core/src/<module>.h, with the Doxygen block and — when behaviour differs per platform — the six-line @note Platform availability: block.
2. All six core/src/platform/<os>/<module>_<os>.{cpp,mm}. A platform that cannot support it still gets a stub (no-op / false / default value); a missing definition is a link error on that platform only, which you will not see locally.
3. New handle type → append an IdTypeTag<T> entry in core/src/foundation/id_allocator.h. Append only, never renumber.
4. New header that should cross the ABI → add it to API_HEADERS in tools/codegen/shared/src/lib.rs (kept roughly in dependency order for readability; the generator does not depend on it). If a hand-written file of the same name already exists in a binding, the generator skips it — delete it first.
5. Build what you can locally:

cmake -S core -B core/build && cmake --build core/build -j
ctest --test-dir core/build --output-on-failure

Only the host platform compiles here. Say so in the report; for the others use the remote-hosts skill or let CI answer.

4. Regenerate, then read the output

./codegen 2>&1 | tee /tmp/codegen.log     # C ABI, then Rust / Dart / C# / JS / Python
grep -i 'skipped' /tmp/codegen.log

The skipped lines are the point of this step. A method whose signature uses a type the generator cannot map is dropped with a warning, not an error — the build stays green and the API is simply absent from every binding. Known baseline (2026-09-17, 8 lines): three ModifierKey operators, RunApp, class Dialog, PositioningStrategy::GetRelativeWindow, Shortcut::GetCallback, KeyboardMonitor::GetInternalEventEmitter. Any line naming your new API means: go back to §1 and change the signature (api-style.md §7 lists what crosses the bridge).

Then read the generated C header for your module (core/src/capi/<module>_c.h):

• Does the function name read well? An unexpected _with_<param> suffix means you added an overload — rename instead (api-style.md §1.6).
• Did the getter become a property in the bindings? It only does when it is const, takes no arguments and starts with Get / Is / Has.
• For events: every payload field you expect is in the C struct. Fields come from GetXxx() const on the event class; unsupported types vanish silently.

Never edit a file that starts with // AUTO-GENERATED. DO NOT EDIT. (# AUTO-GENERATED. in Python) — change the header or the generator and rerun.