tsquare 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsquare",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Wireframes in plain text: easy for LLMs to write, fast to render as SVG or PNG.",
   "keywords": [
     "wireframe",
@@ -23,13 +23,26 @@
     "url": "https://github.com/tsquare-js/tsquare/issues"
   },
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./playground": {
+      "types": "./dist/playground/index.d.ts",
+      "import": "./dist/playground/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "tsquare": "bin/tsquare.js"
   },
   "files": [
     "bin/",
-    "src/",
+    "dist/",
     "skill/tsquare/",
+    "examples/*.tsq",
+    "assets/mark.png",
     "LICENSE",
     "README.md"
   ],
@@ -41,28 +54,31 @@
     "check": "tsx src/cli.ts check",
     "fmt": "tsx src/cli.ts fmt",
     "prompt": "tsx src/cli.ts prompt",
-    "playground": "tsx playground/server.ts",
+    "playground": "tsx src/cli.ts playground",
     "skill": "tsx skill/build.ts",
     "docs": "tsx docs/build.ts",
     "typecheck": "tsc",
     "examples": "for f in examples/*.tsq; do tsx src/cli.ts render $f -o ${f%.tsq}.png --scale 2; done",
     "eval:prompts": "tsx eval/prompts.ts",
-    "eval:score": "tsx eval/score.ts"
+    "eval:score": "tsx eval/score.ts",
+    "build": "tsx scripts/build.ts",
+    "prepare": "npm run build"
   },
   "dependencies": {
     "@fontsource/inter": "5.3.0",
     "@json-render/core": "^0.21.0",
     "@json-render/image": "^0.21.0",
     "@resvg/resvg-js": "^2.6.2",
+    "@types/node": ">=20",
+    "@types/react": "^19.3.0",
     "lucide": "1.48.0",
     "react": "^19.3.0",
-    "tsx": "^4.23.15",
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^26.6.3",
-    "@types/react": "^19.3.0",
+    "esbuild": "^0.28.2",
     "gpt-tokenizer": "^4.0.0",
+    "tsx": "^4.23.15",
     "typescript": "^7.0.2"
   }
 }

package/skill/tsquare/SKILL.md

@@ -13,13 +13,13 @@ tsquare is a small text language for UI wireframe boards. You write a `.tsq` fil
 2. **Check:** `tsquare check <name>.tsq`. It lists problems by line, with the valid options or a "did you mean". Fix every one and check again until it says the file is valid.
 3. **Render:** `tsquare render <name>.tsq -o <name>.png --scale 2` (use `-o <name>.svg` for docs that take SVG).
 4. **Look at the PNG** before showing it. The checker can't see layout, so check for:
-   - content cut off at the bottom of a screen (screens have a fixed height; nothing warns about clipping). Remove content, split it into another screen, or use `device=custom` with a larger `height`.
+   - content cut off at the bottom of a screen (screens have a fixed height; nothing warns about clipping). Remove content, split it into another screen, or give the screen a larger `height` (it works on any device).
    - cramped rows, or text squeezed into narrow columns.
    - anything the request asked for that's missing.
    Fix the `.tsq` and render again.
 5. **Deliver** the image path and the `.tsq` source, so the user can edit it later.
 
-If `tsquare` isn't found, stop and ask the user how it's installed. From a checkout of the repo, `npm link` makes the command available.
+If `tsquare` isn't installed, run it through npx (`npx tsquare check <name>.tsq`); it needs Node 20 or newer. If that fails, stop and ask the user how they want it installed.
 
 ## Keep in mind
 
@@ -35,7 +35,7 @@ A line is the component name in lowercase, followed by arguments separated by sp
 - a bare word that is one of the component's option values sets that option: phone, desktop, primary, ghost, row, sm, left, bottom, password, …
 - a bare prop name sets a boolean prop to true: checked, fullWidth, grow, muted. `off` and `unchecked` set on/checked to false
 - key=value sets any prop. Values: "string", number, true/false, bare word, [list, of, values], {key=value key=value}
-- # starts a comment
+- `#` after a space starts a comment that runs to the end of the line
 
 Lists: items are separated by commas, and an item can contain spaces without quotes: [All notes, Pinned, Shared]. To put a comma inside an item, quote the item: ["$1,200", "Smith, J"]. Inside quotes, write \" for a quote character. Numbers in a list of text are fine: [2023, 2024].
 

package/skill/tsquare/reference.md

@@ -15,8 +15,8 @@ Root canvas (artboard). Holds Screens side by side, plus optional Notes. Must be
 One view of the product in a device frame. Children stack vertically.
 - name: string (main text) — Label shown above the screen
 - device: "phone" | "tablet" | "desktop" | "custom"
-- width: number — Only for device=custom
-- height: number — Only for device=custom
+- width: number — Overrides the device width
+- height: number — Overrides the device height, e.g. height=1400 for a long scrolling page
 - chrome: boolean — Phone status bar / desktop browser bar. Default true for phone and desktop.
 - padding: number
 - gap: number

package/src/catalog.ts

@@ -1,329 +0,0 @@
-import { defineCatalog } from "@json-render/core";
-import { z } from "zod";
-import { ACCENTS, accentMessage, isAccent } from "./colors";
-import { isIcon, unknownIconMessage } from "./icons";
-import { wireframeSchema } from "./schema";
-
-// Every prop is optional so hand-written specs stay short.
-const o = <T extends z.ZodType>(t: T) => t.nullish();
-
-const align = z.enum(["start", "center", "end", "stretch"]);
-const justify = z.enum(["start", "center", "end", "between", "around"]);
-const iconName = z
-  .string()
-  .refine(isIcon, { error: (iss) => unknownIconMessage(String(iss.input)) })
-  .describe("Lucide icon name in kebab-case, e.g. menu, search, arrow-left, settings, bell, user");
-
-export const componentDefinitions = {
-  // ── Canvas ────────────────────────────────────────────────────────────
-  Board: {
-    props: z.object({
-      title: o(z.string()),
-      layout: o(z.enum(["row", "grid"])).describe("row = all screens side by side; grid = wrap every `columns` screens"),
-      columns: o(z.number().int().min(1)),
-      gap: o(z.number()),
-      padding: o(z.number()),
-      accent: o(z.string().refine(isAccent, { error: (iss) => accentMessage(String(iss.input)) })).describe(
-        `The one UI color: primary buttons, solid badges, checked controls, toggles, active tabs, ghost buttons. ${Object.keys(ACCENTS).join(", ")}, or a hex color like #1a73e8. Omit for grayscale.`,
-      ),
-    }),
-    slots: ["default"],
-    description: "Root canvas (artboard). Holds Screens side by side, plus optional Notes. Must be the root element.",
-    example: { title: "Checkout flow", layout: "row", gap: 64 },
-  },
-  Screen: {
-    props: z.object({
-      name: o(z.string()).describe("Label shown above the screen"),
-      device: o(z.enum(["phone", "tablet", "desktop", "custom"])),
-      width: o(z.number()).describe("Only for device=custom"),
-      height: o(z.number()).describe("Only for device=custom"),
-      chrome: o(z.boolean()).describe("Phone status bar / desktop browser bar. Default true for phone and desktop."),
-      padding: o(z.number()),
-      gap: o(z.number()),
-    }),
-    slots: ["default"],
-    description: "One view of the product in a device frame. Children stack vertically.",
-    example: { name: "Home", device: "phone" },
-  },
-  Note: {
-    props: z.object({
-      text: z.string(),
-      color: o(z.enum(["yellow", "blue", "pink", "green"])),
-      width: o(z.number()),
-    }),
-    slots: [],
-    description: "Sticky-note annotation. Put it on the Board beside screens, or inside a Screen next to what it explains.",
-    example: { text: "Empty state TBD", color: "yellow" },
-  },
-
-  // ── Layout ────────────────────────────────────────────────────────────
-  Stack: {
-    props: z.object({
-      direction: o(z.enum(["row", "column"])),
-      gap: o(z.number()),
-      padding: o(z.number()),
-      align: o(align),
-      justify: o(justify),
-      wrap: o(z.boolean()),
-      grow: o(z.boolean()).describe("Fill remaining space in the parent"),
-      width: o(z.union([z.number(), z.string()])).describe("Fixed width, e.g. 240 for a sidebar"),
-      border: o(z.enum(["none", "right", "left", "top", "bottom", "all"])),
-      fill: o(z.boolean()).describe("Light gray background"),
-    }),
-    slots: ["default"],
-    description: "Flex container. The main layout primitive (rows, columns, sidebars, toolbars).",
-    example: { direction: "row", gap: 12, align: "center" },
-  },
-  Grid: {
-    props: z.object({
-      columns: z.number().int().min(1),
-      gap: o(z.number()),
-      padding: o(z.number()),
-    }),
-    slots: ["default"],
-    description: "Equal-width columns that wrap. Good for card grids and galleries.",
-    example: { columns: 3, gap: 16 },
-  },
-  Card: {
-    props: z.object({
-      title: o(z.string()),
-      padding: o(z.number()),
-      gap: o(z.number()),
-      variant: o(z.enum(["outline", "filled"])),
-      grow: o(z.boolean()),
-      width: o(z.union([z.number(), z.string()])).describe("Fixed width, e.g. 320. Default fills the space."),
-    }),
-    slots: ["default"],
-    description: "Bordered container with optional title. Children stack vertically.",
-    example: { title: "Revenue", variant: "outline" },
-  },
-  Divider: {
-    props: z.object({ vertical: o(z.boolean()) }),
-    slots: [],
-    description: "Thin separator line.",
-    example: {},
-  },
-  Spacer: {
-    props: z.object({
-      size: o(z.number()).describe("Fixed size in px. Omit to fill remaining space."),
-    }),
-    slots: [],
-    description: "Empty space. Without a size it grows to push siblings apart.",
-    example: { size: 16 },
-  },
-
-  // ── Content ───────────────────────────────────────────────────────────
-  Heading: {
-    props: z.object({
-      text: z.string(),
-      level: o(z.union([z.literal(1), z.literal(2), z.literal(3)])),
-      align: o(z.enum(["left", "center", "right"])),
-    }),
-    slots: [],
-    description: "Heading text, level 1 (largest) to 3.",
-    example: { text: "Welcome back", level: 1 },
-  },
-  Text: {
-    props: z.object({
-      text: o(z.string()),
-      lines: o(z.number().int().min(1)).describe("Draw N placeholder lines instead of real text"),
-      size: o(z.enum(["sm", "md", "lg"])),
-      muted: o(z.boolean()),
-      bold: o(z.boolean()),
-      align: o(z.enum(["left", "center", "right"])),
-    }),
-    slots: [],
-    description: "Body text, or placeholder lines when `lines` is set and `text` is not.",
-    example: { lines: 3 },
-  },
-  Image: {
-    props: z.object({
-      height: o(z.number()),
-      width: o(z.union([z.number(), z.string()])).describe("Default fills the container width"),
-      label: o(z.string()),
-      rounded: o(z.boolean()),
-    }),
-    slots: [],
-    description: "Image placeholder: a box with an X through it.",
-    example: { height: 180, label: "Hero photo" },
-  },
-  Icon: {
-    props: z.object({
-      name: o(iconName),
-      size: o(z.number()),
-    }),
-    slots: [],
-    description: "Line icon from Lucide.",
-    example: { name: "search", size: 20 },
-  },
-  Avatar: {
-    props: z.object({
-      initials: o(z.string()),
-      size: o(z.number()),
-    }),
-    slots: [],
-    description: "Round avatar with initials or a person silhouette.",
-    example: { initials: "JD", size: 40 },
-  },
-  Badge: {
-    props: z.object({
-      label: z.string(),
-      variant: o(z.enum(["solid", "outline"])),
-      tone: o(z.enum(["neutral", "success", "warning", "danger"])).describe("Status color. Default neutral (the accent for solid badges)"),
-    }),
-    slots: [],
-    description: "Small pill label for counts or statuses.",
-    example: { label: "New", variant: "solid" },
-  },
-
-  // ── Controls ──────────────────────────────────────────────────────────
-  Button: {
-    props: z.object({
-      label: o(z.string()),
-      variant: o(z.enum(["primary", "secondary", "ghost"])),
-      size: o(z.enum(["sm", "md", "lg"])),
-      icon: o(iconName),
-      fullWidth: o(z.boolean()),
-    }),
-    slots: [],
-    description: "Button. Primary is filled, secondary is outlined, ghost is text only.",
-    example: { label: "Continue", variant: "primary", fullWidth: true },
-  },
-  Input: {
-    props: z.object({
-      label: o(z.string()),
-      placeholder: o(z.string()),
-      value: o(z.string()),
-      type: o(z.enum(["text", "password", "search", "email"])),
-      multiline: o(z.number().int().min(1)).describe("Number of rows; 2 or more makes a textarea"),
-      helper: o(z.string()),
-      error: o(z.boolean()).describe("Validation error: red border and red helper text"),
-      grow: o(z.boolean()).describe("Fill the remaining space in a row"),
-      width: o(z.union([z.number(), z.string()])).describe("Fixed width, e.g. 320. Default fills the space."),
-    }),
-    slots: [],
-    description: "Text field with optional label. Set multiline for a textarea.",
-    example: { label: "Email", placeholder: "you@example.com" },
-  },
-  Checkbox: {
-    props: z.object({ label: o(z.string()), checked: o(z.boolean()) }),
-    slots: [],
-    description: "Checkbox with label.",
-    example: { label: "Remember me", checked: true },
-  },
-  Radio: {
-    props: z.object({ label: o(z.string()), checked: o(z.boolean()) }),
-    slots: [],
-    description: "Radio button with label.",
-    example: { label: "Monthly", checked: true },
-  },
-  Toggle: {
-    props: z.object({ label: o(z.string()), on: o(z.boolean()) }),
-    slots: [],
-    description: "On/off switch with label on the left.",
-    example: { label: "Notifications", on: true },
-  },
-  Select: {
-    props: z.object({
-      label: o(z.string()),
-      value: o(z.string()),
-      placeholder: o(z.string()),
-      width: o(z.union([z.number(), z.string()])).describe("Fixed width, e.g. 320. Default fills the space."),
-    }),
-    slots: [],
-    description: "Dropdown field (closed state).",
-    example: { label: "Country", value: "United States" },
-  },
-
-  // ── Navigation & data ─────────────────────────────────────────────────
-  NavBar: {
-    props: z.object({
-      title: o(z.string()),
-      leading: o(z.enum(["none", "menu", "back", "close", "logo"])),
-      actions: o(z.array(iconName)).describe("Icon names shown on the right"),
-      align: o(z.enum(["left", "center"])),
-    }),
-    slots: [],
-    description: "Top app bar. Place first in a Screen.",
-    example: { title: "Inbox", leading: "menu", actions: ["search", "more-vertical"] },
-  },
-  TabBar: {
-    props: z.object({
-      items: z.array(z.object({ label: z.string(), icon: o(iconName) })),
-      active: o(z.number().int()),
-    }),
-    slots: [],
-    description: "Bottom tab bar for mobile. Place last in a Screen (before overlays).",
-    example: { items: [{ label: "Home", icon: "home" }, { label: "Profile", icon: "user" }], active: 0 },
-  },
-  Tabs: {
-    props: z.object({
-      items: z.array(z.string()),
-      active: o(z.number().int()),
-    }),
-    slots: [],
-    description: "In-page tabs with an underline on the active one.",
-    example: { items: ["Overview", "Activity", "Settings"], active: 0 },
-  },
-  List: {
-    props: z.object({ dividers: o(z.boolean()), grow: o(z.boolean()) }),
-    slots: ["default"],
-    description: "Vertical list of ListItems.",
-    example: { dividers: true },
-  },
-  ListItem: {
-    props: z.object({
-      title: o(z.string()),
-      subtitle: o(z.string()),
-      leading: o(z.enum(["none", "icon", "avatar", "image", "checkbox"])),
-      icon: o(iconName),
-      trailing: o(z.enum(["none", "chevron", "toggle", "text", "badge", "icon"])),
-      trailingText: o(z.string()),
-      trailingIcon: o(iconName),
-    }),
-    slots: [],
-    description: "Row in a List. Omit title for a placeholder bar.",
-    example: { title: "Account", subtitle: "Email, password", leading: "icon", icon: "user", trailing: "chevron" },
-  },
-  Table: {
-    props: z.object({
-      columns: z.array(z.string()),
-      rows: o(z.number().int()).describe("Placeholder rows when `data` is not given"),
-      data: o(z.array(z.array(z.string()))),
-    }),
-    slots: [],
-    description: "Table with headers. Rows are placeholder bars unless `data` is given.",
-    example: { columns: ["Name", "Status", "Date"], rows: 5 },
-  },
-
-  // ── Overlays ──────────────────────────────────────────────────────────
-  Modal: {
-    props: z.object({
-      title: o(z.string()),
-      width: o(z.number()),
-      scrim: o(z.boolean()).describe("Dim the screen behind. Default true."),
-    }),
-    slots: ["default"],
-    description: "Centered dialog over the screen. Must be a direct child of a Screen, listed last.",
-    example: { title: "Delete note?", width: 320 },
-  },
-  Drawer: {
-    props: z.object({
-      side: o(z.enum(["left", "right", "bottom"])),
-      title: o(z.string()),
-      size: o(z.number()).describe("Width for left/right, height for bottom"),
-      scrim: o(z.boolean()).describe("Dim the screen behind. Default true."),
-      handle: o(z.boolean()).describe("Grab handle on bottom sheets. Default true for bottom."),
-    }),
-    slots: ["default"],
-    description:
-      "Panel sliding in from an edge: side nav (left), filters/details (right), or bottom sheet. Must be a direct child of a Screen, listed last.",
-    example: { side: "left", title: "Menu", size: 300 },
-  },
-};
-
-export const catalog = defineCatalog(wireframeSchema, {
-  components: componentDefinitions,
-});
-
-export type ComponentName = keyof typeof componentDefinitions;

package/src/colors.ts

@@ -1,82 +0,0 @@
-/**
- * The only colors a wireframe can set: a board-level accent and a few fixed
- * status tones. Everything else stays grayscale.
- */
-import { theme } from "./layout";
-import { closeMatches } from "./suggest";
-
-/** Named accents. Each keeps white text above 4.5:1 contrast. */
-export const ACCENTS = {
-  blue: "#2563eb",
-  indigo: "#4f46e5",
-  violet: "#7c3aed",
-  pink: "#db2777",
-  red: "#dc2626",
-  orange: "#c2410c",
-  green: "#15803d",
-  teal: "#0f766e",
-} as const;
-
-/** Status tones for badges and input errors. They don't change with the accent. */
-export const TONES = {
-  success: "#15803d",
-  warning: "#b45309",
-  danger: "#dc2626",
-} as const;
-
-const HEX = /^#[0-9a-fA-F]{6}$/;
-
-export const isAccent = (v: string) => v in ACCENTS || HEX.test(v);
-
-export function accentMessage(v: string) {
-  const names = Object.keys(ACCENTS);
-  const close = closeMatches(v, names);
-  return `unknown accent "${v}"` + (close.length ? ` (did you mean ${close.join(", ")}?)` : "") +
-    `; use one of ${names.join(", ")}, or a hex color like #1a73e8`;
-}
-
-function luminance(hex: string) {
-  const [r, g, b] = [1, 3, 5]
-    .map((i) => parseInt(hex.slice(i, i + 2), 16) / 255)
-    .map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
-
-function contrast(a: string, b: string) {
-  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
-  return (hi + 0.05) / (lo + 0.05);
-}
-
-/** Mix a color toward black until it reads on white (for text, underlines, icons). */
-function readableOnWhite(hex: string) {
-  let [r, g, b] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
-  let out = hex;
-  for (let k = 0; k < 20 && contrast(out, "#ffffff") < 4.5; k++) {
-    [r, g, b] = [r, g, b].map((v) => Math.round(v * 0.9));
-    out = "#" + [r, g, b].map((v) => v.toString(16).padStart(2, "0")).join("");
-  }
-  return out;
-}
-
-export interface Palette {
-  /** Fills for primary buttons, solid badges, checked controls, toggles that are on. */
-  accent: string;
-  /** Text and icons drawn on the accent fill. */
-  onAccent: string;
-  /** Accent as text or a line on white: active tabs, the active tab-bar item, ghost buttons. Dark gray without an accent. */
-  accentText: string;
-}
-
-/** Colors for one board. Without an accent this is exactly the grayscale theme. */
-export function paletteFor(accent?: string | null): Palette {
-  if (!accent || !isAccent(accent)) {
-    return { accent: theme.primary, onAccent: theme.onPrimary, accentText: theme.ink };
-  }
-  const hex = (ACCENTS as Record<string, string>)[accent] ?? accent.toLowerCase();
-  return {
-    accent: hex,
-    // hex accents can be light (a brand yellow): switch to dark text when white wouldn't read
-    onAccent: contrast(hex, "#ffffff") >= 3 ? "#ffffff" : theme.ink,
-    accentText: readableOnWhite(hex),
-  };
-}

package/src/compile.ts

@@ -1,64 +0,0 @@
-import type { Spec } from "@json-render/core";
-import { checkSpec, renderWireframePng, renderWireframeSvg } from "./render";
-import { parseWireframeText, type TextIssue } from "./text";
-
-export interface CompileResult {
-  /** The compiled spec, or null if the text couldn't be parsed at all. */
-  spec: Spec | null;
-  /** Every problem, tied to a source line. Empty means the wireframe is valid. */
-  issues: TextIssue[];
-}
-
-/**
- * Parse wireframe text and validate it against the catalog, reporting every
- * problem by line number so it can be shown to a person or fed back to a model.
- */
-export function compileWireframe(source: string): CompileResult {
-  const parsed = parseWireframeText(source);
-  const issues: TextIssue[] = [...parsed.issues];
-
-  if (parsed.spec) {
-    for (const msg of checkSpec(parsed.spec)) {
-      // checkSpec reports "<element id>[.props…]: message"; map ids back to lines
-      const m = msg.match(/^([\w-]+)(?:\.props[^:]*)?: (.*)$/);
-      const line = m ? parsed.lines[m[1]] : undefined;
-      const text = m && line ? (m[2].startsWith(`${parsed.spec.elements[m[1]].type} `) ? m[2] : `${parsed.spec.elements[m[1]].type}: ${m[2]}`) : msg;
-      // "Stack "stack-4"" → "the Stack on line 4"
-      const readable = text.replace(/(\w+) "([\w-]+)"/g, (all, type, id) =>
-        parsed.lines[id] ? `the ${type} on line ${parsed.lines[id]}` : all,
-      );
-      issues.push({ line: line ?? 1, message: readable });
-    }
-  }
-
-  // The parser and the validator can both flag the same unknown prop.
-  const seen = new Set<string>();
-  const unique = issues.filter((i) => {
-    const key = `${i.line}|${i.message.replace(/^\w+: /, "").replace(/ \(.*$/, "")}`;
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-  unique.sort((a, b) => a.line - b.line);
-  return { spec: parsed.spec, issues: unique };
-}
-
-/** One issue per line, e.g. for an error message or a model repair prompt. */
-export function formatIssues(issues: TextIssue[]) {
-  return issues.map((i) => `line ${i.line}: ${i.message}`).join("\n");
-}
-
-export class WireframeError extends Error {
-  constructor(public issues: TextIssue[]) {
-    super(`Invalid wireframe:\n${formatIssues(issues)}`);
-  }
-}
-
-/** Compile and render wireframe text. Throws WireframeError (with line-numbered issues) if it's invalid. */
-export async function renderWireframe(source: string, opts: { format?: "svg" | "png"; scale?: number } = {}) {
-  const { spec, issues } = compileWireframe(source);
-  if (!spec || issues.length) throw new WireframeError(issues);
-  return opts.format === "png"
-    ? renderWireframePng(spec, { skipValidation: true, scale: opts.scale })
-    : renderWireframeSvg(spec, { skipValidation: true });
-}