tsquare 0.1.0 → 0.3.0

package/README.md

@@ -28,15 +28,29 @@ Requires Node 20 or newer. To work on tsquare itself, clone the repo, run `npm i
 
 ## Playground
 
+Online at [tsquare.dev/playground](https://tsquare.dev/playground), or locally:
+
 ```bash
-npm run playground   # http://localhost:4321
+npx tsquare playground   # http://localhost:4321
 ```
 
-- **Editor:** live render as you type, problems listed by line (click one to jump there), and SVG/PNG export. Paste a whole model reply and it keeps just the code block.
-- **Components:** every component with its props and a rendered example you can open in the editor. It's generated from the catalog, so it can't drift from what the renderer accepts.
-- **Prompt:** the system prompt for models, with a copy button.
+- **Editor:** syntax highlighting, autocomplete for components, options, props, icons and colors, and problems underlined by line. Paste a whole model reply and it keeps just the code block.
+- **Preview:** renders as you type. Zoom and pan (⌘/Ctrl + scroll or pinch), jump to a single screen, or go full screen.
+- **Links:** copy a share link that reopens the wireframe in the playground, or an image link (SVG, PNG, Markdown, HTML) to embed it anywhere.
+- **Examples** with thumbnails, **light and dark** themes, a resizable split, and SVG/PNG export.
+- **Components:** every component with its props and a rendered example. **Prompt:** the system prompt for models, with a copy button.
+
+The local playground uses the same renderer as the CLI; its links point to tsquare.dev. In this repo, `npm run playground` runs it from source.
+
+## Image links
+
+A wireframe can be embedded anywhere an image works (Notion, GitHub, docs sites) with a link that contains the wireframe itself:
+
+```markdown
+![Login](https://tsquare.dev/svg/zNYwxDsIwEAT7vGJ…)
+```
 
-It renders on a local Node server using the same code as the CLI.
+The playground's **Copy link** menu makes these. The text is compressed into the URL, not encrypted, so anyone with the link can read it; see [privacy](https://tsquare.dev/privacy). `encodeWireframe` and `decodeWireframe` in the library produce and read the same links.
 
 ## The language
 
@@ -51,7 +65,7 @@ One element per line; children are indented two spaces under their parent. The f
 | `tabs items=[All notes, Pinned]` | lists in `[ ]`, items separated by commas; an item can contain spaces |
 | `data=[["$1,200", "Smith, J"]]` | quote an item that contains a comma (`\"` for a quote inside quotes) |
 | `tabbar items=[{label=Home icon=home}]` | objects in `{ }` |
-| `# note to self` | comment |
+| `# note to self` | a comment, on its own line only; elsewhere `#` is text (`[#1001, #1002]`) |
 
 If a bare word could mean two props (for example `start`, which is both an `align` and a `justify` value), write it as `key=value`. Code fences (```` ``` ````) are ignored, so a model's reply can be rendered as-is.
 
@@ -95,13 +109,25 @@ tsquare render <file.tsq|-> [-o out.svg|out.png] [--scale 2]
 tsquare check  <file.tsq|->        # problems by line number
 tsquare fmt    <file.tsq|-> [-w]   # canonical formatting (drops comments)
 tsquare prompt                     # system prompt for models
+tsquare playground [--port 4321]   # live editor, component reference, prompt
 ```
 
 Use `-` to read from stdin. In this repo, run them through npm: `npm run check -- file.tsq`. Files use the `.tsq` extension; the CLI reads any text file.
 
+## Library
+
+```ts
+import { renderWireframe, compileWireframe, formatIssues } from "tsquare";
+
+const { issues } = compileWireframe(source);           // problems by line, empty when valid
+const png = await renderWireframe(source, { format: "png", scale: 2 });
+```
+
+`tsquare/playground` exports the playground's request handler, for hosting it inside your own Node server. See [Using it with AI](docs/ai.md) for the prompt and the repair loop.
+
 ## Using it with Claude (skill)
 
-`skill/tsquare/` is a Claude skill: the syntax, the component reference, and a workflow of write → `tsquare check` → `tsquare render` → look at the PNG and fix. Copy it to `~/.claude/skills/tsquare` (all projects) or `<project>/.claude/skills/tsquare`, and make the `tsquare` command available (`npm link` in this repo). Rebuild it after catalog changes with `npm run skill`.
+`skill/tsquare/` is a Claude skill: the syntax, the component reference, and a workflow of write → `tsquare check` → `tsquare render` → look at the PNG and fix. Copy it to `~/.claude/skills/tsquare` (all projects) or `<project>/.claude/skills/tsquare`, and make sure `npx tsquare` runs where Claude works. Rebuild it after catalog changes with `npm run skill`.
 
 ## How it works
 
@@ -124,7 +150,7 @@ How often models write valid tsquare on the first try, with no repair round:
 
 | | Sonnet | Haiku |
 |---|---|---|
-| Valid on the first try (20 requests) | 100% | 85% |
+| Valid on the first try (20 requests) | 100% | 80% |
 | Median tokens per wireframe (JSON took about 4× as many) | 184 | 210 |
 | Color checks passed (7 requests) | 11/11 | 11/11 |
 

package/bin/tsquare.js

@@ -1,7 +1,3 @@
 #!/usr/bin/env node
-// The CLI is TypeScript (with JSX components); tsx loads it at runtime so
-// `npm link` and `npx tsquare` work without a build step.
-import { register } from "tsx/esm/api";
-
-register();
-await import("../src/cli.ts");
+// Runs the built CLI (npm run build writes dist/).
+import "../dist/cli.js";