@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills-cursor/canvas/sdk/form-primitives.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Form primitives for `cursor/canvas`. Provides themed, controlled form controls
+ * for interactive canvas apps with persistent state. All `onChange` callbacks
+ * receive the **value directly** (not a DOM event), so they pair naturally
+ * with `useCanvasState`:
+ *
+ * ```tsx
+ * const [name, setName] = useCanvasState("name", "");
+ * <TextInput value={name} onChange={setName} placeholder="Enter name…" />
+ * ```
+ */
+import { type CSSProperties, type JSX, type ReactNode } from "react";
+export type TextInputProps = {
+    value?: string;
+    /** Called with the new string value on every keystroke. */
+    onChange?: (value: string) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    type?: "text" | "email" | "password" | "number" | "url" | "search";
+    style?: CSSProperties;
+};
+/**
+ * Single-line text input (28px height). Use for names, titles, search
+ * queries, and short text fields.
+ *
+ * `onChange` receives the **string value**, not a DOM event — this pairs
+ * directly with `useCanvasState` setters.
+ *
+ * @example
+ * ```tsx
+ * const [name, setName] = useCanvasState("name", "");
+ *
+ * <TextInput value={name} onChange={setName} placeholder="Task title…" />
+ * ```
+ */
+export declare function TextInput({ value, onChange, placeholder, disabled, type, style }: TextInputProps): JSX.Element;
+export type TextAreaProps = {
+    value?: string;
+    /** Called with the new string value on every keystroke. */
+    onChange?: (value: string) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    /** Minimum visible rows. Defaults to 3. */
+    rows?: number;
+    style?: CSSProperties;
+};
+/**
+ * Multi-line text input that auto-resizes to fit its content.
+ * Use for notes, descriptions, comments, and multi-line text fields.
+ *
+ * The textarea grows as the user types. Set `rows` for the minimum visible
+ * height (defaults to 3). Override with `style={{ height: "100px" }}` for a
+ * fixed size.
+ *
+ * @example
+ * ```tsx
+ * const [notes, setNotes] = useCanvasState("notes", "");
+ *
+ * <TextArea value={notes} onChange={setNotes} placeholder="Add notes…" rows={4} />
+ * ```
+ */
+export declare function TextArea({ value, onChange, placeholder, disabled, rows, style }: TextAreaProps): JSX.Element;
+export type CheckboxProps = {
+    checked?: boolean;
+    /** Called with the new boolean value when toggled. */
+    onChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    /** Optional label rendered beside the checkbox. Clicking the label toggles the checkbox. */
+    label?: ReactNode;
+    style?: CSSProperties;
+};
+/**
+ * Checkbox with optional label (accent blue when checked).
+ *
+ * Pass `label` to render a clickable text label beside the checkbox. Without a
+ * label, provide `title` or wrap in your own `<label>` for accessibility.
+ *
+ * @example
+ * ```tsx
+ * const [agreed, setAgreed] = useCanvasState("agreed", false);
+ *
+ * <Checkbox checked={agreed} onChange={setAgreed} label="I agree to the terms" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Checkbox in a list — no label, parent handles layout
+ * <Checkbox checked={item.done} onChange={(v) => toggleItem(item.id, v)} />
+ * ```
+ */
+export declare function Checkbox({ checked, onChange, disabled, label, style }: CheckboxProps): JSX.Element;
+export type ToggleProps = {
+    checked?: boolean;
+    /** Called with the new boolean value when toggled. */
+    onChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    /** `sm` = 16px track, `md` = 20px track (default `sm`). */
+    size?: "sm" | "md";
+    style?: CSSProperties;
+};
+/**
+ * Boolean toggle switch. Uses the accent color for the "on" state and a
+ * neutral fill for "off".
+ *
+ * @example
+ * ```tsx
+ * const [enabled, setEnabled] = useCanvasState("enabled", false);
+ *
+ * <Row gap={8} align="center">
+ *   <Text>Notifications</Text>
+ *   <Spacer />
+ *   <Toggle checked={enabled} onChange={setEnabled} />
+ * </Row>
+ * ```
+ */
+export declare function Toggle({ checked, onChange, disabled, size, style }: ToggleProps): JSX.Element;
+export type SelectOption = {
+    value: string;
+    label: string;
+    disabled?: boolean;
+};
+export type SelectProps = {
+    value?: string;
+    /** Called with the new selected value. */
+    onChange?: (value: string) => void;
+    /** List of options. Each must have a unique `value`. */
+    options: SelectOption[];
+    /** Placeholder shown when no value is selected. */
+    placeholder?: string;
+    disabled?: boolean;
+    style?: CSSProperties;
+};
+/**
+ * Dropdown select (native `<select>` with themed styling).
+ *
+ * Uses a native `<select>` under the hood for reliable keyboard, screen-reader,
+ * and mobile support. The dropdown list uses OS-native styling.
+ *
+ * @example
+ * ```tsx
+ * const [priority, setPriority] = useCanvasState("priority", "medium");
+ *
+ * <Select
+ *   value={priority}
+ *   onChange={setPriority}
+ *   options={[
+ *     { value: "low", label: "Low" },
+ *     { value: "medium", label: "Medium" },
+ *     { value: "high", label: "High" },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function Select({ value, onChange, options, placeholder, disabled, style }: SelectProps): JSX.Element;
+export type IconButtonProps = {
+    /** Icon content: an SVG element, emoji, or unicode character. */
+    children: ReactNode;
+    onClick?: () => void;
+    disabled?: boolean;
+    /** Tooltip text. Always provide for accessibility since there is no text label. */
+    title?: string;
+    /**
+     * `"default"` is transparent until hovered; `"circle"` has a permanent
+     * background fill.
+     */
+    variant?: "default" | "circle";
+    /** `sm` = 16px, `md` = 20px (default `md`). */
+    size?: "sm" | "md";
+    style?: CSSProperties;
+};
+/**
+ * Compact icon-only button for inline actions on list items (delete, edit,
+ * expand, etc.). Accepts **any** `children` as the icon — use an inline SVG,
+ * an emoji, or a unicode character.
+ *
+ * Always provide `title` for accessibility (screen-reader label + tooltip).
+ *
+ * Canvas has no icon font, so pass icon content directly.
+ *
+ * @example
+ * ```tsx
+ * // Delete button on a card
+ * <IconButton title="Delete" onClick={() => remove(id)}>✕</IconButton>
+ *
+ * // Edit button with an SVG icon
+ * <IconButton title="Edit" variant="circle" size="sm" onClick={edit}>
+ *   <svg width={12} height={12} viewBox="0 0 12 12" fill="none">
+ *     <path d="M8.5 1.5l2 2L4 10H2V8z" stroke="currentColor" strokeWidth={1.2} />
+ *   </svg>
+ * </IconButton>
+ * ```
+ */
+export declare function IconButton({ children, onClick, disabled, title, variant, size, style }: IconButtonProps): JSX.Element;
+//# sourceMappingURL=form-primitives.d.ts.map

package/skills-cursor/canvas/sdk/hooks.d.ts

@@ -0,0 +1,117 @@
+import type { CanvasPalette, CanvasTokens } from "./canvas-tokens.js";
+import { type CanvasAction } from "./internal/canvas-action-dispatch.js";
+/**
+ * Host theme for the current canvas. Semantic color groups (`text`, `bg`,
+ * `fill`, `stroke`, `accent`, `diff`) live at the top level for ergonomic
+ * inline-style access; `tokens` is also present as a self-reference for
+ * callers that prefer a namespaced form.
+ */
+export interface CanvasHostTheme extends CanvasTokens {
+    readonly kind: string;
+    readonly tokens: CanvasTokens;
+    readonly palette: CanvasPalette;
+}
+/**
+ * Returns the current host theme. Falls back to dark mode when no host
+ * state is available.
+ *
+ * Semantic color groups are available directly on the returned object —
+ * `accent`, `text`, `bg`, `fill`, `stroke`, `diff` — as well as `kind`
+ * (`"dark"` | `"light"` | …) and `palette` (the flat color palette).
+ *
+ * Call `useHostTheme()` inside each component that needs theme access —
+ * the returned object is scoped to that component, not shared across
+ * function boundaries.
+ *
+ * Stable paths for `style={{ ... }}` usage:
+ * - `text.primary / secondary / tertiary / quaternary` — text hierarchy
+ * - `bg.editor / chrome / elevated` — surface backgrounds
+ * - `fill.primary / secondary / tertiary / quaternary` — tinted fills
+ * - `stroke.primary / secondary / tertiary` — borders and dividers
+ * - `accent.primary / control` — accent blue and button background
+ * - `text.link` — link color
+ * - `text.onAccent` — text on accent-colored surfaces
+ *
+ * Prefer built-in components (`Card`, `Button`, `Text`, etc.) over raw
+ * token usage. Reach for tokens only when no component covers the case,
+ * and stick to flat solid colors — no gradients, no box-shadows.
+ *
+ * @example
+ * ```tsx
+ * function Overview() {
+ *   const theme = useHostTheme();
+ *   return (
+ *     <div style={{ background: theme.fill.tertiary, color: theme.text.secondary, padding: 8 }}>
+ *       <span style={{ color: theme.accent.primary }}>Accent text</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useHostTheme(): CanvasHostTheme;
+/**
+ * Setter for `useCanvasState`. Accepts either a new value or an updater
+ * function that receives the previous value.
+ */
+export type SetCanvasState<T> = (action: T | ((prev: T) => T)) => void;
+/**
+ * Persistent state hook for canvas applications. Works like `React.useState`
+ * but the value survives rebuilds, reloads, and IDE restarts — it is stored
+ * in a `.canvas.data.json` sidecar file next to the canvas source.
+ *
+ * Each key is a unique string chosen by the canvas author. Keys are stable
+ * regardless of hook call order or component tree structure.
+ *
+ * @param key - Unique string identifier for this piece of state.
+ * @param defaultValue - Value returned when no persisted value exists for `key`.
+ * @returns A `[value, setValue]` tuple, same shape as `React.useState`.
+ *
+ * @example
+ * ```tsx
+ * function Counter() {
+ *   const [count, setCount] = useCanvasState("count", 0);
+ *   return <Button onClick={() => setCount(c => c + 1)}>{count}</Button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * interface Column { id: string; title: string; cardIds: string[] }
+ * function KanbanBoard() {
+ *   const [columns, setColumns] = useCanvasState<Column[]>("columns", [
+ *     { id: "todo", title: "To Do", cardIds: [] },
+ *     { id: "doing", title: "In Progress", cardIds: [] },
+ *     { id: "done", title: "Done", cardIds: [] },
+ *   ]);
+ *   // ...
+ * }
+ * ```
+ */
+export declare function useCanvasState<T>(key: string, defaultValue: T): [T, SetCanvasState<T>];
+export type { CanvasAction };
+/**
+ * Returns a stable `dispatch` function for triggering IDE actions from
+ * canvas buttons. Actions are fire-and-forget — the canvas does not
+ * receive a response.
+ *
+ * ## Available actions
+ *
+ * **`openAgent`** — Navigate the IDE to an agent conversation.
+ * `agentId` is the conversation UUID (the filename stem from the
+ * `agent-transcripts/` directory). Works for both local and
+ * cloud/background agents in Glass and classic IDE modes.
+ *
+ * @example
+ * ```tsx
+ * function AgentLink({ agentId, title }: { agentId: string; title: string }) {
+ *   const dispatch = useCanvasAction();
+ *   return (
+ *     <Button onClick={() => dispatch({ type: "openAgent", agentId })}>
+ *       {title}
+ *     </Button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useCanvasAction(): (action: CanvasAction) => void;
+//# sourceMappingURL=hooks.d.ts.map

package/skills-cursor/canvas/sdk/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Public API for authoring `.canvas.tsx` files via `cursor/canvas`.
+ *
+ * Be creative with layout — use Grid, Row, cards, charts, tables, and raw SVG
+ * in whatever combination serves the content. Read the canvas skill for full
+ * design guidance. Key constraints:
+ *
+ * - Colors from `useHostTheme()` tokens. No hardcoded hex.
+ * - No gradients, no box-shadows, no emojis as decoration.
+ * - Don't wrap every section in Card — mix open sections with cards.
+ * - Run the pre-delivery self-check before returning code.
+ */
+/** Charts. */
+export type { BarChartProps, ChartDataPoint, ChartSeries, ChartTone, LineChartProps, PieChartProps, } from "./chart-primitives.js";
+export { BarChart, LineChart, PieChart } from "./chart-primitives.js";
+/** DAG layout. */
+export type { DAGLayoutEdge, DAGLayoutNode, DAGLayoutOptions, DAGLayoutRank, DAGLayoutResult, } from "./dag-layout.js";
+export { computeDAGLayout } from "./dag-layout.js";
+/**
+ * Diff rendering. Compose with the generic `Card` family for file-level
+ * chrome: use `DiffView` inside a `CardBody` (with `padding: 0`) and put
+ * `DiffStats` in the enclosing `CardHeader`'s `trailing` slot.
+ */
+export type { DiffLineData, DiffLineType, DiffStatsProps, DiffViewProps, } from "./diff-view.js";
+export { DiffStats, DiffView } from "./diff-view.js";
+/** Form controls. */
+export type { CheckboxProps, IconButtonProps, SelectOption, SelectProps, TextAreaProps, TextInputProps, ToggleProps, } from "./form-primitives.js";
+export { Checkbox, IconButton, Select, TextArea, TextInput, Toggle, } from "./form-primitives.js";
+/** Host state hooks. */
+export type { CanvasAction, CanvasHostTheme, SetCanvasState } from "./hooks.js";
+export { useCanvasAction, useCanvasState, useHostTheme } from "./hooks.js";
+/** Semantic design tokens for custom styling. */
+export type { CanvasPalette, CanvasTokens } from "./theme.js";
+export { canvasPaletteDark, canvasPaletteLight, canvasTokens, canvasTokensLight, } from "./theme.js";
+export type { TodoItem, TodoListCardProps, TodoListProps, TodoStatus, } from "./todo-list.js";
+export { TodoList, TodoListCard } from "./todo-list.js";
+/** Component props types. */
+export type { ButtonProps, CalloutProps, CalloutTone, CardBodyProps, CardHeaderProps, CardProps, CardSize, CardVariant, CodeProps, DividerProps, GridProps, H1Props, H2Props, H3Props, LinkProps, PillProps, PillSize, PillTone, RowProps, StackProps, StatProps, StatTone, TableColumnAlign, TableProps, TableRowTone, TextProps, TextWeight, } from "./ui-primitives.js";
+/** Layout. */
+/** Typography. */
+/** Surfaces. */
+/** Actions. */
+/** Feedback. */
+export { Button, Callout, Card, CardBody, CardHeader, Code, Divider, Grid, H1, H2, H3, Link, 
+/** Shallow-merge two style objects. Useful for combining tokens with overrides. */
+mergeStyle, Pill, Row, Spacer, Stack, Stat, Table, Text, } from "./ui-primitives.js";
+//# sourceMappingURL=index.d.ts.map

package/skills-cursor/canvas/sdk/theme.d.ts

@@ -0,0 +1,61 @@
+export type { CanvasPalette, CanvasTokens } from "./canvas-tokens.js";
+export { canvasPaletteDark, canvasPaletteLight, canvasTokens, canvasTokensLight, } from "./canvas-tokens.js";
+/** Typography presets used by the built-in `cursor/canvas` components. */
+export declare const canvasTypography: {
+    readonly h1: {
+        readonly fontSize: "24px";
+        readonly lineHeight: "30px";
+        readonly fontWeight: 590;
+    };
+    readonly h2: {
+        readonly fontSize: "18px";
+        readonly lineHeight: "24px";
+        readonly fontWeight: 590;
+    };
+    readonly h3: {
+        readonly fontSize: "16px";
+        readonly lineHeight: "22px";
+        readonly fontWeight: 590;
+    };
+    readonly body: {
+        readonly fontSize: "14px";
+        readonly lineHeight: "20px";
+        readonly fontWeight: 400;
+    };
+    readonly small: {
+        readonly fontSize: "12px";
+        readonly lineHeight: "16px";
+        readonly fontWeight: 400;
+    };
+};
+/** Spacing scale (px). */
+export declare const canvasSpacing: {
+    readonly "0.5": 2;
+    readonly "1": 4;
+    readonly "1.5": 6;
+    readonly "2": 8;
+    readonly "2.5": 10;
+    readonly "3": 12;
+    readonly "3.5": 14;
+    readonly "4": 16;
+    readonly "4.5": 18;
+    readonly "5": 20;
+    readonly "6": 24;
+    readonly "7": 28;
+    readonly "8": 32;
+    readonly "9": 36;
+    readonly "10": 40;
+};
+export type CanvasSpacing = typeof canvasSpacing;
+/** Border radius (px). */
+export declare const canvasRadius: {
+    readonly none: 0;
+    readonly xs: 2;
+    readonly sm: 4;
+    readonly md: 6;
+    readonly lg: 8;
+    readonly xl: 12;
+    readonly full: 9999;
+};
+export type CanvasRadius = typeof canvasRadius;
+//# sourceMappingURL=theme.d.ts.map

package/skills-cursor/canvas/sdk/todo-list.d.ts

@@ -0,0 +1,49 @@
+import type { CSSProperties, JSX } from "react";
+export type TodoStatus = "pending" | "in_progress" | "completed" | "cancelled";
+export interface TodoItem {
+    readonly id: string;
+    readonly content: string;
+    readonly status: TodoStatus;
+}
+export type TodoListProps = {
+    todos: readonly TodoItem[];
+    dimmedTodoIds?: ReadonlySet<string>;
+    /** Called when a todo row is clicked (entire row is a button). */
+    onTodoClick?: (todo: TodoItem) => void;
+    style?: CSSProperties;
+};
+/**
+ * Task list with status icons and wrapping text. Each row is a **clickable**
+ * button; use `onTodoClick` to handle selection or navigation.
+ *
+ * @example
+ * ```tsx
+ * <TodoList
+ *   todos={items}
+ *   onTodoClick={(todo) => setActiveId(todo.id)}
+ * />
+ * ```
+ */
+export declare function TodoList({ todos, dimmedTodoIds, onTodoClick, style }: TodoListProps): JSX.Element | null;
+export type TodoListCardProps = {
+    todos: readonly TodoItem[];
+    dimmedTodoIds?: ReadonlySet<string>;
+    defaultExpanded?: boolean;
+    onTodoClick?: (todo: TodoItem) => void;
+    style?: CSSProperties;
+};
+/**
+ * Bordered, collapsible todo list with summary header (N of M Done). Compose
+ * with `onTodoClick` for row actions.
+ *
+ * @example
+ * ```tsx
+ * <TodoListCard
+ *   todos={items}
+ *   defaultExpanded
+ *   onTodoClick={(todo) => console.log(todo.id)}
+ * />
+ * ```
+ */
+export declare function TodoListCard({ todos, dimmedTodoIds, defaultExpanded, onTodoClick, style }: TodoListCardProps): JSX.Element | null;
+//# sourceMappingURL=todo-list.d.ts.map