[Roadmap] v1.0.0 #533

TL;DR

v1.0.0 makes the hook interfaces predictable. The sub-issues below track each change, one PR per sub-issue.

Base branch

Open every v1 PR against v1-base, not main. Breaking changes are stacked on v1-base, and v1-base is merged into main once every sub-issue is closed, so the major version is bumped only once.

Direction

• A hook's name tells who owns the state. *State hooks own it, *Value hooks derive a value from one you pass, and *Callback hooks wrap a function you pass.
• Required values are positional arguments, and optional behavior goes in a final options object.
• Time options carry their unit in the name, such as debounceMs, throttleMs and delayMs.
• Renamed hooks keep the old name as a deprecated alias. useDebounce and useThrottle stay available but are deprecated.

Before opening a PR

Changing a public export or its JSDoc also changes generated files, and CI fails when they are stale.

• Run yarn docs:gen <name> to regenerate the English API page from JSDoc, and yarn skill:gen to regenerate the agent skill.
• Run yarn test:docs and yarn test:skill. They also catch guides that still name a renamed or removed export.
• Update the translated pages (ko, ja, zh-Hans, es) next to the English page.

Order

Some sub-issues touch the same hooks as an open PR. Start them after that PR is merged into v1-base to avoid conflicts. Each sub-issue lists what it waits for.