tsquare 0.1.0 → 0.3.0

package/{src/cli.ts → dist/cli.js}

@@ -1,35 +1,44 @@
 #!/usr/bin/env node
+import {
+  WireframeError,
+  compileWireframe,
+  formatIssues,
+  printWireframeText,
+  renderWireframe,
+  wireframePrompt
+} from "./chunks/chunk-46MGJLGB.js";
+
+// src/cli.ts
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { compileWireframe, formatIssues, renderWireframe, WireframeError } from "./compile";
-import { printWireframeText } from "./print";
-import { wireframePrompt } from "./prompt";
-
-const USAGE = `tsquare — render wireframe text to SVG or PNG
+var USAGE = `tsquare \u2014 render wireframe text to SVG or PNG
 
   tsquare render <file.tsq|-> [-o out.svg|out.png] [--scale 2]
   tsquare check  <file.tsq|->      report problems by line number
   tsquare fmt    <file.tsq|-> [-w] print in canonical form (-w rewrites the file; drops comments)
   tsquare prompt                   print the system prompt for models
+  tsquare playground [--port 4321] open the playground: live editor, component reference, prompt
 
 Use - to read from stdin. Code fences (\`\`\`) in the input are ignored.
 `;
-
-async function readInput(file: string) {
+async function readInput(file) {
   if (file !== "-") return readFile(file, "utf8");
-  const chunks: Buffer[] = [];
-  for await (const c of process.stdin) chunks.push(c as Buffer);
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
   return Buffer.concat(chunks).toString("utf8");
 }
-
-async function main(argv: string[]) {
+async function main(argv) {
   const [cmd, ...rest] = argv;
-  const flag = (name: string) => {
+  const flag = (name) => {
     const i = rest.indexOf(name);
-    return i >= 0 ? rest[i + 1] : undefined;
+    return i >= 0 ? rest[i + 1] : void 0;
   };
   const file = rest.find((a, i) => (a === "-" || !a.startsWith("-")) && !["-o", "--scale"].includes(rest[i - 1]));
-
+  if (cmd === "playground") {
+    const { startPlayground } = await import("./playground/index.js");
+    startPlayground(Number(flag("--port") ?? 4321));
+    return;
+  }
   if (cmd === "prompt") {
     process.stdout.write(wireframePrompt() + "\n");
     return;
@@ -39,36 +48,31 @@ async function main(argv: string[]) {
     process.exitCode = cmd && cmd !== "help" ? 1 : 0;
     return;
   }
-
   const source = await readInput(file);
-
   if (cmd === "check") {
     const { issues } = compileWireframe(source);
     if (issues.length) {
       console.error(formatIssues(issues));
       process.exitCode = 1;
     } else {
-      console.log(`✓ ${file === "-" ? "input" : file} is valid`);
+      console.log(`\u2713 ${file === "-" ? "input" : file} is valid`);
     }
     return;
   }
-
   if (cmd === "fmt") {
     const { spec, issues } = compileWireframe(source);
     if (!spec || issues.length) throw new WireframeError(issues);
-    const out = printWireframeText(spec);
-    if (rest.includes("-w") && file !== "-") await writeFile(file, out);
-    else process.stdout.write(out);
+    const out2 = printWireframeText(spec);
+    if (rest.includes("-w") && file !== "-") await writeFile(file, out2);
+    else process.stdout.write(out2);
     return;
   }
-
   const out = flag("-o") ?? (file === "-" ? "wireframe.svg" : file.replace(/\.(tsq|wf)$/, "") + ".svg");
   const png = out.endsWith(".png");
   const data = await renderWireframe(source, { format: png ? "png" : "svg", scale: Number(flag("--scale") ?? 1) });
   await writeFile(out, data);
-  console.log(`✓ wrote ${path.relative(process.cwd(), out)}`);
+  console.log(`\u2713 wrote ${path.relative(process.cwd(), out)}`);
 }
-
 main(process.argv.slice(2)).catch((err) => {
   console.error(err instanceof WireframeError ? err.message : err);
   process.exitCode = 1;

package/dist/colors.d.ts

@@ -0,0 +1,29 @@
+/** Named accents. Each keeps white text above 4.5:1 contrast. */
+export declare const ACCENTS: {
+    readonly blue: "#2563eb";
+    readonly indigo: "#4f46e5";
+    readonly violet: "#7c3aed";
+    readonly pink: "#db2777";
+    readonly red: "#dc2626";
+    readonly orange: "#c2410c";
+    readonly green: "#15803d";
+    readonly teal: "#0f766e";
+};
+/** Status tones for badges and input errors. They don't change with the accent. */
+export declare const TONES: {
+    readonly success: "#15803d";
+    readonly warning: "#b45309";
+    readonly danger: "#dc2626";
+};
+export declare const isAccent: (v: string) => boolean;
+export declare function accentMessage(v: string): string;
+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 declare function paletteFor(accent?: string | null): Palette;

package/dist/compile.d.ts

@@ -0,0 +1,24 @@
+import type { Spec } from "@json-render/core";
+import { type TextIssue } from "./text.js";
+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 declare function compileWireframe(source: string): CompileResult;
+/** One issue per line, e.g. for an error message or a model repair prompt. */
+export declare function formatIssues(issues: TextIssue[]): string;
+export declare class WireframeError extends Error {
+    issues: TextIssue[];
+    constructor(issues: TextIssue[]);
+}
+/** Compile and render wireframe text. Throws WireframeError (with line-numbered issues) if it's invalid. */
+export declare function renderWireframe(source: string, opts?: {
+    format?: "svg" | "png";
+    scale?: number;
+}): Promise<string | Buffer<ArrayBufferLike>>;

package/dist/components.d.ts

@@ -0,0 +1,83 @@
+import React from "react";
+import { type Palette } from "./colors.js";
+import type { ComponentRenderProps } from "@json-render/image";
+/**
+ * Satori renders a subset of CSS. Rules followed here:
+ * - every element that has more than one child sets display:flex
+ * - absolute positioning is relative to the direct parent (Yoga), so overlays
+ *   are lifted out and placed by Screen rather than nested in the body
+ */
+type Dir = "row" | "column";
+type Props<P = Record<string, any>> = ComponentRenderProps<P> & {
+    dir?: Dir;
+    stretch?: boolean;
+    aligned?: boolean;
+    colors?: Palette;
+};
+/** A registry whose components all receive this board's palette as `colors`. */
+export declare function withPalette(colors: Palette): typeof registry;
+export declare function IconGlyph({ name, size, color, strokeWidth }: {
+    name?: string | null;
+    size?: number;
+    color?: string;
+    strokeWidth?: number;
+}): React.JSX.Element;
+declare function Board({ element, children }: Props): React.JSX.Element;
+declare function Screen({ element, children }: Props): React.JSX.Element;
+declare function Note({ element, dir, aligned }: Props): React.JSX.Element;
+declare function Stack({ element, children, dir: parentDir, stretch }: Props): React.JSX.Element;
+declare function Grid({ element, children }: Props): React.JSX.Element;
+declare function Card({ element, children, dir, stretch }: Props): React.JSX.Element;
+declare function Divider({ element, dir }: Props): React.JSX.Element;
+declare function Spacer({ element }: Props): React.JSX.Element;
+declare function Heading({ element }: Props): React.JSX.Element;
+declare function Text({ element }: Props): React.JSX.Element;
+declare function Image({ element, dir }: Props): React.JSX.Element;
+declare function Icon({ element, dir, aligned }: Props): React.JSX.Element;
+declare function Avatar({ element, dir, aligned }: Props): React.JSX.Element;
+declare function Badge({ element, dir, aligned, colors }: Props): React.JSX.Element;
+declare function Button({ element, dir, aligned, colors: c }: Props): React.JSX.Element;
+declare function Input({ element, dir }: Props): React.JSX.Element;
+declare function Select({ element, dir }: Props): React.JSX.Element;
+declare function Checkbox({ element, dir, aligned, colors }: Props): React.JSX.Element;
+declare function Radio({ element, dir, aligned, colors }: Props): React.JSX.Element;
+declare function Toggle({ element, colors }: Props): React.JSX.Element;
+declare function NavBar({ element }: Props): React.JSX.Element;
+declare function TabBar({ element, colors: c }: Props): React.JSX.Element;
+declare function Tabs({ element, colors: c }: Props): React.JSX.Element;
+declare function List({ element, children, dir, stretch }: Props): React.JSX.Element;
+declare function ListItem({ element, colors }: Props): React.JSX.Element;
+declare function Table({ element }: Props): React.JSX.Element;
+declare function Modal({ element, children }: Props): React.JSX.Element;
+declare function Drawer({ element, children }: Props): React.JSX.Element;
+export declare const registry: {
+    Board: typeof Board;
+    Screen: typeof Screen;
+    Note: typeof Note;
+    Stack: typeof Stack;
+    Grid: typeof Grid;
+    Card: typeof Card;
+    Divider: typeof Divider;
+    Spacer: typeof Spacer;
+    Heading: typeof Heading;
+    Text: typeof Text;
+    Image: typeof Image;
+    Icon: typeof Icon;
+    Avatar: typeof Avatar;
+    Badge: typeof Badge;
+    Button: typeof Button;
+    Input: typeof Input;
+    Checkbox: typeof Checkbox;
+    Radio: typeof Radio;
+    Toggle: typeof Toggle;
+    Select: typeof Select;
+    NavBar: typeof NavBar;
+    TabBar: typeof TabBar;
+    Tabs: typeof Tabs;
+    List: typeof List;
+    ListItem: typeof ListItem;
+    Table: typeof Table;
+    Modal: typeof Modal;
+    Drawer: typeof Drawer;
+};
+export {};

package/dist/icons.d.ts

@@ -0,0 +1,12 @@
+/** Kebab-case names for every Lucide icon (including Lucide's aliases, e.g. home and house). */
+export declare const iconNames: string[];
+/** The Lucide icon node for a kebab-case name, or undefined if there's no such icon. */
+export declare function iconNode(name: string): any;
+export declare const isIcon: (name: string) => boolean;
+/**
+ * Close matches for an unknown name: near spellings ("serach" → search) and names that
+ * share a word with it ("cart" → shopping-cart, "call" → phone-call).
+ * There are no synonyms: "notification" won't find bell.
+ */
+export declare function suggestIcons(name: string, limit?: number): string[];
+export declare function unknownIconMessage(name: string): string;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="node" preserve="true" />
+export { renderWireframe, compileWireframe, formatIssues, WireframeError, type CompileResult } from "./compile.js";
+export { wireframePrompt, repairPrompt } from "./prompt.js";
+export { printWireframeText as formatWireframe } from "./print.js";
+export { encodeWireframe, decodeWireframe, MAX_SHARED_TEXT } from "./share.js";
+export { renderWireframeSvg, renderWireframePng, checkSpec, boardSize, boardLayout, type BoardItem, type RenderWireframeOptions } from "./render.js";
+export { parseWireframeText, type TextIssue, type ParseResult } from "./text.js";
+export { catalog, componentDefinitions } from "./catalog.js";
+export { registry } from "./components.js";
+export { theme, DEVICES } from "./layout.js";

package/dist/index.js

@@ -0,0 +1,54 @@
+import {
+  DEVICES,
+  WireframeError,
+  boardLayout,
+  boardSize,
+  catalog,
+  checkSpec,
+  compileWireframe,
+  componentDefinitions,
+  formatIssues,
+  parseWireframeText,
+  printWireframeText,
+  registry,
+  renderWireframe,
+  renderWireframePng,
+  renderWireframeSvg,
+  repairPrompt,
+  theme,
+  wireframePrompt
+} from "./chunks/chunk-46MGJLGB.js";
+
+// src/share.ts
+import { deflateRawSync, inflateRawSync } from "node:zlib";
+var MAX_SHARED_TEXT = 64e3;
+function encodeWireframe(text) {
+  return "z" + deflateRawSync(Buffer.from(text, "utf8"), { level: 9 }).toString("base64url");
+}
+function decodeWireframe(data) {
+  if (!data.startsWith("z")) throw new Error(`unknown encoding "${data.slice(0, 1)}" (expected a "z" prefix)`);
+  return inflateRawSync(Buffer.from(data.slice(1), "base64url"), { maxOutputLength: MAX_SHARED_TEXT }).toString("utf8");
+}
+export {
+  DEVICES,
+  MAX_SHARED_TEXT,
+  WireframeError,
+  boardLayout,
+  boardSize,
+  catalog,
+  checkSpec,
+  compileWireframe,
+  componentDefinitions,
+  decodeWireframe,
+  encodeWireframe,
+  formatIssues,
+  printWireframeText as formatWireframe,
+  parseWireframeText,
+  registry,
+  renderWireframe,
+  renderWireframePng,
+  renderWireframeSvg,
+  repairPrompt,
+  theme,
+  wireframePrompt
+};

package/dist/layout.d.ts

@@ -0,0 +1,66 @@
+/** Sizes and colors shared by the components and the board-size calculation. */
+export declare const theme: {
+    readonly font: "Inter";
+    readonly board: "#e6e8eb";
+    readonly paper: "#ffffff";
+    readonly ink: "#1f2328";
+    readonly text: "#3d434a";
+    readonly muted: "#868d96";
+    readonly line: "#d0d4d9";
+    readonly lineStrong: "#9ca3ab";
+    readonly fill: "#f0f2f4";
+    readonly fill2: "#e1e4e8";
+    readonly primary: "#2b3035";
+    readonly onPrimary: "#ffffff";
+    readonly scrim: "rgba(31, 35, 40, 0.38)";
+    readonly notes: {
+        readonly yellow: "#fdf1a8";
+        readonly blue: "#cfe6fb";
+        readonly pink: "#fbd3e0";
+        readonly green: "#d4f1d0";
+    };
+};
+export declare const DEVICES: {
+    readonly phone: {
+        readonly width: 390;
+        readonly height: 844;
+        readonly radius: 36;
+        readonly padding: 16;
+    };
+    readonly tablet: {
+        readonly width: 820;
+        readonly height: 1180;
+        readonly radius: 24;
+        readonly padding: 24;
+    };
+    readonly desktop: {
+        readonly width: 1280;
+        readonly height: 800;
+        readonly radius: 10;
+        readonly padding: 24;
+    };
+    readonly custom: {
+        readonly width: 800;
+        readonly height: 600;
+        readonly radius: 8;
+        readonly padding: 20;
+    };
+};
+export type Device = keyof typeof DEVICES;
+/** Height of the screen name label plus the space under it. */
+export declare const LABEL_H = 40;
+/** Height of the board title block. */
+export declare const TITLE_H = 64;
+export declare const BOARD_PADDING = 56;
+export declare const BOARD_GAP = 64;
+export declare const NOTE_WIDTH = 220;
+export declare function screenSize(props?: Record<string, any>): {
+    device: "custom" | "desktop" | "phone" | "tablet";
+    width: any;
+    height: any;
+    radius: 8 | 10 | 24 | 36;
+    padding: any;
+    chrome: any;
+};
+/** Rough height of a Note so the board is tall enough to hold it. */
+export declare function estimateNoteHeight(text: string, width: number): number;

package/dist/playground/index.d.ts

@@ -0,0 +1,38 @@
+/// <reference types="node" preserve="true" />
+/**
+ * The playground: an editor with live rendering, the component reference and
+ * the model prompt. Ships in the package so it runs locally (`tsquare
+ * playground`) and on the website from the same code.
+ *
+ * The page (index.html) talks to a small set of endpoints, all answered by
+ * `createPlaygroundHandler`:
+ *
+ *   GET  /                   the page
+ *   GET  /playground.js      the page's script (CodeMirror editor and UI), bundled by the build
+ *   GET  /mark.png           the logo mark (tab icon, header)
+ *   GET  /api/language       what the editor needs to highlight and autocomplete
+ *   GET  /api/reference      components, props and rendered examples
+ *   GET  /api/examples       the example wireframes
+ *   GET  /api/prompt         the model prompt
+ *   POST /api/render         wireframe text → { issues, svg?, width?, height?, items? } (items: where each screen sits)
+ *   POST /api/png?scale=2    wireframe text → image/png
+ */
+import { type IncomingMessage, type ServerResponse } from "node:http";
+/** Problems with the reference examples: a component without an example or group, or an example that doesn't compile. */
+export declare function checkReferenceExamples(): string[];
+/** esbuild options for the browser bundle; shared with scripts/build.ts. */
+export declare const PLAYGROUND_BUNDLE: {
+    bundle: boolean;
+    format: "esm";
+    platform: "browser";
+    target: string;
+    minify: boolean;
+    legalComments: "eof";
+};
+/**
+ * Handles a playground request. Resolves to false when the path isn't a
+ * playground route, so a host server can serve its own routes around it.
+ */
+export declare function createPlaygroundHandler(): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+/** Runs the playground on localhost. */
+export declare function startPlayground(port?: number): import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;