tsquare 0.8.0 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsquare",
-  "version": "0.8.0",
+  "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"
   },
@@ -87,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