@roxyapi/ui-vue 0.33.0 → 0.35.0

package/AGENTS.md

@@ -8,7 +8,7 @@ Live preview: <https://roxyapi.github.io/ui/>. Source of truth for component typ
 
 ## Identity
 
-Roxy UI is the official web component library for the RoxyAPI catalog. Components and helpers cover Western astrology, Vedic astrology, numerology, tarot, Human Design, forecast, biorhythm, I Ching, crystals, dreams, angel numbers, with the location helper for geocoding. New endpoints regenerate component types automatically.
+Roxy UI is the official web component library for the RoxyAPI catalog. Components and helpers cover Western astrology, Vedic astrology, forecast, Human Design, Chinese astrology, feng shui, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers, with the location helper for geocoding. New endpoints regenerate component types automatically.
 
 ## Decision tree for picking a component
 
@@ -18,7 +18,7 @@ Map the natural-language request to a component first; fall back to the table be
 
 | If the user says... | Render |
 |---|---|
-| "daily horoscope for `{sign}`", "weekly horoscope", "monthly horoscope" | `<roxy-horoscope-card>` |
+| "daily horoscope for `{sign}`", "weekly horoscope", "monthly horoscope", "year ahead", "yearly horoscope" | `<roxy-horoscope-card>` with `period="daily"`, `"weekly"`, `"monthly"` or `"yearly"`. Every period carries the reading twice, whole as one column and split into six topic sections, and `layout` picks which one renders. Yearly also carries the themes, key periods, eclipses, retrogrades and best months of the year |
 | "birth chart", "natal chart", "Western chart", "show me my planets" | `<roxy-natal-chart>` |
 | "match two birth charts", "compare us in Western astrology", "synastry" | `<roxy-synastry-chart>` |
 | "kundli", "Vedic chart", "rashi chart", "South/North Indian chart" | `<roxy-vedic-kundli>` |
@@ -37,6 +37,12 @@ Map the natural-language request to a component first; fall back to the table be
 | "forecast", "what is coming up", "upcoming transits and events", "timeline of my year" | `<roxy-forecast-timeline>` |
 | "biorhythm", "physical/emotional/intellectual cycle", "critical days" | `<roxy-biorhythm-chart>` |
 | "I Ching", "hexagram", "cast the coins", "Book of Changes" | `<roxy-hexagram>` |
+| "BaZi", "four pillars", "my Chinese birth chart", "what is my Day Master", "eight characters" | `<roxy-bazi-chart>` |
+| "luck pillars", "Da Yun", "my ten year cycles", "when does my luck change" | `<roxy-luck-pillars>` |
+| "Chinese zodiac", "what animal am I", "year of the {animal}", "my Chinese sign today", "are {animal} and {animal} compatible" | `<roxy-zodiac-card>` (`mode="sign"` for a birth date, `"animal"` for one animal in full, `"daily"` for today, `"compatibility"` for a pair) |
+| "Chinese almanac", "Tong Shu", "is {date} a good day", "pick a wedding date", "auspicious days for {activity}" | `<roxy-almanac-day>` (`mode="day"`, `"month"`, or `"auspicious"` for a date search) |
+| "Kua number", "eight mansions", "Ba Zhai", "my best direction", "which way should my desk face" | `<roxy-kua-card>` (`mode="kua"` for the number, `"mansions"` for the full map) |
+| "flying stars", "Xuan Kong", "the stars in my house", "annual stars for {year}", "period 9 chart" | `<roxy-flying-star-chart>` (`mode="natal"` for a building, `mode="annual"` for one year over it) |
 | "moon phase", "moon calendar", "next full moon", "current moon" | `<roxy-moon-phase>` |
 | "what does my dream mean", "dream symbol", "dream dictionary", "I dreamt of {symbol}" | `<roxy-dream-card>` |
 | "angel number {n}", "meaning of 111 / 222 / 1111", "I keep seeing this number" | `<roxy-angel-number-card>` |
@@ -61,7 +67,7 @@ Use the table below for the formal endpoint to component mapping.
 | `<roxy-transit-wheel>` | Western | POST /astrology/transit-aspects | Natal chart on the inner ring, transiting bodies on the outer ring, aspect lines between them |
 | `<roxy-aspects-table>` | Western | POST /astrology/aspects, /astrology/transit-aspects, /astrology/aspect-patterns | Aspect rows coloured by nature with orb and strength, plus detected chart patterns |
 | `<roxy-moon-phase>` | Western | GET /astrology/moon-phase/{current,upcoming,calendar/...} | Moon phase card and calendar |
-| `<roxy-horoscope-card>` | Western | GET /astrology/horoscope/{sign}/{daily,weekly,monthly} | Daily, weekly, or monthly horoscope card |
+| `<roxy-horoscope-card>` | Western | GET /astrology/horoscope/{sign}/{daily,weekly,monthly,yearly} | Daily, weekly, monthly, or yearly horoscope card |
 | `<roxy-astrocartography-map>` | Western | POST /astrology/astrocartography | World map of planetary MC, IC, Ascendant, and Descendant lines with per-line interpretations |
 | `<roxy-local-space-compass>` | Western | POST /astrology/local-space | Compass dial of planetary azimuth lines from the birthplace, dimmed below the horizon |
 | `<roxy-relocation-wheel>` | Western | POST /astrology/relocation-chart | Relocated chart wheel plus the move geometry, angular planets, and planets that change house |
@@ -106,6 +112,12 @@ Use the table below for the formal endpoint to component mapping.
 | `<roxy-hd-variables>` | Human Design | POST /human-design/variables | The four transformation arrows with direction, color, tone, and base, plus a reading per arrow grouped by layer and the cognition |
 | `<roxy-forecast-timeline>` | Forecast | POST /forecast/{timeline,significant-dates,transits} | Date-grouped events across Western, Vedic, and biorhythm domains, weighted by significance |
 | `<roxy-forecast-digest>` | Forecast | POST /forecast/digest | Per-window event counts, domain breakdown, and the highest-significance events |
+| `<roxy-bazi-chart>` | Chinese | POST /chinese-astrology/bazi/chart | Year, month, day and hour pillars in hanzi with hidden stems, Ten Gods, Na Yin, element balance and interactions |
+| `<roxy-luck-pillars>` | Chinese | POST /chinese-astrology/bazi/luck-pillars | Ten-year luck pillars as a strip with ages and years, the annual pillars, and the direction and start age behind them |
+| `<roxy-zodiac-card>` | Chinese | POST /chinese-astrology/zodiac/sign, GET /chinese-astrology/zodiac/{animals/{id},{id}/daily,compatibility/{sign1}/{sign2}} | The animal for a date, one animal in full, a daily reading, or a pair scored |
+| `<roxy-almanac-day>` | Chinese | GET /chinese-astrology/calendar/{day/{date},monthly}, POST /chinese-astrology/calendar/auspicious-days | Day officer, favours and avoids, clash animal and pillars, as one day, a month, or a date search |
+| `<roxy-flying-star-chart>` | Feng Shui | POST /feng-shui/flying-stars/natal, GET /feng-shui/flying-stars/annual/{year} | Nine-palace flying star plate with the mountain, period and water star per palace, the facing and sitting mountains and the structure |
+| `<roxy-kua-card>` | Feng Shui | POST /feng-shui/kua, POST /feng-shui/eight-mansions | Kua number and trigram over the eight-sector direction map, favourable and unfavourable sectors ranked |
 | `<roxy-biorhythm-chart>` | Biorhythm | POST /biorhythm/{daily,forecast,critical-days} | Daily bars, forecast cycle lines, critical days |
 | `<roxy-hexagram>` | I Ching | GET /iching/hexagrams/{number}, /iching/cast, POST /iching/daily, /iching/daily/cast | Hexagram figure with trigrams, judgment, image, and a reading per line (statement plus meaning); a cast highlights the moving lines and the resulting hexagram |
 | `<roxy-crystal-card>` | Crystals | GET /crystals/{id} | Photo, meaning sections, chakra, zodiac, element, hardness, keywords, and pairings |
@@ -214,7 +226,7 @@ Several components select a view, mode, or chart layout in addition to `data`. T
 <RoxyPanchangTable data={panchang} detail="detailed" />
 ```
 
-The full set: `RoxyNatalChart` `houseSystem`, `RoxyHoroscopeCard` `period`, `RoxyMoonPhase` `mode`, `RoxyCompatibilityCard` `mode`, `RoxyVedicKundli` and `RoxyDivisionalChart` `chartStyle`, `RoxyPanchangTable` `detail`, `RoxyDashaTimeline` `period`, `RoxyDoshaCard` `type`, `RoxyNumerologyCard` `type`, `RoxyTarotSpread` `spread`, `RoxyBiorhythmChart` `mode`, `RoxyHexagram` `mode`. Outside React and Vue, set the same value as a kebab-case attribute or a JS property on the element (for example `chart-style="south"` or `el.chartStyle = 'south'`).
+The full set: `RoxyNatalChart` `houseSystem`, `RoxyHoroscopeCard` `period` and `layout`, `RoxyMoonPhase` `mode`, `RoxyZodiacCard` `mode`, `RoxyKuaCard` `mode`, `RoxyAlmanacDay` `mode`, `RoxyFlyingStarChart` `mode`, `RoxyCompatibilityCard` `mode`, `RoxyVedicKundli` and `RoxyDivisionalChart` `chartStyle`, `RoxyPanchangTable` `detail`, `RoxyDashaTimeline` `period`, `RoxyDoshaCard` `type`, `RoxyNumerologyCard` `type`, `RoxyTarotSpread` `spread`, `RoxyBiorhythmChart` `mode`, `RoxyHexagram` `mode`. Outside React and Vue, set the same value as a kebab-case attribute or a JS property on the element (for example `chart-style="south"` or `el.chartStyle = 'south'`).
 
 ### 6c. Vue and Nuxt
 
@@ -421,7 +433,7 @@ That single element renders a schema-driven form (a zodiac/enum tile picker, a b
 
 In React, the same props are typed: `<RoxyNatalChart endpoint="astrology/natal-chart" publishableKey={process.env.NEXT_PUBLIC_ROXY_PK} />`.
 
-**Three optional attributes on the self-fetch element.** `lang` sets the response language (`en`, `tr`, `de`, `es`, `hi`, `pt`, `fr`, `ru`): put it on the element (`<roxy-horoscope-card lang="de" ...>`) and the form routes it to the `?lang=` query on submit, so visitors never see a language field. `submit-label` overrides the derived button label. `attribution` renders a small "Spiritual data by RoxyAPI" credit under the result: off by default, and the one-tag script below turns it on unless you set `data-attribution="off"`. None of these apply in controlled mode.
+**Three optional attributes on the self-fetch element.** `lang` sets the response language (`en`, `tr`, `de`, `es`, `hi`, `pt`, `fr`, `ru`, `zh-Hans`, `zh-Hant`): put it on the element (`<roxy-horoscope-card lang="de" ...>`) and the form routes it to the `?lang=` query on submit, so visitors never see a language field. `submit-label` overrides the derived button label. `attribution` renders a small "Spiritual data by RoxyAPI" credit under the result: off by default, and the one-tag script below turns it on unless you set `data-attribution="off"`. None of these apply in controlled mode.
 
 **One tag, no element wiring.** For the simplest embed, load `dist/cdn/widgets.js` and drop a `<div data-roxy-widget="{slug}" data-publishable-key="pk_live_...">`. The script mounts the matching component from a generated slug map: with every path parameter supplied as a `data-*` attribute (`data-sign`, `data-id`) it fetches on mount, otherwise it renders the same input form. A second `data-*` attribute picks a variant (`data-period`, `data-mode`, `data-type`, `data-spread`). To keep every key on your own server instead, drop the publishable key and give the tag `data-submit-url` and `data-location-url`: the widget renders the form and routes both its requests there. `data-submit-context` rides along with the submitted one.
 
@@ -429,17 +441,49 @@ In React, the same props are typed: `<RoxyNatalChart endpoint="astrology/natal-c
 
 ### Pattern 5: MCP tool-call response
 
-A remote MCP server at `roxyapi.com/mcp/{domain}` exposes each RoxyAPI endpoint as an MCP tool. The JSON returned by the tool call has the same shape as the SDK response. Pass it straight into the matching component.
+A Remote MCP server at `roxyapi.com/mcp/{domain}` exposes each RoxyAPI endpoint as a tool, named for its method and path: `post_astrology_natal_chart`, `post_tarot_spreads_three_card`, `get_tarot_cards_id`. When your model calls one, the result is a single text content block holding the JSON string, and that JSON is the same shape the SDK returns. So the whole render is: parse it, look up the component, set `data`.
+
+`componentForTool(name)` is the lookup, exported from `@roxyapi/ui`, `@roxyapi/ui-react` and `@roxyapi/ui-vue`. It returns `{ tag, pascal, attrs?, operationId, toolName }` for a tool the library draws, and `undefined` for one it does not. `operationId` names the OpenAPI operation the tool calls, for your logs or for finding the endpoint in the API reference. `attrs` values are always strings: set them as attributes in the DOM, spread them as props in React and Vue.
 
 ```ts
-// Pseudocode for any MCP-aware agent
-const result = await mcp.call('roxyapi.astrology.generate_natal_chart', {
-	date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5,
-});
-document.querySelector('roxy-natal-chart').data = result;
+import { componentForTool } from '@roxyapi/ui';
+
+// `toolName` and `result` are what your model handed back for one tool call.
+const found = componentForTool(toolName);
+if (found) {
+	const el = document.createElement(found.tag);
+	for (const [name, value] of Object.entries(found.attrs ?? {})) el.setAttribute(name, value);
+	el.data = JSON.parse(result.content[0].text);
+	container.append(el);
+}
+```
+
+In React, `pascal` is the export name, so a namespace import renders it directly:
+
+```tsx
+import * as RoxyUI from '@roxyapi/ui-react';
+import { componentForTool } from '@roxyapi/ui-react';
+
+export function ToolWidget({ toolName, output }: { toolName: string; output: string }) {
+	const found = componentForTool(toolName);
+	if (!found) return null;
+	const Component = RoxyUI[found.pascal as keyof typeof RoxyUI] as React.ComponentType<{ data: unknown }>;
+	return <Component data={JSON.parse(output)} {...found.attrs} />;
+}
 ```
 
-No field renames. No glue code. Use the decision tree above to pick the component for any tool.
+Three things the lookup already handles, so you do not have to:
+
+- **A compact result.** Ask a tool for the compact shape and its same-shaped arrays arrive columnar, as `{ "__cols": [names], "__rows": [[values]] }`. Every component decodes that on the way in and renders the same card either way. `expandCompact(value)` is exported too, for the paths that read the JSON before an element does.
+- **A server-prefixed name.** Some hosts prefix the tool name with the server it came from and a colon (`roxy_tarot:post_tarot_daily`). The lookup strips the prefix.
+- **Which component leads.** Three responses are rendered by two components each, and the lookup returns the one that leads with the drawing:
+	- the natal chart response is drawn by both `<roxy-natal-chart>` and `<roxy-western-planets-table>`, the lookup returns `<roxy-natal-chart>`
+	- the transit aspects response is drawn by both `<roxy-transit-wheel>` and `<roxy-aspects-table>`, the lookup returns `<roxy-transit-wheel>`
+	- the Vedic birth chart response is drawn by both `<roxy-vedic-kundli>` and `<roxy-vedic-planets-table>`, the lookup returns `<roxy-vedic-kundli>`
+
+Full recipe, including the vendor connectors and the Vercel AI SDK: <https://roxyapi.com/docs/tutorials/ai-chat-widgets>.
+
+No field renames. No glue code. Use the decision tree above to pick the component for any tool the lookup does not cover.
 
 ### Pattern 6: Next.js RSC streaming
 
@@ -503,7 +547,9 @@ This is how the WordPress plugin renders: PHP fetches the response server-side,
 
 ## Localized responses
 
-Most RoxyAPI endpoints return their interpretation text in eight languages, selected with the `lang` query parameter (`en`, `tr`, `de`, `es`, `hi`, `pt`, `fr`, `ru`). Human Design, for example, returns the type, strategy, authority, profile, channel, center, gate, and line readings in the requested language.
+Most RoxyAPI endpoints return their interpretation text in the language you ask for, selected with the `lang` query parameter (`en`, `tr`, `de`, `es`, `hi`, `pt`, `fr`, `ru`, `zh-Hans`, `zh-Hant`). Human Design, for example, returns the type, strategy, authority, profile, channel, center, gate, and line readings in the requested language. Coverage varies by domain, and a field with no translation in the language you asked for comes back in English.
+
+Chinese is named by script rather than by language, so `zh-Hant` and `zh-Hans` are the two values to send. A component resolves a regional tag for you: `zh-TW` and `zh-HK` read as traditional, `zh-CN` and `zh-SG` as simplified.
 
 The components hold no copy of their own; they print the prose the response carries. So the language of the response is the language of the render.
 
@@ -627,7 +673,7 @@ That table is the shared vocabulary, not the whole list. **`components-catalog.j
 
 ## Domain ordering
 
-When listing domains in user-visible copy, use the canonical order: Western astrology, Vedic astrology, forecast, human design, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers. Location is utility, not a selling domain. The `domain` field in `components-catalog.json` carries the same names, so sort by this list rather than by whatever order you discovered components in.
+When listing domains in user-visible copy, use the canonical order: Western astrology, Vedic astrology, forecast, human design, Chinese astrology, feng shui, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers. Sort by this list and skip any domain the catalog does not carry a component for. Location is utility, not a selling domain. The `domain` field in `components-catalog.json` carries the same names, so sort by this list rather than by whatever order you discovered components in.
 
 ## What not to ship
 

package/README.md

@@ -177,6 +177,53 @@ Every chart, table, and card adapts to light and dark automatically. Hover any i
 </tr>
 </table>
 
+### Chinese astrology and feng shui
+
+<table>
+<tr>
+<td width="50%"><strong>Four pillars</strong> · <code>&lt;roxy-bazi-chart&gt;</code><br><sub>POST /chinese-astrology/bazi/chart</sub><br>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/bazi-chart-dark.png">
+  <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/bazi-chart-light.png" alt="BaZi four pillars chart, each pillar drawn as a Heavenly Stem over its Earthly Branch in hanzi with the Ten God relation, the stems the branch stores, and the Na Yin, over the five-element balance and the interactions the pillars form">
+</picture>
+</td>
+<td width="50%"><strong>Flying star chart</strong> · <code>&lt;roxy-flying-star-chart&gt;</code><br><sub>POST /feng-shui/flying-stars/natal</sub><br>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/flying-star-chart-dark.png">
+  <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/flying-star-chart-light.png" alt="Xuan Kong flying star plate, nine palaces on the Chinese compass with south at the top, each carrying its mountain star, period star and water star, over the facing and sitting mountains and the structure they produce">
+</picture>
+</td>
+</tr>
+<tr>
+<td width="50%"><strong>Chinese zodiac</strong> · <code>&lt;roxy-zodiac-card&gt;</code><br><sub>GET /chinese-astrology/zodiac/animals/&#123;id&#125;</sub><br>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/zodiac-card-dark.png">
+  <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/zodiac-card-light.png" alt="Chinese zodiac animal card with the animal in hanzi, its element and polarity, the double hours it governs, its trine, and its secret friend, clash and harm partners">
+</picture>
+</td>
+<td width="50%"><strong>Kua and eight mansions</strong> · <code>&lt;roxy-kua-card&gt;</code><br><sub>POST /feng-shui/eight-mansions</sub><br>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/kua-card-dark.png">
+  <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/kua-card-light.png" alt="Eight Mansions map on the nine-palace grid, four favourable and four unfavourable compass sectors each with its star, rank and life domain, and the Kua number and trigram in the centre">
+</picture>
+</td>
+</tr>
+<tr>
+<td width="50%"><strong>Luck pillars</strong> · <code>&lt;roxy-luck-pillars&gt;</code><br><sub>POST /chinese-astrology/bazi/luck-pillars</sub><br>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/luck-pillars-dark.png">
+  <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/luck-pillars-light.png" alt="BaZi luck pillars as a strip of ten-year stretches, each with its stem and branch in hanzi, the Ten God relation, and the ages and years it spans">
+</picture>
+</td>
+<td width="50%"><strong>Chinese almanac</strong> · <code>&lt;roxy-almanac-day&gt;</code><br><sub>GET /chinese-astrology/calendar/day/&#123;date&#125;</sub><br>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/almanac-day-dark.png">
+  <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/almanac-day-light.png" alt="Chinese almanac day with the day officer, what the day favours and what it avoids, the animal it clashes with, and its three pillars and lunar mansion">
+</picture>
+</td>
+</tr>
+</table>
+
 ### Other domains
 
 <table>
@@ -290,6 +337,40 @@ Always call `/location/search` first. Every chart endpoint expects latitude, lon
 
 > **Timezone format.** RoxyAPI accepts both forms: a decimal-hour offset (`5.5` for IST, `-5` for EST) or an IANA name (`'Asia/Kolkata'`, `'America/New_York'`). Pick one and stay consistent. The decimal form is shorter and what `/location/search` returns; examples on this page use it. The IANA form is correct over DST boundaries when historical accuracy matters.
 
+## Render an AI tool result
+
+It ships inside `@roxyapi/ui`, `@roxyapi/ui-react` and `@roxyapi/ui-vue`, so whichever one you already installed has it and there is nothing else to add.
+
+Your model calls a Remote MCP tool at `roxyapi.com/mcp/{domain}` and hands you back a tool name and a JSON string. `componentForTool(name)` turns that name into the component that draws it, so a chat answer shows a real tarot spread or a real chart instead of a wall of fields. It works in any chat UI that lets you render your own markup for a tool result.
+
+```ts
+import { componentForTool } from '@roxyapi/ui';
+
+const found = componentForTool(toolName);
+if (found) {
+	const el = document.createElement(found.tag);
+	for (const [name, value] of Object.entries(found.attrs ?? {})) el.setAttribute(name, value);
+	el.data = JSON.parse(result.content[0].text);
+	container.append(el);
+}
+```
+
+In React, `pascal` is the export name, so a namespace import renders it directly:
+
+```tsx
+import * as RoxyUI from '@roxyapi/ui-react';
+import { componentForTool } from '@roxyapi/ui-react';
+
+export function ToolWidget({ toolName, output }: { toolName: string; output: string }) {
+	const found = componentForTool(toolName);
+	if (!found) return null;
+	const Component = RoxyUI[found.pascal as keyof typeof RoxyUI] as React.ComponentType<{ data: unknown }>;
+	return <Component data={JSON.parse(output)} {...found.attrs} />;
+}
+```
+
+A compact tool result is decoded for you, and a name a host prefixed with its server (`roxy_tarot:post_tarot_daily`) resolves the same as a bare one. Full recipe, with the vendor connectors and the Vercel AI SDK: <https://roxyapi.com/docs/tutorials/ai-chat-widgets>. Runnable page: [examples/vanilla/tool-result.html](examples/vanilla/tool-result.html).
+
 ## Server-rendered, no JavaScript wiring
 
 Server-rendered and cached pages (WordPress, JSX SSR, static HTML) cannot always run JavaScript to set the `data` property per element. Render the response into a child `<script type="application/json" class="roxy-data">` on the server instead. The component reads it on load. No per-element script, no API key in the browser.
@@ -428,7 +509,103 @@ const { data: d9 } = await roxy.vedicAstrology.generateDivisionalChart({
 <RoxyDivisionalChart data={d9} />
 ```
 
-### 3. Numerology (life path, full chart, personal year)
+### 3. Forecast (transits, cross-domain timeline)
+
+One stateless call merges Western transits, Vedic Vimshottari dasha boundaries, and biorhythm critical days into a single significance-scored, time-ordered timeline. Built for forecast feeds, transit alerts, and timing tools. No coordinates needed.
+
+```tsx
+import { RoxyForecastTimeline } from '@roxyapi/ui-react';
+
+// Transit forecast. The demand leader. Western transit-to-natal aspects, sign
+// ingresses, and retrograde stations over the window.
+const { data: transits } = await roxy.forecast.forecastTransits({
+  body: { birthData: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 } },
+});
+<RoxyForecastTimeline data={transits} />
+
+// Cross-domain timeline. The same window merged with Vedic dasha boundaries and
+// biorhythm critical days into one significance-scored timeline.
+const { data: timeline } = await roxy.forecast.generateTimeline({
+  body: {
+    birthData: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
+    domains: ['western', 'vedic', 'biorhythm'],
+  },
+});
+<RoxyForecastTimeline data={timeline} />
+```
+
+### 4. Human Design (bodygraph)
+
+A self-knowledge system computed from the same ephemeris as Western astrology, laid over the I Ching gate wheel and nine chakra-style centers. Self-discovery apps, dating and compatibility products, and AI coaching bots render the full bodygraph. No coordinates needed; Human Design uses the birth instant, not the observer location.
+
+The response is a reading, not a set of labels: the type, strategy, authority, profile, and definition each arrive with the text that explains them, every defined channel and every center carry their own interpretation, and each of the activations carries a gate meaning and the meaning of its line. `<RoxyBodygraph>` lays that out for you. The chart and the identity read at a glance, and every body of prose sits behind a disclosure, so one component renders a complete reading without becoming a wall of text.
+
+```tsx
+import { RoxyBodygraph } from '@roxyapi/ui-react';
+
+// Full bodygraph. The head term every Human Design app leads with ("human design chart").
+// Type, strategy, authority, profile, the nine centers, channels, and every gate
+// activation in one call. Pass the birth instant only, no latitude or longitude.
+const { data: bodygraph } = await roxy.humanDesign.generateBodygraph({
+  body: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
+});
+<RoxyBodygraph data={bodygraph} />
+```
+
+Every interpretation is localized. Ask for the language on the request and the component renders it, because the component prints the prose the API returned and holds no copy of its own.
+
+```tsx
+const { data: bodygraph } = await roxy.humanDesign.generateBodygraph({
+  body: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
+  query: { lang: 'de' },
+});
+```
+
+### 5. Chinese astrology (four pillars, luck pillars, zodiac, almanac)
+
+The BaZi chart a reading is built on, the ten-year luck pillars that time it, the twelve-animal zodiac, and the almanac people actually consult to pick a date. Fits date-selection tools, Chinese-new-year features and East Asian wellness apps.
+
+```tsx
+import { RoxyBaziChart, RoxyZodiacCard, RoxyAlmanacDay } from '@roxyapi/ui-react';
+
+// Four pillars. Stem over branch per pillar, hidden stems, Ten Gods, element balance.
+const { data: bazi } = await roxy.chineseAstrology.generateBaziChart({
+  body: { date: '1990-01-15', time: '14:30:00', timezone: 'America/New_York' },
+});
+<RoxyBaziChart data={bazi} />
+
+// The animal a birth date falls in, on the classical year boundary.
+const { data: sign } = await roxy.chineseAstrology.calculateZodiacAnimal({
+  body: { date: '1990-01-15' },
+});
+<RoxyZodiacCard data={sign} mode="sign" />
+
+// Almanac day. What the day favours, what it avoids, and the animal it clashes with.
+const { data: day } = await roxy.chineseAstrology.getAlmanacDay({ path: { date: '2026-09-08' } });
+<RoxyAlmanacDay data={day} mode="day" />
+```
+
+### 6. Feng shui (kua number, eight mansions, flying stars)
+
+A person's Kua number and the eight directions it ranks for them, plus the Xuan Kong flying-star plate for a building. Fits home and office consultation tools, property apps and annual-forecast features.
+
+```tsx
+import { RoxyKuaCard, RoxyFlyingStarChart } from '@roxyapi/ui-react';
+
+// Kua number and the full Eight Mansions map, four favourable sectors and four not.
+const { data: mansions } = await roxy.fengShui.generateEightMansions({
+  body: { date: '1990-01-15', gender: 'female' },
+});
+<RoxyKuaCard data={mansions} mode="mansions" />
+
+// Flying star plate for a building, from its facing degrees and construction period.
+const { data: plate } = await roxy.fengShui.generateFlyingStarChart({
+  body: { facingDegrees: 175, period: 9 },
+});
+<RoxyFlyingStarChart data={plate} mode="natal" />
+```
+
+### 7. Numerology (life path, full chart, personal year)
 
 Life path, the full chart, and the personal year. The easiest domain to integrate: a name and a birth date are enough, with no birth time and no coordinates.
 
@@ -454,7 +631,7 @@ const { data: pyear } = await roxy.numerology.calculatePersonalYear({
 <RoxyNumerologyCard data={pyear} type="personal-year" />
 ```
 
-### 4. Tarot (daily card, three-card, Celtic Cross)
+### 8. Tarot (daily card, three-card, Celtic Cross)
 
 Draw a single daily card, a three-card spread, or a full Celtic Cross. The card database is stable reference data, so fetch it once and cache it rather than calling per render.
 
@@ -478,59 +655,7 @@ const { data: cc } = await roxy.tarot.castCelticCross({
 <RoxyTarotSpread data={cc} />
 ```
 
-### 5. Human Design (bodygraph)
-
-A self-knowledge system computed from the same ephemeris as Western astrology, laid over the I Ching gate wheel and nine chakra-style centers. Self-discovery apps, dating and compatibility products, and AI coaching bots render the full bodygraph. No coordinates needed; Human Design uses the birth instant, not the observer location.
-
-The response is a reading, not a set of labels: the type, strategy, authority, profile, and definition each arrive with the text that explains them, every defined channel and every center carry their own interpretation, and each of the activations carries a gate meaning and the meaning of its line. `<RoxyBodygraph>` lays that out for you. The chart and the identity read at a glance, and every body of prose sits behind a disclosure, so one component renders a complete reading without becoming a wall of text.
-
-```tsx
-import { RoxyBodygraph } from '@roxyapi/ui-react';
-
-// Full bodygraph. The head term every Human Design app leads with ("human design chart").
-// Type, strategy, authority, profile, the nine centers, channels, and every gate
-// activation in one call. Pass the birth instant only, no latitude or longitude.
-const { data: bodygraph } = await roxy.humanDesign.generateBodygraph({
-  body: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
-});
-<RoxyBodygraph data={bodygraph} />
-```
-
-Every interpretation is localized. Ask for the language on the request and the component renders it, because the component prints the prose the API returned and holds no copy of its own.
-
-```tsx
-const { data: bodygraph } = await roxy.humanDesign.generateBodygraph({
-  body: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
-  query: { lang: 'de' },
-});
-```
-
-### 6. Forecast (transits, cross-domain timeline)
-
-One stateless call merges Western transits, Vedic Vimshottari dasha boundaries, and biorhythm critical days into a single significance-scored, time-ordered timeline. Built for forecast feeds, transit alerts, and timing tools. No coordinates needed.
-
-```tsx
-import { RoxyForecastTimeline } from '@roxyapi/ui-react';
-
-// Transit forecast. The demand leader. Western transit-to-natal aspects, sign
-// ingresses, and retrograde stations over the window.
-const { data: transits } = await roxy.forecast.forecastTransits({
-  body: { birthData: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 } },
-});
-<RoxyForecastTimeline data={transits} />
-
-// Cross-domain timeline. The same window merged with Vedic dasha boundaries and
-// biorhythm critical days into one significance-scored timeline.
-const { data: timeline } = await roxy.forecast.generateTimeline({
-  body: {
-    birthData: { date: '1990-01-15', time: '14:30:00', timezone: 5.5 },
-    domains: ['western', 'vedic', 'biorhythm'],
-  },
-});
-<RoxyForecastTimeline data={timeline} />
-```
-
-### 7. Biorhythm (daily, forecast)
+### 9. Biorhythm (daily, forecast)
 
 Physical, emotional and intellectual cycles from a birth date alone, as a daily reading or a forward forecast with the critical days marked. Fits wellness, productivity, sports and couples apps.
 
@@ -551,7 +676,7 @@ const { data: forecast } = await roxy.biorhythm.getForecast({
 <RoxyBiorhythmChart data={forecast} mode="forecast" />
 ```
 
-### 8. I Ching (cast a reading, hexagram lookup)
+### 10. I Ching (cast a reading, hexagram lookup)
 
 Cast a reading with its changing lines and the hexagram it transforms into, or look up any of the 64 figures directly. Fits meditation apps, decision-making tools and wisdom chatbots.
 
@@ -610,7 +735,7 @@ The self-fetch form renders spec-driven inputs (a zodiac tile picker, a boolean
 | `<roxy-transit-wheel>` | Western | POST /astrology/transit-aspects | Natal chart on the inner ring, transiting bodies on the outer ring, aspect lines between them |
 | `<roxy-aspects-table>` | Western | POST /astrology/aspects, /astrology/transit-aspects, /astrology/aspect-patterns | Aspect rows coloured by nature with orb and strength, plus detected chart patterns |
 | `<roxy-moon-phase>` | Western | GET /astrology/moon-phase/{current,upcoming,calendar/...} | Moon phase card and calendar |
-| `<roxy-horoscope-card>` | Western | GET /astrology/horoscope/{sign}/{daily,weekly,monthly} | Daily, weekly, or monthly horoscope card |
+| `<roxy-horoscope-card>` | Western | GET /astrology/horoscope/{sign}/{daily,weekly,monthly,yearly} | Daily, weekly, monthly, or yearly horoscope card |
 | `<roxy-astrocartography-map>` | Western | POST /astrology/astrocartography | World map of planetary MC, IC, Ascendant, and Descendant lines with per-line interpretations |
 | `<roxy-local-space-compass>` | Western | POST /astrology/local-space | Compass dial of planetary azimuth lines from the birthplace, dimmed below the horizon |
 | `<roxy-relocation-wheel>` | Western | POST /astrology/relocation-chart | Relocated chart wheel plus the move geometry, angular planets, and planets that change house |
@@ -655,6 +780,12 @@ The self-fetch form renders spec-driven inputs (a zodiac tile picker, a boolean
 | `<roxy-hd-variables>` | Human Design | POST /human-design/variables | The four transformation arrows with direction, color, tone, and base, plus a reading per arrow grouped by layer and the cognition |
 | `<roxy-forecast-timeline>` | Forecast | POST /forecast/{timeline,significant-dates,transits} | Date-grouped events across Western, Vedic, and biorhythm domains, weighted by significance |
 | `<roxy-forecast-digest>` | Forecast | POST /forecast/digest | Per-window event counts, domain breakdown, and the highest-significance events |
+| `<roxy-bazi-chart>` | Chinese | POST /chinese-astrology/bazi/chart | Year, month, day and hour pillars in hanzi with hidden stems, Ten Gods, Na Yin, element balance and interactions |
+| `<roxy-luck-pillars>` | Chinese | POST /chinese-astrology/bazi/luck-pillars | Ten-year luck pillars as a strip with ages and years, the annual pillars, and the direction and start age behind them |
+| `<roxy-zodiac-card>` | Chinese | POST /chinese-astrology/zodiac/sign, GET /chinese-astrology/zodiac/{animals/{id},{id}/daily,compatibility/{sign1}/{sign2}} | The animal for a date, one animal in full, a daily reading, or a pair scored |
+| `<roxy-almanac-day>` | Chinese | GET /chinese-astrology/calendar/{day/{date},monthly}, POST /chinese-astrology/calendar/auspicious-days | Day officer, favours and avoids, clash animal and pillars, as one day, a month, or a date search |
+| `<roxy-flying-star-chart>` | Feng Shui | POST /feng-shui/flying-stars/natal, GET /feng-shui/flying-stars/annual/{year} | Nine-palace flying star plate with the mountain, period and water star per palace, the facing and sitting mountains and the structure |
+| `<roxy-kua-card>` | Feng Shui | POST /feng-shui/kua, POST /feng-shui/eight-mansions | Kua number and trigram over the eight-sector direction map, favourable and unfavourable sectors ranked |
 | `<roxy-biorhythm-chart>` | Biorhythm | POST /biorhythm/{daily,forecast,critical-days} | Daily bars, forecast cycle lines, critical days |
 | `<roxy-hexagram>` | I Ching | GET /iching/hexagrams/{number}, /iching/cast, POST /iching/daily, /iching/daily/cast | Hexagram figure with trigrams, judgment, image, and a reading per line (statement plus meaning); a cast highlights the moving lines and the resulting hexagram |
 | `<roxy-crystal-card>` | Crystals | GET /crystals/{id} | Photo, meaning sections, chakra, zodiac, element, hardness, keywords, and pairings |
@@ -753,7 +884,7 @@ What each family keeps when you set it:
 
 - Charts and wheels keep the drawing, the legend, the glyphs, every degree and house, and the tab strip.
 - Tables keep every row and column, including the calculated ones (kaksha bindus, koota scores, significance bars, orbs and strengths).
-- Cards keep the header, the badges, the meters and the fact grids: a dosha keeps its present or absent verdict, its phase and its severity; a crystal keeps its Mohs hardness and its attribute grid; a horoscope keeps its energy meter, its Moon placement, the transits behind the reading and its key dates.
+- Cards keep the header, the badges, the meters and the fact grids: a dosha keeps its present or absent verdict, its phase and its severity; a crystal keeps its Mohs hardness and its attribute grid; a horoscope keeps its energy meter, its Moon placement, the transits behind the reading, its key dates, and the dated sky events the reading was built on, each with its exact instant and the house it falls in.
 - Vedic responses keep the sidereal frame caption, so a chart is still reconcilable against another calculator.
 
 What goes: interpretation paragraphs, the reading accordions, keyword chips attached to a reading, remedies and action steps and strengths lists (sentences laid out as bullets), and any section whose only content was one of those, heading included.
@@ -801,7 +932,9 @@ Two things are separate on purpose. The catalogue is the wording this library wr
 
 Dates, times and numbers follow the page as well, in the conventions that language actually uses: a Spanish page reads `15 ene 1990`, an Argentine one `15 de ene de 1990`, a German one `15. Jan. 1990, 14:30`. The hour cycle comes from the language, not from us, so nobody gets a 12-hour clock on a page that writes 24. This needs no catalogue and no attribute: it follows the same `lang` your page already declares.
 
-A catalogue ships for every language the API serves: `de`, `es`, `fr`, `hi`, `pt`, `ru`, `tr`. Coverage grows card by card, and a card is either translated or it is not, so a component reads its own labels in your language or renders them in English, never a mixture. Every term in every catalogue is sourced from named astrology references in that language rather than translated word for word, because the words a practitioner reads are the product.
+A catalogue ships for `de`, `es`, `fr`, `hi`, `pt`, `ru` and `tr`. Coverage grows card by card, and a card is either translated or it is not, so a component reads its own labels in your language or renders them in English, never a mixture. Every term in every catalogue is sourced from named astrology references in that language rather than translated word for word, because the words a practitioner reads are the product.
+
+Chinese is keyed by script rather than by language, so a page declaring `zh-Hant` or `zh-Hans` gets the response in that script from the endpoints that serve it. A regional tag resolves on its own: `zh-TW` and `zh-HK` read as traditional, `zh-CN` and `zh-SG` as simplified. Component labels stay English on those pages, and the response carries the vocabulary.
 
 ## Reliability
 
@@ -810,7 +943,7 @@ A catalogue ships for every language the API serves: `de`, `es`, `fr`, `hi`, `pt
 - Consistent response formats across every domain in the catalog.
 - A11y zero violations enforced in CI.
 - Tight per-component bundle budget enforced in CI.
-- Coverage of the highest-demand endpoints across Western astrology, Vedic astrology, numerology, tarot, Human Design, forecast, biorhythm, I Ching, plus helpers for location search and schema-driven forms.
+- Coverage of the highest-demand endpoints across Western astrology, Vedic astrology, forecast, Human Design, Chinese astrology, feng shui, numerology, tarot, biorhythm, I Ching, plus helpers for location search and schema-driven forms.
 
 ## Built for AI agents
 
@@ -837,7 +970,7 @@ Local preview serves `apps/docs/` on port 3001. Same directory and same paths th
 
 ## Stack and integrations
 
-Roxy UI runs in any framework that supports the DOM: **React, Next.js, Vue, Svelte, Angular, Solid, Astro, Qwik, Hono, Remix, Nuxt, SvelteKit, Lit, plain HTML, WordPress, Shopify themes that allow custom code, and any MCP-compatible AI agent**. Distribution paths: npm, jsDelivr CDN, shadcn registry. Use cases: astrology widgets, kundli matching, daily horoscope, tarot reader, numerology calculator, biorhythm dashboard, I Ching cast, panchang almanac, dasha timeline, moon phase tracker, synastry compatibility, dosha checker.
+Roxy UI runs in any framework that supports the DOM: **React, Next.js, Vue, Svelte, Angular, Solid, Astro, Qwik, Hono, Remix, Nuxt, SvelteKit, Lit, plain HTML, WordPress, Shopify themes that allow custom code, and any MCP-compatible AI agent**. Distribution paths: npm, jsDelivr CDN, shadcn registry. Use cases: astrology widgets, kundli matching, daily horoscope, BaZi four pillars chart, Chinese zodiac readings, feng shui Kua and flying star plates, almanac day picker, tarot reader, numerology calculator, biorhythm dashboard, I Ching cast, panchang almanac, dasha timeline, moon phase tracker, synastry compatibility, dosha checker.
 
 ## FAQ
 
@@ -873,7 +1006,7 @@ Persist the choice in `localStorage` from your own code; the components do not o
 <details>
 <summary><strong>How big is each component? What is the bundle cost?</strong></summary>
 
-Per-component bundles run 13-26 KB gzipped, capped at 30 KB by CI. The full bundle (every component, helpers, base styles, and the inlined design tokens) stays well under the 150 KB CI cap, around 108 KB gzipped today. The React and Vue packages load the runtime on mount, so a route that renders one chart pays for one component, not the whole catalog. Pin a concrete version in production for byte-stable cache hits.
+Every component bundle is under 30 KB gzipped and the full bundle (every component, helpers, base styles, and the inlined design tokens) is under 150 KB gzipped. Both ceilings are enforced in CI on every build, measured on the compressed bytes a browser actually downloads, so a release cannot quietly grow past them. A route that renders one chart pays for one component, not the whole catalog. Pin a concrete version in production for byte-stable cache hits.
 </details>
 
 <details>