Canvas

A canvas is one .canvas.tsx file the app compiles so the user can open it beside the chat.

Rule text is English so it survives every runtime. Canvas content is output — it follows TD-LANG-01: 中文白话.

Workflow

1. Decide whether to use a canvas

The trigger is whether the numbers are the deliverable. If they are a step toward something else, skip the canvas.

Use one when: several symbols are compared across the same metrics; a read spans multiple periods or charts; an event is studied before and after; a directional call comes with scenarios or an entry/stop/target plan; a session or week is reviewed; any structured table longer than a handful of rows.

Do NOT when: the answer is one quote or one sentence; the user wants one of the four fixed chart types (chart skill); the user wants a journal entry or stock note (markdown under journal/ and stocks/); the data was an intermediate step; you do not have the numbers yet.

2. Fetch first, then embed

fetch_kline / read_data_pack / bash longbridge / research files. Write the numbers into the TSX, or offload them to a data file (see "Where data comes from" below). A canvas itself still cannot fetch — no sandboxed network access — but it can pull live quotes and K-line through the two hooks in that section.

Indicators are computed server-side and passed in; CandleChart draws, it does not compute (ema needs { label, points }, not periods). Attribute every number's vintage in the caption (TD-DATA-02). What you could not fetch goes in Coverage, never into a guess (TD-DATA-01).

3. Write the canvas

• One file, saved via save_canvas({ slug, title, source }). Slug is kebab-case. A canvas may have sibling data files (see below); it has no other helper .tsx/.ts files.
• Exactly one export default, the top-level component.
• Import from @kansoku/canvas, or a same-directory JSON data file (./<name>.json). No other relative paths, no react, no node:, no npm.
• Banned in source: fetch(, XMLHttpRequest, import(, require(, setTimeout / setInterval, document., window.. 64 KB limit.
• Revising: if the current source is not already in this conversation (you wrote or read it earlier and nothing else changed it), use bash cat -- journal/canvases/<slug>.canvas.tsx first; otherwise patch directly. Do not re-read after a successful apply_patch — its result already confirms the write. Send one apply_patch call carrying every hunk (*** Begin Patch / *** Update File: <path> / @@ context / , -, + lines / *** End Patch). Keep the same path. Use save_canvas only when creating a canvas or replacing the whole source. One question, one slug.
• Free builds may keep at most 3 canvases. Overwriting an existing slug is always allowed; a fourth new slug is rejected until the user upgrades to Pro.

4. Where data comes from

• Small data (a handful of numbers, a short series): inline it in the TSX as before.
• K-line, always through a tool — never hand-typed bars. Use snapshot_candles({ slug, name, symbol }) for a post-hoc read: the server builds a three-timeframe CandleFeed and writes journal/canvases/<slug>.<name>.json; import snap from './<name>.json' and pass it to CandleChart as source={snap} tf="m5". Use useCandles(symbol) instead only when the user explicitly wants to watch the market live — it returns a live-updating CandleFeed. Either way CandleChart never takes hand-typed bars for real market data.
• Any other data too big or awkward to inline: save_canvas_data({ slug, name, json }) writes journal/canvases/<slug>.<name>.json, then import x from './<name>.json' in the source. Both data tools require the canvas (the slug) to already exist — save_canvas first if it does not.
• Live quotes: useQuote(symbol) returns a live-updating QuoteCell | null, e.g. for Stat. Its fields are last、pct、regularLast、regularPct、session、turnover?、 asOf?；QuoteCell / CandleFeed / CandleFeedTf / TimeframeKey 的完整定义在 $KANSOKU_APP_SKILLS_DIR/canvas/sdk/shared.d.ts。
• Caption discipline: a canvas driven by useQuote / useCandles writes Source as 「实时」; one driven by a snapshot file writes the data's cutoff time, taken from CandleFeed.asOf.
• The only permitted empty state is <CandleChart source={null} .../> rendering its built-in「等待行情…」placeholder while a live feed has not delivered a first frame. Every other empty state is still forbidden (see below).
• Live subscription budget: at most 6 combined useQuote / useCandles calls per canvas.

Never render empty states. No data means omit the element — no placeholder text, no 「暂无数据」, no zeroed rows, no empty chart frame. Coverage is the sole exception; naming gaps is its job. If the whole canvas would be empty, say what is missing instead.

Label every plot. Charts get screenshotted alone. Each needs a title naming the specific measure (08-28 相对各自开盘价（都从 0 起）, not 走势图), yUnit only when the axis carries a real dimension (% / USD / 亿) — a category axis of tickers takes no xUnit — series names when multi-series, and any transformation stated (归一化 / 累计 / 相对开盘). A missing title renders as Untitled — never ship that. A Section holding one chart gets no title of its own: the chart title is the heading.

Components. The table below is the complete allow-list; referencing an export that does not exist — or inventing a prop — is the most common failure, and an unknown prop is silently dropped rather than erroring. Exact prop shapes are declared next to this file in $KANSOKU_APP_SKILLS_DIR/canvas/sdk/. Use bash cat to read them instead of guessing, starting with core.d.ts — it holds everything the mandatory parts of the skeleton use (layout, text, Stat, Table, Compare, Coverage, Source). Read the rest only when you reach for them: charts.d.ts, CandleChart.d.ts, analysis.d.ts (Scenarios / RRPlan / Timeline), control.d.ts, theme.d.ts, live.d.ts (useQuote / useCandles), shared.d.ts (QuoteCell / CandleFeed 等行情数据结构).

Four of them validate themselves against the discipline rules: Scenarios flags probabilities that miss 100 (TD-SCENARIO-01), RRPlan reddens reward-to-risk under 1.5 (TD-RR-01), Coverage carries TD-DATA-01, Source carries TD-DATA-02.

Interactivity is useState / useMemo plus Toggle / Select / Param. There is no useEffect.

Param only rewrites numbers already in the canvas. Do not use it to switch symbols, switch timeframes, or trigger a new fetch. Give both min and max or neither — one side alone is rejected at save. Native <input> / <textarea> are rejected; use Param / Toggle / Select.

Design guidance

Flat, dense, square. No gradients, no emojis, no shadows, no corner radius beyond 2px. A canvas that looks like a generic dashboard is a failed canvas.

Structure — five parts, fixed order

Skip a part with no content. Never reorder. Never push the conclusion to the bottom.

Parts 1 and 5 are mandatory. All data and no conclusion is not acceptable.

Hierarchy and color

The conclusion and the number driving it get space; detail stays compact. Squint test: blur your eyes — can you tell what this canvas concluded?

tone encodes price direction only (up / down / neutral), never good-versus-bad — 「亏损收窄」is good news with a down direction, and up makes it read backwards. Directionless numbers (成交额, 市值, 天数) take no tone. Callout tone="warn" means "hold off", at most one per canvas.

Hard limits

Grid columns ≤ 4 · Stat ≤ 4 per screen · charts ≤ 6 per canvas · Text paragraph ≤ 3 lines · no Section for fewer than 2 elements.

Say X → use Y

Nothing on the left may be hand-rolled with Table.

Slop patterns — forbidden

Two or more of these means redesign.

• All data, no conclusion — the most common failure.
• Hand-rolled tables — anything from the mapping table rebuilt as Table.
• Intent attribution — 「主力在出货」「有人故意砸盘」. Unfalsifiable (TD-INTENT-01); cite price, volume, structure.
• Narrating noise — giving a ±2% day a cause (TD-NOISE-01).
• Unlabeled numbers — no unit, no time basis.
• Emojis as icons, status markers, or bullets.
• Rainbow coloring — most elements are neutral; color is scarce and means something.
• Wall of identical cards — mix open sections with cards.
• Giant text — nothing above H1, never H1 stacked on H1.

Self-check before saving

1. Conclusion visible on the first screen?
2. Every number carries a unit and a time basis?
3. Nothing from the mapping table hand-rolled with Table?
4. Coverage or Source states the data boundary?
5. Slop list scanned?
6. Squint test: does one thing stand out?

Skeleton

The five-part shape as a real, typechecked file: apps/web/src/features/canvas/demo/skeleton.canvas.tsx. Read it and adapt it — do not invent another structure. Every component at once: apps/web/src/features/canvas/demo/kitchenSink.canvas.tsx, viewable at /canvases/demo.

Handing it over

Tell the user the slug so they can open it beside the chat. First canvas of the conversation: one sentence on what a canvas is. Canvas they did not ask for: one sentence on why it beat plain text. Later ones: just the slug.

Troubleshooting

rejected: lists one line per reason — fix those, do not work around them. Save also rejects unknown @kansoku/canvas exports, unknown JSX tags, invented props, and source that fails to compile (invalid TSX or leftover imports). save_canvas refuses outright until this skill has been read once in this conversation.

Compile and runtime errors are written into journal/canvases/.meta.json; inspect that file with bash cat -- journal/canvases/.meta.json when the diagnostic record is needed.

A blank canvas almost always referenced an export that does not exist. A prop that has no effect was invented — use bash cat to check it against the declarations in $KANSOKU_APP_SKILLS_DIR/canvas/sdk/.

missing data file: <slug>.<name>.json means the source imports a data file that has not been written yet — call save_canvas_data or snapshot_candles with that name first, then save_canvas / apply_patch.