feat(client-api): harden encodeAxis input validation + schema clarity

[lmeyerov]

Problem

encodeAxis usage is easy to get wrong in downstream integrations because the expected input shape is not enforced clearly enough.

Observed integration failure mode:

• caller passed encodeAxis: { rows: [...] }
• runtime path expected axis rows array directly (encodeAxis([...]))
• result: axis overlays silently missing or no clear corrective error

Current behavior

In client API (projects/client-api/src/index.js), encodeAxis(axis) sets:

• rows: axis

So the payload expects direct rows array semantics.

Additional audit notes (2026-04-29)

• This surfaced during Louie radial/ring validation audits.
• Downstream tools need deterministic runtime errors (or explicit normalization) when object-with-rows shape is passed.
• Better machine-readable schema export would reduce drift across Python/TS integrations.

Requested behavior

1. Validate encodeAxis input shape at runtime with explicit errors:

• if object-with-rows is passed, either:
  • reject with clear message, or
  • normalize axis.rows -> rows array

2. Strengthen docs/types for encodeAxis input contract.
3. Export machine-readable schema for settings contracts so downstream clients can sync validation automatically.

Why this matters

• Reduces silent failures in graph overlays.
• Improves agent/tooling feedback loops with actionable errors.
• Prevents drift between docs, TS props, and runtime behavior.

Related

• pygraphistry strict settings validators: feat(validation): expose strict reusable settings validators pygraphistry#1240
• pygraphistry ring axis deep validator: feat(gfql): deep axis payload validation for ring_*_layout calls pygraphistry#1239