tsquare 0.2.0 → 0.3.1

package/dist/prompt.d.ts

@@ -14,7 +14,7 @@ export declare function componentDocs(): {
 }[];
 export declare function componentReference(): string;
 export declare const RULES = "## Rules\n1. The top element is a Board. The Board's children are Screens, plus optional Notes beside them.\n2. Each Screen is one view of the product. Use several Screens to show several views or states.\n3. A Screen lays out its children top to bottom. Use Stack (direction row or column) and Grid to arrange content.\n4. NavBar is pinned to the top of its Screen and TabBar to the bottom.\n5. Modal and Drawer are overlays. They must be direct children of a Screen.\n6. This is a low-fidelity wireframe. Prefer placeholders (Image boxes, Text with lines) over invented copy unless the copy matters.\n7. Only use the components and props listed below. All props are optional unless marked required.\n8. Wireframes are grayscale. The only UI colors: Board accent (one color for primary buttons, checked controls, toggles, active tabs and ghost buttons), Badge tone (success, warning, danger) and Input error. Only add an accent if the request asks for color or a brand.";
-export declare const TEXT_FORMAT = "## Output format: wireframe text\nOne element per line. Indent children two spaces under their parent. The first line is the board.\n\nA line is the component name in lowercase, followed by arguments separated by spaces:\n- \"a quoted string\" sets the component's main text prop (marked \"main text\" below)\n- a bare word that is one of the component's option values sets that option: phone, desktop, primary, ghost, row, sm, left, bottom, password, \u2026\n- a bare prop name sets a boolean prop to true: checked, fullWidth, grow, muted. `off` and `unchecked` set on/checked to false\n- key=value sets any prop. Values: \"string\", number, true/false, bare word, [list, of, values], {key=value key=value}\n- `#` after a space starts a comment that runs to the end of the line\n\nLists: 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].\n\nIf a bare word could mean more than one prop, write it as key=value.";
+export declare const TEXT_FORMAT = "## Output format: wireframe text\nOne element per line. Indent children two spaces under their parent. The first line is the board.\n\nA line is the component name in lowercase, followed by arguments separated by spaces:\n- \"a quoted string\" sets the component's main text prop (marked \"main text\" below)\n- a bare word that is one of the component's option values sets that option: phone, desktop, primary, ghost, row, sm, left, bottom, password, \u2026\n- a bare prop name sets that component's yes/no prop to true, only on components that have it (see each component's props below): checked (checkbox, radio), fullWidth (button), muted (text), grow (stack, card, input, list). `off` and `unchecked` set on/checked to false\n- key=value sets any prop. Values: \"string\", number, true/false, bare word, [list, of, values], {key=value key=value}\n\nComments: a line that starts with # is a comment. A comment must be on its own line, never after an element on the same line. Anywhere else, # is ordinary text: [#1001, #1002], \"Order #12345\", accent=#1a73e8.\n\nLists: 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].\n\nIf a bare word could mean more than one prop, write it as key=value.";
 export declare const EXAMPLE_REQUEST = "Two phone screens for a recipe app: a browse screen with search, category tabs, a grid of recipe cards and a tab bar; and a recipe detail screen with its options sheet open.";
 /** The system prompt for writing wireframe text. */
 export declare function wireframePrompt(): string;

package/dist/render.d.ts

@@ -5,7 +5,27 @@ export declare class SpecError extends Error {
 }
 /** Catalog validation plus the structural rules the renderer depends on. */
 export declare function checkSpec(spec: Spec): string[];
-/** Work out the canvas size from the Board's screens (Satori needs it up front). */
+export interface BoardItem {
+    type: "Screen" | "Note";
+    /** Screen name or note text, for labels in tools like the playground. */
+    name: string;
+    /** Box on the board in px, including the screen's name label above its frame. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Where everything sits on the board: the canvas size (Satori needs it up
+ * front) and each screen's and note's box, laid out in rows exactly as the
+ * Board component does.
+ */
+export declare function boardLayout(spec: Spec): {
+    width: number;
+    height: number;
+    items: BoardItem[];
+};
+/** The canvas size for a board. */
 export declare function boardSize(spec: Spec): {
     width: number;
     height: number;

package/dist/share.d.ts

@@ -0,0 +1,8 @@
+/** Largest decoded text accepted, in bytes. Plenty for a board; stops a tiny URL from inflating into megabytes. */
+export declare const MAX_SHARED_TEXT = 64000;
+export declare function encodeWireframe(text: string): string;
+/**
+ * The wireframe a link carries, upgraded to the current language: a link made
+ * by an older version means today what it meant then (see upgrade.ts).
+ */
+export declare function decodeWireframe(data: string): string;

package/dist/text.d.ts

@@ -17,11 +17,16 @@
  *   key=value     → any prop; value is "string", number, true/false, word, [list] or {key=value …}
  *                   list items are separated by commas only, so [Ana Torres, Admin] is two items;
  *                   quote an item that contains a comma: ["$1,200", "Smith, J"]
- *   # comment
+ *   # comment        → only on a line of its own; anywhere else # is text ([#1001, …], accent=#1a73e8)
  */
 import type { Spec } from "@json-render/core";
 /** Which prop a quoted string fills, per component. */
 export declare const PRIMARY_PROP: Record<string, string>;
+/**
+ * For an error message: where a prop name or bare word that this component doesn't take
+ * belongs instead, e.g. fullWidth on an input → "fullWidth is a Button prop". Empty if nowhere.
+ */
+export declare function belongsElsewhere(component: string, word: string, asProp: boolean): string;
 /** What a component accepts as bare words, for docs: option values (with their prop), ambiguous values, and boolean props. */
 export declare function bareWords(component: string): {
     options: {

package/dist/upgrade.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Everything tsquare does for wireframes written in an older version of the
+ * language, kept in one place so the parser, catalog and renderer only know
+ * the current language.
+ *
+ *   upgradeWireframe(text)                    always-safe rewrites (renamed props);
+ *                                             compileWireframe runs it first
+ *   upgradeWireframe(text, { fromLink: true }) also the rules for text that came
+ *                                             from a link made by an older version;
+ *                                             decodeWireframe runs it
+ *   upgradeSpec(spec)                         the renames, for JSON specs
+ *
+ * Rewrites keep every line where it was (except moving a comment onto its own
+ * line, which only happens for links), so problems still point at the right line.
+ *
+ * Adding an upgrade: a rename goes in RENAMED_PROPS. A change in meaning goes
+ * here only if old text can be recognised without guessing; otherwise new links
+ * get a new prefix letter in share.ts and the upgrade applies to the old letter.
+ */
+/** Props renamed in 0.3.0. The prompt, docs and autocomplete only teach the new names; `tsquare fmt` rewrites old ones. */
+export declare const RENAMED_PROPS: Record<string, Record<string, string>>;
+export interface UpgradeOptions {
+    /** The text came from a link (share link or render URL), which may predate 0.3.0. */
+    fromLink?: boolean;
+}
+/** Rewrites older syntax to the current language. Text that's already current comes back unchanged. */
+export declare function upgradeWireframe(text: string, options?: UpgradeOptions): string;
+/** The renames, for a JSON spec. In place; safe to call more than once. */
+export declare function upgradeSpec<S extends {
+    elements: Record<string, {
+        type: string;
+        props?: Record<string, unknown>;
+    }>;
+}>(spec: S): S;
+/**
+ * Components whose main text may be a plain word (`avatar JD`, `icon search`), the parser's
+ * WORD_PRIMARY. Neither has option words, so their first plain word is always the main text.
+ * Kept here rather than imported, so the playground's browser bundle doesn't pull in the parser
+ * and catalog; scripts/build.ts fails if this drifts from the parser.
+ */
+export declare const PLAIN_WORD_MAIN_TEXT: string[];

package/examples/checkout.tsq

@@ -0,0 +1,15 @@
+board row "Checkout" accent=green
+  screen phone "Cart"
+    navbar "Cart" leading=back
+    list
+      listitem "Oat latte" subtitle="Large, extra shot" leading=image trailing=text trailingText="$5.40"
+      listitem "Croissant" subtitle="Warm" leading=image trailing=text trailingText="$3.20"
+    spacer
+    button primary lg "Checkout · $8.60" fullWidth
+  screen phone "Pay"
+    navbar "Cart" leading=back
+    text lines=4
+    drawer bottom "Payment" size=300
+      select "Card" value="Visa ending 6411"
+      toggle "Save card" on
+      button primary lg "Pay $8.60" fullWidth

package/examples/dashboard.tsq

@@ -0,0 +1,27 @@
+board "Analytics" accent=blue
+  screen desktop "Dashboard" padding=0 height=640
+    stack row grow
+      stack width=220 border=right fill padding=16 gap=6
+        text "Acme" bold
+        list dividers=false
+          listitem "Overview" leadingIcon=layout-grid
+          listitem "Customers" leadingIcon=users
+          listitem "Orders" leadingIcon=receipt
+          listitem "Settings" leadingIcon=settings
+      stack grow padding=24 gap=20
+        stack row justify=between align=center
+          heading "Overview" level=2
+          stack row gap=8
+            input search placeholder="Search" width=220
+            button primary "Export" leadingIcon=download
+            avatar "DM"
+        grid columns=4 gap=12
+          card "Revenue"
+            heading "$48.2k" level=2
+          card "Orders"
+            heading "1,284" level=2
+          card "Customers"
+            heading "932" level=2
+          card "Refunds"
+            heading "12" level=2
+        table columns=[Order, Customer, Status, Total] data=[["#1042", Ana Torres, Paid, "$120"], ["#1041", Ben Cho, Pending, "$80"], ["#1040", Priya Nair, Paid, "$45"]]

package/examples/notes-mobile.tsq

@@ -16,7 +16,7 @@ board row "Notes app — mobile"
       text sm "or" muted
       stack grow
         divider
-    button secondary lg "Continue with Google" fullWidth icon=globe
+    button secondary lg "Continue with Google" fullWidth leadingIcon=globe
     spacer
     text sm "New here? Create an account" align=center muted
   screen phone "2 · Notes"
@@ -24,13 +24,13 @@ board row "Notes app — mobile"
     input search placeholder="Search notes"
     tabs items=[All, Pinned, Shared] active=0
     list
-      listitem "Grocery list" subtitle="Eggs, oat milk, basil…" leading=icon icon=shopping-cart trailing=text trailingText="9:12"
-      listitem "Trip ideas" subtitle="Lisbon in October?" leading=icon icon=map trailing=badge trailingText="2"
+      listitem "Grocery list" subtitle="Eggs, oat milk, basil…" leadingIcon=shopping-cart trailing=text trailingText="9:12"
+      listitem "Trip ideas" subtitle="Lisbon in October?" leadingIcon=map trailing=badge trailingText="2"
       listitem leading=image trailing=chevron
       listitem leading=image trailing=chevron
       listitem leading=image trailing=chevron
     stack row justify=end grow align=end
-      button primary "New note" icon=plus
+      button primary "New note" leadingIcon=plus
     tabbar items=[{label=Notes icon=notebook-pen}, {label=Search icon=search}, {label=Shared icon=users}, {label=Profile icon=user}] active=0
   screen phone "3 · Side menu (drawer)"
     navbar "Notes" leading=menu actions=[bell, more-vertical]
@@ -49,12 +49,12 @@ board row "Notes app — mobile"
           text sm "dana@example.com" muted
       divider
       list dividers=false
-        listitem "All notes" leading=icon icon=notebook-pen trailing=text trailingText="24"
-        listitem "Folders" leading=icon icon=folder trailing=chevron
-        listitem "Archive" leading=icon icon=archive
-        listitem "Settings" leading=icon icon=settings
+        listitem "All notes" leadingIcon=notebook-pen trailing=text trailingText="24"
+        listitem "Folders" leadingIcon=folder trailing=chevron
+        listitem "Archive" leadingIcon=archive
+        listitem "Settings" leadingIcon=settings
       spacer
-      button secondary "Sign out" icon=log-out fullWidth
+      button secondary "Sign out" leadingIcon=log-out fullWidth
   screen phone "4 · Discard draft (modal)"
     navbar "New note" leading=close actions=[image, check] align=center
     heading "Untitled" level=2

package/examples/notes-web.tsq

@@ -7,10 +7,10 @@ board "Notes app — web"
           text "Notebook" bold
         spacer size=12
         list dividers=false
-          listitem "Overview" leading=icon icon=layout-dashboard
-          listitem "All notes" leading=icon icon=notebook-pen trailing=text trailingText="128"
-          listitem "Shared" leading=icon icon=users
-          listitem "Settings" leading=icon icon=settings
+          listitem "Overview" leadingIcon=layout-dashboard
+          listitem "All notes" leadingIcon=notebook-pen trailing=text trailingText="128"
+          listitem "Shared" leadingIcon=users
+          listitem "Settings" leadingIcon=settings
         spacer
         stack row gap=10
           avatar "DM" size=32
@@ -21,7 +21,7 @@ board "Notes app — web"
           spacer
           stack width=260
             input search placeholder=Search
-          button "New note" icon=plus
+          button "New note" leadingIcon=plus
         grid columns=3 gap=20
           card "Notes this week"
             heading "42" level=1
@@ -38,7 +38,7 @@ board "Notes app — web"
     stack row gap=12
       heading "All notes" level=1
       spacer
-      button secondary "Filters" icon=sliders-horizontal
+      button secondary "Filters" leadingIcon=sliders-horizontal
     table columns=[Title, Folder, Owner, Updated] rows=9
     drawer right "Filters" size=340
       select "Folder" placeholder="Any folder"

package/examples/sign-in.tsq

@@ -0,0 +1,14 @@
+board "Sign in"
+  screen phone "Sign in" padding=28 gap=16
+    spacer size=24
+    heading "Welcome back" level=1
+    text "Sign in to sync your notes." muted
+    input email "Email" placeholder="you@example.com"
+    input password "Password"
+    stack row justify=between
+      checkbox "Remember me" checked
+      button ghost sm "Forgot?"
+    button primary lg "Sign in" fullWidth
+    spacer
+    text sm "New here? Create an account" align=center muted
+  note "Show the error state when the password is wrong" width=200

package/examples/states.tsq

@@ -0,0 +1,16 @@
+board row "Empty and error states"
+  screen phone "No notes yet"
+    navbar "Notes" actions=[plus]
+    stack grow justify=center align=center gap=12 padding=24
+      image "Illustration" height=140 width=200
+      heading "No notes yet" level=2
+      text "Your notes will show up here." muted align=center
+      button primary "New note" leadingIcon=plus
+  screen phone "Couldn't load"
+    navbar "Notes" actions=[plus]
+    stack grow justify=center align=center gap=12 padding=24
+      icon triangle-alert size=40
+      heading "Something went wrong" level=2
+      text "Check your connection and try again." muted align=center
+      button secondary "Try again" leadingIcon=refresh-cw
+      badge "Offline" tone=warning

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsquare",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Wireframes in plain text: easy for LLMs to write, fast to render as SVG or PNG.",
   "keywords": [
     "wireframe",
@@ -76,6 +76,14 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
+    "@codemirror/autocomplete": "^6.20.3",
+    "@codemirror/commands": "^6.11.1",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/lint": "^6.9.7",
+    "@codemirror/search": "^6.7.2",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/view": "^6.43.13",
+    "@lezer/highlight": "^1.2.5",
     "esbuild": "^0.28.2",
     "gpt-tokenizer": "^4.0.0",
     "tsx": "^4.23.15",

package/skill/tsquare/SKILL.md

@@ -33,9 +33,10 @@ One element per line. Indent children two spaces under their parent. The first l
 A line is the component name in lowercase, followed by arguments separated by spaces:
 - "a quoted string" sets the component's main text prop (marked "main text" in reference.md)
 - 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
+- a bare prop name sets that component's yes/no prop to true, only on components that have it (see each component's props below): checked (checkbox, radio), fullWidth (button), muted (text), grow (stack, card, input, list). `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}
-- `#` after a space starts a comment that runs to the end of the line
+
+Comments: a line that starts with # is a comment. A comment must be on its own line, never after an element on the same line. Anywhere else, # is ordinary text: [#1001, #1002], "Order #12345", accent=#1a73e8.
 
 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

@@ -106,7 +106,8 @@ Button. Primary is filled, secondary is outlined, ghost is text only.
 - label: string (main text)
 - variant: "primary" | "secondary" | "ghost"
 - size: "sm" | "md" | "lg"
-- icon: string — Lucide icon name in kebab-case, e.g. menu, search, arrow-left, settings, bell, user
+- leadingIcon: string — Lucide icon before the label, e.g. chevron-left for Back
+- trailingIcon: string — Lucide icon after the label, e.g. chevron-right for Next
 - fullWidth: boolean
 
 ### Input
@@ -170,10 +171,10 @@ Row in a List. Omit title for a placeholder bar.
 - title: string (main text)
 - subtitle: string
 - leading: "none" | "icon" | "avatar" | "image" | "checkbox"
-- icon: string — Lucide icon name in kebab-case, e.g. menu, search, arrow-left, settings, bell, user
+- leadingIcon: string — Lucide icon on the left; setting it implies leading=icon
 - trailing: "none" | "chevron" | "toggle" | "text" | "badge" | "icon"
-- trailingText: string
-- trailingIcon: string — Lucide icon name in kebab-case, e.g. menu, search, arrow-left, settings, bell, user
+- trailingText: string — Text for trailing=text or badge; setting it implies trailing=text
+- trailingIcon: string — Lucide icon on the right; setting it implies trailing=icon
 
 ### Table
 Table with headers. Rows are placeholder bars unless `data` is given.