tsquare 0.7.1 → 0.9.0

package/dist/playground/viewer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The zoomable board: zoom, pan, pinch, and zoom to a screen. Browser code,
+ * published as `tsquare/viewer`: the playground page uses it, and so does the
+ * VS Code extension's preview. Each brings its own markup and controls and
+ * passes the elements in; the board comes from renderWireframeSvg + boardLayout.
+ *
+ * The viewer sets the styles its math depends on (see structuralStyles), so
+ * the host only needs to size the stage and optionally style the
+ * "panning", "animate" and "stale" classes it toggles on the stage.
+ */
+import type { BoardItem } from "../render.js";
+export type { BoardItem };
+export interface ViewerElements {
+    /**
+     * The visible area; give it a size. It gets these classes, for optional styling:
+     * "panning" while dragging (cursor: grabbing), "animate" while zooming to a
+     * screen or fitting (transition the canvas's transform), and "stale" from
+     * setStale (dim the image).
+     */
+    stage: HTMLElement;
+    /** Inside the stage; holds the board image and is transformed. */
+    canvas: HTMLElement;
+    /** Where the screen chips go ("All", then one per screen). */
+    screens: HTMLElement;
+    /** Removed when the first board shows. */
+    empty?: HTMLElement | null;
+    zoomIn?: HTMLElement | null;
+    zoomOut?: HTMLElement | null;
+    /** Shows the zoom level; clicking it fits the board. */
+    zoomFit?: HTMLElement | null;
+}
+export interface Viewer {
+    show(svg: string, width: number, height: number, items: BoardItem[]): void;
+    refresh(animate?: boolean): void;
+    /** Dims the board, for when the text has problems and this is the last valid render. */
+    setStale(stale: boolean): void;
+    fit(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+}
+export declare function createViewer(el: ViewerElements, opts?: {
+    onScreenZoom?: () => void;
+    onZoom?: (scale: number) => void;
+}): Viewer;

package/dist/playground/viewer.js

@@ -0,0 +1,172 @@
+// src/playground/viewer.ts
+function structuralStyles(stage, canvas) {
+  if (getComputedStyle(stage).position === "static") stage.style.position = "relative";
+  stage.style.overflow = "hidden";
+  stage.style.touchAction = "none";
+  Object.assign(canvas.style, { position: "absolute", left: "0px", top: "0px", transformOrigin: "0 0" });
+}
+function createViewer(el, opts = {}) {
+  const { stage, canvas } = el;
+  structuralStyles(stage, canvas);
+  let img = null;
+  let size = { width: 0, height: 0 };
+  let items = [];
+  let scale = 1, x = 0, y = 0;
+  let mode = "fit";
+  const PAD = 16;
+  const label = () => {
+    if (el.zoomFit) el.zoomFit.textContent = `${Math.round(scale * 100)}%`;
+    opts.onZoom?.(scale);
+  };
+  const apply = (animate = false) => {
+    stage.classList.toggle("animate", animate);
+    canvas.style.transform = `translate(${x}px, ${y}px) scale(${scale})`;
+    label();
+  };
+  const fitRect = (r, animate) => {
+    const w = stage.clientWidth - PAD * 2, h = stage.clientHeight - PAD * 2;
+    if (w <= 0 || h <= 0 || !r.width) return;
+    scale = Math.min(w / r.width, h / r.height, 4);
+    x = PAD + (w - r.width * scale) / 2 - r.x * scale;
+    y = PAD + (h - r.height * scale) / 2 - r.y * scale;
+    apply(animate);
+  };
+  const markScreens = () => el.screens.querySelectorAll("button").forEach((b, i) => b.setAttribute("aria-pressed", String(i === 0 ? mode === "fit" : mode === i - 1)));
+  function refresh(animate = false) {
+    if (!size.width) return;
+    if (mode === "fit") fitRect({ x: 0, y: 0, ...size }, animate);
+    else if (typeof mode === "number" && items[mode]) fitRect(items[mode], animate);
+    else apply();
+    markScreens();
+  }
+  function zoomAt(factor, cx = stage.clientWidth / 2, cy = stage.clientHeight / 2) {
+    const next = Math.min(8, Math.max(0.05, scale * factor));
+    x = cx - (cx - x) * (next / scale);
+    y = cy - (cy - y) * (next / scale);
+    scale = next;
+    mode = "manual";
+    apply();
+    markScreens();
+  }
+  const fit = () => {
+    mode = "fit";
+    refresh(true);
+  };
+  function show(svg, width, height, list) {
+    const url = URL.createObjectURL(new Blob([svg], { type: "image/svg+xml" }));
+    if (!img) {
+      img = document.createElement("img");
+      img.alt = "Rendered wireframe";
+      img.draggable = false;
+      canvas.replaceChildren(img);
+      el.empty?.remove();
+    }
+    const old = img.src;
+    img.src = url;
+    if (old.startsWith("blob:")) setTimeout(() => URL.revokeObjectURL(old), 1e3);
+    const resized = width !== size.width || height !== size.height;
+    size = { width, height };
+    img.width = width;
+    img.height = height;
+    const screens = list.filter((i) => i.type === "Screen");
+    if (screens.map((s) => s.name).join("\n") !== items.filter((i) => i.type === "Screen").map((s) => s.name).join("\n")) {
+      if (typeof mode === "number") mode = "fit";
+      buildScreenChips(screens);
+    }
+    items = screens;
+    if (resized && mode === "manual") mode = "fit";
+    refresh();
+  }
+  function buildScreenChips(screens) {
+    const bar = el.screens;
+    bar.replaceChildren();
+    if (screens.length < 2) return;
+    const chip = (text, onClick) => {
+      const b = document.createElement("button");
+      b.type = "button";
+      b.textContent = text;
+      b.addEventListener("click", onClick);
+      bar.appendChild(b);
+    };
+    chip("All", fit);
+    screens.forEach((s, i) => chip(s.name || `Screen ${i + 1}`, () => {
+      mode = i;
+      refresh(true);
+      opts.onScreenZoom?.();
+    }));
+  }
+  stage.addEventListener("wheel", (e) => {
+    if (!size.width) return;
+    e.preventDefault();
+    const r = stage.getBoundingClientRect();
+    if (e.ctrlKey || e.metaKey) zoomAt(Math.exp(-e.deltaY * 0.01), e.clientX - r.left, e.clientY - r.top);
+    else {
+      x -= e.deltaX;
+      y -= e.deltaY;
+      mode = "manual";
+      apply();
+      markScreens();
+    }
+  }, { passive: false });
+  const pointers = /* @__PURE__ */ new Map();
+  let pinch = null;
+  const twoFingers = () => {
+    const [a, b] = [...pointers.values()];
+    return { mid: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }, dist: Math.hypot(a.x - b.x, a.y - b.y) };
+  };
+  stage.addEventListener("pointerdown", (e) => {
+    stage.setPointerCapture(e.pointerId);
+    pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+    stage.classList.add("panning");
+    pinch = pointers.size === 2 ? twoFingers() : null;
+  });
+  stage.addEventListener("pointermove", (e) => {
+    const prev = pointers.get(e.pointerId);
+    if (!prev) return;
+    pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+    if (pointers.size === 2 && pinch) {
+      const now = twoFingers();
+      const r = stage.getBoundingClientRect();
+      x += now.mid.x - pinch.mid.x;
+      y += now.mid.y - pinch.mid.y;
+      if (pinch.dist && now.dist) zoomAt(now.dist / pinch.dist, now.mid.x - r.left, now.mid.y - r.top);
+      else {
+        mode = "manual";
+        apply();
+        markScreens();
+      }
+      pinch = now;
+    } else {
+      x += e.clientX - prev.x;
+      y += e.clientY - prev.y;
+      mode = "manual";
+      apply();
+      markScreens();
+    }
+  });
+  const release = (e) => {
+    pointers.delete(e.pointerId);
+    pinch = pointers.size === 2 ? twoFingers() : null;
+    if (!pointers.size) stage.classList.remove("panning");
+  };
+  stage.addEventListener("pointerup", release);
+  stage.addEventListener("pointercancel", release);
+  stage.addEventListener("dblclick", fit);
+  new ResizeObserver(() => refresh()).observe(stage);
+  el.zoomIn?.addEventListener("click", () => zoomAt(1.25));
+  el.zoomOut?.addEventListener("click", () => zoomAt(0.8));
+  el.zoomFit?.addEventListener("click", fit);
+  return {
+    show,
+    refresh,
+    setStale: (stale) => {
+      stage.classList.toggle("stale", stale);
+    },
+    fit,
+    zoomIn: () => zoomAt(1.25),
+    zoomOut: () => zoomAt(0.8)
+  };
+}
+export {
+  createViewer
+};

package/dist/prompt.d.ts

@@ -13,7 +13,7 @@ export declare function componentDocs(): {
     props: PropDoc[];
 }[];
 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 and Flow lines after them (rule 10).\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, Drawer and Toast 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), Input error and Flow color. Only add an accent if the request asks for color or a brand.\n9. Any element except Board, Screen, Note and Flow can take tooltip=\"text\" to show a tooltip next to it. Select (with options), Input type=date, and Button, ListItem or NavBar (with menu) take open to show their list, calendar or menu over the screen.\n10. To show how screens connect, name elements or screens by writing #name after them (button primary \"Sign in\" #signin, screen phone \"Home\" #home), then add board-level lines after the screens: flow signin -> home \"Tap Sign in\".";
+export declare const RULES = "## Rules\n1. The top element is a Board. The Board's children are Screens, plus optional Notes beside them and Flow lines after them (rule 10).\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, Drawer and Toast 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), Input error and Flow color. Only add an accent if the request asks for color or a brand.\n9. Any element except Board, Screen, Note and Flow can take tooltip=\"text\" to show a tooltip next to it. Select (with options), Input type=date, and Button, ListItem or NavBar (with menu) take open to show their list, calendar or menu over the screen.\n10. To show how screens connect, name elements or screens by writing #name after them (button primary \"Sign in\" #signin, screen phone \"Home\" #home), then write each flow on its own line after the screens, indented like a screen (not inside one): flow signin -> home \"Tap Sign in\".\n11. Icons are Lucide names, plus brand logos named brand-\u2026: brand-google, brand-apple, brand-github, brand-facebook, brand-x, brand-notion, brand-stripe (button \"Continue with Google\" leadingIcon=brand-google). Plain apple is a fruit and x is a close icon.";
 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsquare",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Wireframes in plain text: easy for LLMs to write, fast to render as SVG or PNG.",
   "keywords": [
     "wireframe",
@@ -26,11 +26,18 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./playground": {
       "types": "./dist/playground/index.d.ts",
-      "import": "./dist/playground/index.js"
+      "import": "./dist/playground/index.js",
+      "default": "./dist/playground/index.js"
+    },
+    "./viewer": {
+      "types": "./dist/playground/viewer.d.ts",
+      "import": "./dist/playground/viewer.js",
+      "default": "./dist/playground/viewer.js"
     },
     "./package.json": "./package.json"
   },
@@ -75,6 +82,7 @@
     "@types/react": "^19.3.0",
     "lucide": "1.48.0",
     "react": "^19.3.0",
+    "simple-icons": "16.34.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {
@@ -86,9 +94,12 @@
     "@codemirror/state": "^6.7.6",
     "@codemirror/view": "^6.43.13",
     "@lezer/highlight": "^1.2.5",
+    "@types/jsdom": "^30.0.0",
     "esbuild": "^0.28.2",
     "gpt-tokenizer": "^4.0.0",
+    "jsdom": "^29.1.1",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2"
-  }
+  },
+  "gitHead": "c248211e0c39260cb4cbd59008fb1d64b54b3f08"
 }

package/skill/tsquare/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: tsquare
 description: Create low-fidelity UI wireframes and mockups (app screens, several devices side by side, boards for specs and docs) as tsquare text, then render them to PNG or SVG with the tsquare CLI. Use when asked to wireframe, mock up or sketch a UI screen, page or flow, or to add a UI mockup to a document.
+license: MIT
+compatibility: Needs Node.js 20 or newer to run the tsquare CLI (installed, or through npx).
 ---
 
 # tsquare wireframes
@@ -52,7 +54,8 @@ If a bare word could mean more than one prop, write it as key=value.
 7. Only use the components and props listed below. All props are optional unless marked required.
 8. 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), Input error and Flow color. Only add an accent if the request asks for color or a brand.
 9. Any element except Board, Screen, Note and Flow can take tooltip="text" to show a tooltip next to it. Select (with options), Input type=date, and Button, ListItem or NavBar (with menu) take open to show their list, calendar or menu over the screen.
-10. To show how screens connect, name elements or screens by writing #name after them (button primary "Sign in" #signin, screen phone "Home" #home), then add board-level lines after the screens: flow signin -> home "Tap Sign in".
+10. To show how screens connect, name elements or screens by writing #name after them (button primary "Sign in" #signin, screen phone "Home" #home), then write each flow on its own line after the screens, indented like a screen (not inside one): flow signin -> home "Tap Sign in".
+11. Icons are Lucide names, plus brand logos named brand-…: brand-google, brand-apple, brand-github, brand-facebook, brand-x, brand-notion, brand-stripe (button "Continue with Google" leadingIcon=brand-google). Plain apple is a fruit and x is a close icon.
 
 ## Example
 

package/skill/tsquare/reference.md

@@ -28,7 +28,7 @@ Sticky-note annotation. Put it on the Board beside screens, or inside a Screen n
 - width: number
 
 ### Flow
-An arrow between two elements or screens, named with #id. Written at the board level after the screens: flow signin -> home "Tap Sign in".
+An arrow between two elements or screens, named with #id. Write each flow on its own line after the screens, indented like a screen (not inside one): flow signin -> home "Tap Sign in".
 - from (required): string — The id where the arrow starts (written before ->)
 - to (required): string — The id it points at (written after ->)
 - label: string (main text)
@@ -116,7 +116,7 @@ Chart placeholder: a generic line, bar, area, pie or donut shape, no data.
 - width: number | string — Default fills the container width
 
 ### Icon
-Line icon from Lucide.
+Line icon from Lucide, or a brand logo (brand-google, brand-apple, …).
 - name: string (main text) — Lucide icon name in kebab-case, e.g. menu, search, arrow-left, settings, bell, user
 - size: number