docs: formalize the reactive contract (trigger keys, frozen parameters, cancel-and-restart)

[l2hyunwoo]

Closes #91.

Writes down what callers may rely on for reactive playback. Three rules, each checked against the runtime:

1. Every value read inside content is frozen at compile time. The internal composition is composed once and disposed, so keys are the only recompile trigger.
2. Keys are playback triggers. Put state in keys when its change should fire playback; state that only shapes the pattern stays inside content. A slider value passed as a key fires on every drag step.
3. Cancel-and-restart is best effort. A key change cancels the in-flight playback before starting the new one, with ordering held by the manager's state lock. Neither Vibrator.cancel() nor CHHapticPatternPlayer.stop reports completion, so a few milliseconds of physical overlap are possible.

Changes

• Jindong KDoc states the three rules and the Jindong(pattern) { Clip(pattern) } idiom.
• New guide page reactive-contract.mdx and a Clip DSL reference; quick-start already covered reactive playback, so it links to the new guide rather than repeating it.
• A Jindong(pattern, vararg keys) overload was considered and left out: Jindong(p) { ... } resolves to the existing vararg overload with p as a key, which compiles and plays the lambda instead of the pattern.

Tests

Jindong-level contract oracle: a parameter change without a key does not re-fire; a key change re-fires with the current parameter value. Complements the Clip-level tests from #90.

Stacked on #90 (base branch feat/clip-node).

Summary by CodeRabbit

• New Features

  • Added the Clip DSL function for placing prebuilt haptic patterns on the timeline.
  • Added guidance on reactive playback behavior, including key-triggered restarts, value freezing, and timing considerations.

• Documentation

  • Added API and guide pages covering Clip and the Reactive Contract.
  • Expanded quick-start, conceptual, and Jindong documentation with examples, usage notes, and navigation links.

• Tests

  • Added coverage verifying parameter updates and key-triggered playback behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4b12eb8b-ab04-4c51-bf1e-f238fea986f3

📥 Commits

Reviewing files that changed from the base of the PR and between 6ae88ac and 0f50141.

📒 Files selected for processing (11)

• documentation/content/docs/api/jindong-compose/composable-dsl/clip.mdx
• documentation/content/docs/api/jindong-compose/composable-dsl/meta.json
• documentation/content/docs/api/jindong-compose/jindong.mdx
• documentation/content/docs/api/meta.json
• documentation/content/docs/guide/meta.json
• documentation/content/docs/guide/quick-start.mdx
• documentation/content/docs/guide/reactive-contract.mdx
• documentation/content/docs/guide/thinking-declarative.mdx
• documentation/content/docs/meta.json
• jindong-compose/src/commonMain/kotlin/io/github/compose/jindong/Jindong.kt
• jindong-compose/src/commonTest/kotlin/io/github/compose/jindong/JindongContractTest.kt

---

📝 Walkthrough

Walkthrough

Changes

Reactive contract and Clip DSL

Layer / File(s)	Summary
Contract documentation and validation jindong-compose/src/commonMain/.../Jindong.kt, jindong-compose/src/commonTest/.../JindongContractTest.kt	Documents frozen content values, key-triggered playback, cancel-and-restart behavior, and validates parameter versus key changes.
Clip API reference documentation/content/docs/api/jindong-compose/..., documentation/content/docs/api/meta.json, documentation/content/docs/meta.json	Adds the Clip API page, examples, semantics, navigation entries, and related Jindong API references.
Guide contract documentation documentation/content/docs/guide/reactive-contract.mdx, documentation/content/docs/guide/meta.json, documentation/content/docs/guide/quick-start.mdx, documentation/content/docs/guide/thinking-declarative.mdx	Adds the Reactive Contract guide and links it from existing guide content and navigation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• feat(compose): add Clip node for embedding pattern values in the DSL #90 — Covers the Compose Clip node, reactive key semantics, documentation, and tests added here.
• Pattern algebra and the reactive contract #94 — Covers the Clip DSL, reactive-contract documentation/tests, and pattern embedding addressed here.

Possibly related PRs

• compose-jindong/jindong#84 — Introduced the key-driven recompilation behavior that this PR documents and tests.

Suggested reviewers: wisemuji

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately captures the main change: documenting Jindong's reactive contract.
Description check	✅ Passed	The description includes the issue, summary, changes, tests, and context, though it does not mirror the template headings exactly.
Linked Issues check	✅ Passed	The PR implements the documented contract, the Clip idiom, and regression tests for keyed and non-keyed playback as requested in #91.
Out of Scope Changes check	✅ Passed	The changes stay within the doc-and-test scope of the issue, with only related navigation and cross-reference updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/reactive-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Jindong Core Test Coverage Report

Total Project Coverage	89.41%