tsquare 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.5.1
+
+Docs only: tooltips are easier to find.
+- **Language guide:** the "Tooltips and open states" section starts with a rendered picture of a tooltip, an open select, an open date picker and a row menu. It's generated by `npm run docs`, so it always matches the renderer. The section also now says notes can't take tooltips.
+- **Button page and the playground's Components tab:** a rendered tooltip example.
+- **Components index:** a note that any element inside a screen can take `tooltip="…"`.
+
+## 0.5.0
+
+### Open states and tooltips
+
+```tsquare
+select "Country" value="Mexico" open options=[Canada, Mexico, United States]
+input "Check-in" type=date value="Oct 14, 2026" open
+button ghost leadingIcon=more-horizontal open menu=[{label=Rename icon=pencil}, Duplicate, Delete]
+button secondary "Draft" tooltip="Saves without publishing"
+```
+
+- **Open states:** a select's options list, a date input's calendar and a button's menu now draw over the screen, covering what's below, as they would in the app.
+  - Each opens below its element, or above when there isn't room, and stays inside its screen.
+  - The date picker opens on the value's month with that day selected.
+- **Menus on list rows and the navbar too:** `listitem "Budget.xlsx" open menu=[Rename, Move, Delete]` opens right-aligned under the row; a row with nothing at its end shows … for it. The navbar's menu opens under a ⋮, added after its actions unless the last one already is a ⋯/⋮ icon.
+- **Tooltips:** `tooltip="…"` works on any element except a board or screen. It sits above the element (below it near the top of the screen), with its arrow pointing at the element.
+- **Errors** when an open state has nothing to show: `open` without `options` or `menu`, or `open` on an input that isn't `type=date`.
+- **How it works:** a board with any of these renders twice. The first pass measures where elements landed, and the second draws the overlays on top. Boards without them render once, exactly as before.
+
 ## 0.4.2
 
 - **Toast corners:** `position` also takes `topLeft`, `topRight`, `bottomLeft` and `bottomRight`, besides `top` and `bottom` (centered, the default). Desktop apps often show toasts in a corner.

package/dist/anchors.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Anchored overlays: things drawn over the board at an element's position (an open
+ * select's options, an open date picker, a button's menu, tooltips).
+ *
+ * Satori lays out and draws in one go without reporting positions, so a board that
+ * has any of these renders twice:
+ *   1. Measuring pass: each anchored element (and its screen) gets a marker, a box in a
+ *      unique color filling it. Satori's SVG uses absolute coordinates, so reading the
+ *      markers' rects back gives every box on the board.
+ *   2. Final pass: the board as usual, plus a top layer on the Board with each overlay
+ *      placed from those boxes, clipped to its screen, so it covers the content below.
+ * Boards without anchored elements render once, exactly as before.
+ *
+ * Precision: a marker fills its box inside the box's border, so bordered elements measure up to
+ * 1.5px in from their outer edge. That's invisible in the output, so overlays don't correct for it.
+ */
+import { type ReactNode } from "react";
+import type { Spec } from "@json-render/core";
+import type { Palette } from "./colors.js";
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export type AnchorKind = "tooltip" | "options" | "calendar" | "menu";
+/** `end`: the menu opens from the element's right end (a list row's …, a navbar's ⋮). */
+export interface Anchor {
+    id: string;
+    kind: AnchorKind;
+    screen: string;
+    field: boolean;
+    end?: boolean;
+}
+/** Every anchored overlay on the board, in drawing order (document order; tooltips last). */
+export declare function findAnchors(spec: Spec): Anchor[];
+/**
+ * A copy of the spec whose anchored elements and screens carry marker colors in hidden props:
+ * `__mark` on the outer box (menus, tooltips, screens), `__markField` on a field (options, calendar).
+ * Box keys are the element id, or `<id>#field`.
+ */
+export declare function tagForMeasuring(spec: Spec, anchors: Anchor[]): {
+    tagged: Spec;
+    colors: Map<string, string>;
+};
+/** The boxes of the markers in a measuring-pass SVG, by the ids they were tagged with. */
+export declare function readMarkers(svg: string, colors: Map<string, string>): Record<string, Rect>;
+/**
+ * Where an overlay of `size` goes next to `anchor`, inside `screen`: below (or above, for
+ * tooltips) when it fits, otherwise the side with more room; horizontally aligned as asked,
+ * then kept inside the screen. Coordinates are relative to the screen.
+ */
+export declare function place(anchor: Rect, size: {
+    w: number;
+    h: number;
+}, screen: Rect, opts: {
+    prefer: "below" | "above";
+    align: "start" | "center" | "end";
+    gap: number;
+}): {
+    x: number;
+    y: number;
+    bottom: number;
+    side: "above" | "below";
+};
+/** "Oct 14, 2026", "October 14 2026", "14 Oct 2026", "2026-10-14" → the month for the calendar and the day. */
+export declare function parseDate(value: unknown): {
+    month: string;
+    day?: number;
+} | null;
+/**
+ * The top layer: each overlay inside a box covering its screen (clipped to it), placed from the
+ * measured boxes. `Calendar` is the board's own calendar component, reused for date pickers.
+ */
+export declare function overlayLayer(spec: Spec, anchors: Anchor[], boxes: Record<string, Rect>, c: Palette, Calendar: (props: any) => ReactNode): ReactNode;

package/dist/catalog.d.ts

@@ -1,4 +1,15 @@
 import { z } from "zod";
+/**
+ * Props every element except Board and Screen accepts, on top of its own. Kept out of each
+ * component's schema so the prompt describes them once.
+ */
+export declare const UNIVERSAL_PROPS: {
+    readonly tooltip: z.ZodString;
+};
+/** Not the canvas (Board, Screen) or its annotations (Note): a tooltip there would be meaningless. */
+export declare const takesUniversalProps: (type: string) => boolean;
+/** Why a universal prop isn't allowed here, and what to do instead. */
+export declare function universalPropMessage(type: string, key: string): string;
 export declare const componentDefinitions: {
     Board: {
         props: z.ZodObject<{
@@ -319,6 +330,11 @@ export declare const componentDefinitions: {
             leadingIcon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             trailingIcon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             fullWidth: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+            menu: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                label: z.ZodString;
+                icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strict>]>>>>;
+            open: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strip>;
         slots: never[];
         description: string;
@@ -342,6 +358,7 @@ export declare const componentDefinitions: {
                 text: "text";
             }>>>;
             digits: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            open: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
             multiline: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
             helper: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             error: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
@@ -396,6 +413,8 @@ export declare const componentDefinitions: {
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             value: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             placeholder: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            options: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            open: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
             grow: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
             width: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
         }, z.core.$strip>;
@@ -466,6 +485,11 @@ export declare const componentDefinitions: {
                 center: "center";
                 left: "left";
             }>>>;
+            menu: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                label: z.ZodString;
+                icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strict>]>>>>;
+            open: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strip>;
         slots: never[];
         description: string;
@@ -550,6 +574,11 @@ export declare const componentDefinitions: {
             }>>>;
             trailingText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             trailingIcon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            menu: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                label: z.ZodString;
+                icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strict>]>>>>;
+            open: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strip>;
         slots: never[];
         description: string;
@@ -976,6 +1005,11 @@ export declare const catalog: import("@json-render/core").Catalog<{
                 leadingIcon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 trailingIcon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 fullWidth: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+                menu: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    label: z.ZodString;
+                    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                }, z.core.$strict>]>>>>;
+                open: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
             }, z.core.$strip>;
             slots: never[];
             description: string;
@@ -999,6 +1033,7 @@ export declare const catalog: import("@json-render/core").Catalog<{
                     text: "text";
                 }>>>;
                 digits: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                open: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
                 multiline: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
                 helper: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 error: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
@@ -1053,6 +1088,8 @@ export declare const catalog: import("@json-render/core").Catalog<{
                 label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 value: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                options: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+                open: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
                 grow: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
                 width: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
             }, z.core.$strip>;
@@ -1123,6 +1160,11 @@ export declare const catalog: import("@json-render/core").Catalog<{
                     center: "center";
                     left: "left";
                 }>>>;
+                menu: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    label: z.ZodString;
+                    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                }, z.core.$strict>]>>>>;
+                open: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
             }, z.core.$strip>;
             slots: never[];
             description: string;
@@ -1207,6 +1249,11 @@ export declare const catalog: import("@json-render/core").Catalog<{
                 }>>>;
                 trailingText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 trailingIcon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                menu: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    label: z.ZodString;
+                    icon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                }, z.core.$strict>]>>>>;
+                open: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
             }, z.core.$strip>;
             slots: never[];
             description: string;

package/dist/chunks/{chunk-NREXWHAE.js → chunk-B6KIVOSH.js}

@@ -209,6 +209,7 @@ var wireframeSchema = defineSchema(
       "Screens lay out their children top to bottom. Use Stack (direction row/column) and Grid inside a Screen to arrange content.",
       "Modal, Drawer and Toast are overlays. They MUST be direct children of a Screen, and SHOULD be listed last in the Screen's children so they draw on top.",
       "NavBar goes first in a Screen's children and TabBar goes last (before any overlay).",
+      "Any element except Board, Screen and Note can take a tooltip prop (text) to show a tooltip next to it. Select (with options), Input with type date, and Button, ListItem or NavBar (with menu) take open to show their list, calendar or menu over the screen.",
       "This is a low-fidelity wireframe: prefer placeholders (Image boxes, Text with lines) over invented copy, unless the copy matters to the design.",
       'Every element MUST include a "children" array. Leaf elements use an empty array: "children": [].',
       "Every id listed in a children array MUST exist as its own element."
@@ -223,6 +224,15 @@ var justify = z.enum(["start", "center", "end", "between", "around"]);
 var iconName = z.string().refine(isIcon, { error: (iss) => unknownIconMessage(String(iss.input)) }).describe("Lucide icon name in kebab-case, e.g. menu, search, arrow-left, settings, bell, user");
 var day = z.number().int().min(1).max(31);
 var percent = z.number().min(0).max(100);
+var menuItem = z.union([z.string(), z.strictObject({ label: z.string(), icon: o(iconName) })]);
+var UNIVERSAL_PROPS = {
+  tooltip: z.string().describe("Show a tooltip with this text next to the element")
+};
+var takesUniversalProps = (type) => type !== "Board" && type !== "Screen" && type !== "Note";
+function universalPropMessage(type, key) {
+  const base = `${key}s go on elements inside a screen`;
+  return type === "Note" ? `${base}; a note is already an annotation, so put the text in the note` : `${base}, not on the ${type.toLowerCase()} itself`;
+}
 var bulletItem = z.union([
   z.string(),
   // strict: a misspelled key is an error, not silently dropped
@@ -426,10 +436,12 @@ var componentDefinitions = {
       size: o(z.enum(["sm", "md", "lg"])),
       leadingIcon: o(iconName).describe("Lucide icon before the label, e.g. chevron-left for Back"),
       trailingIcon: o(iconName).describe("Lucide icon after the label, e.g. chevron-right for Next"),
-      fullWidth: o(z.boolean())
+      fullWidth: o(z.boolean()),
+      menu: o(z.array(menuItem)).describe("Dropdown menu items, shown below the button when open"),
+      open: o(z.boolean()).describe("Show the menu")
     }),
     slots: [],
-    description: "Button. Primary is filled, secondary is outlined, ghost is text only.",
+    description: "Button. Primary is filled, secondary is outlined, ghost is text only. With menu and open, a dropdown menu.",
     example: { label: "Continue", variant: "primary", fullWidth: true }
   },
   Input: {
@@ -439,6 +451,7 @@ var componentDefinitions = {
       value: o(z.string()),
       type: o(z.enum(["text", "password", "search", "email", "date", "code"])).describe("date shows a calendar icon; code draws one box per digit"),
       digits: o(z.number().int().min(2).max(10)).describe("Boxes for type=code, default 6"),
+      open: o(z.boolean()).describe("type=date: show the calendar below the field"),
       multiline: o(z.number().int().min(1)).describe("Number of rows; 2 or more makes a textarea"),
       helper: o(z.string()),
       error: o(z.boolean()).describe("Validation error: red border and red helper text"),
@@ -472,11 +485,13 @@ var componentDefinitions = {
       label: o(z.string()),
       value: o(z.string()),
       placeholder: o(z.string()),
+      options: o(z.array(z.string())).describe("The choices, shown below the field when open"),
+      open: o(z.boolean()).describe("Show the options list"),
       grow: o(z.boolean()).describe("Fill the remaining space in a row"),
       width: o(z.union([z.number(), z.string()])).describe("Fixed width, e.g. 320. Default fills the space.")
     }),
     slots: [],
-    description: "Dropdown field (closed state).",
+    description: "Dropdown field. With options and open, the list shows below it.",
     example: { label: "Country", value: "United States" }
   },
   Slider: {
@@ -518,7 +533,9 @@ var componentDefinitions = {
       title: o(z.string()),
       leading: o(z.enum(["none", "menu", "back", "close", "logo"])),
       actions: o(z.array(iconName)).describe("Icon names shown on the right"),
-      align: o(z.enum(["left", "center"]))
+      align: o(z.enum(["left", "center"])),
+      menu: o(z.array(menuItem)).describe("A menu under the last action (adds \u22EE if needed), shown when open"),
+      open: o(z.boolean()).describe("Show the menu")
     }),
     slots: [],
     description: "Top app bar. Place first in a Screen.",
@@ -565,7 +582,9 @@ var componentDefinitions = {
       leadingIcon: o(iconName).describe("Lucide icon on the left; setting it implies leading=icon"),
       trailing: o(z.enum(["none", "chevron", "toggle", "text", "badge", "icon"])),
       trailingText: o(z.string()).describe("Text for trailing=text or badge; setting it implies trailing=text"),
-      trailingIcon: o(iconName).describe("Lucide icon on the right; setting it implies trailing=icon")
+      trailingIcon: o(iconName).describe("Lucide icon on the right; setting it implies trailing=icon"),
+      menu: o(z.array(menuItem)).describe("A menu for the row (shows \u2026 on the right if nothing else is there), shown when open"),
+      open: o(z.boolean()).describe("Show the menu")
     }),
     slots: [],
     description: "Row in a List. Omit title for a placeholder bar.",
@@ -648,6 +667,38 @@ function Box({ style, children }) {
   for (const [k, v] of Object.entries(style ?? {})) if (v !== void 0 && v !== null) clean[k] = v;
   return /* @__PURE__ */ jsx("div", { style: clean, children });
 }
+function Marker({ color }) {
+  return /* @__PURE__ */ jsx("div", { style: { position: "absolute", top: 0, left: 0, width: "100%", height: "100%", backgroundColor: color } });
+}
+function markRoot(root, color) {
+  let node = root;
+  while (isValidElement(node) && typeof node.type === "function" && node.type !== Box) node = node.type(node.props);
+  if (!isValidElement(node)) return root;
+  const kids = Children.toArray(node.props.children);
+  return cloneElement(node, {}, ...kids, /* @__PURE__ */ jsx(Marker, { color }, "__marker"));
+}
+function withMarkers(reg) {
+  return Object.fromEntries(
+    Object.entries(reg).map(([name, C]) => [
+      name,
+      (props) => {
+        const root = C(props);
+        const color = props.element?.props?.__mark;
+        return color && name !== "Screen" ? markRoot(root, color) : root;
+      }
+    ])
+  );
+}
+function withTopLayer(reg, layer) {
+  return {
+    ...reg,
+    Board: (props) => {
+      const root = reg.Board(props);
+      if (!isValidElement(root)) return root;
+      return cloneElement(root, {}, ...Children.toArray(root.props.children), layer);
+    }
+  };
+}
 function withDir(children, dir, stretch = false, aligned = false) {
   return Children.toArray(children).map((c) => isValidElement(c) ? cloneElement(c, { dir, stretch, aligned }) : c);
 }
@@ -803,7 +854,8 @@ function Screen({ element, children }) {
               }
             ),
             bottom,
-            overlays.map((o2) => isValidElement(o2) ? cloneElement(o2, { aboveTabBar: bottom.length > 0 }) : o2)
+            overlays.map((o2) => isValidElement(o2) ? cloneElement(o2, { aboveTabBar: bottom.length > 0 }) : o2),
+            p.__mark ? /* @__PURE__ */ jsx(Marker, { color: p.__mark }) : null
           ] })
         ]
       }
@@ -1188,8 +1240,8 @@ function fieldWidth(width, dir) {
 function FieldLabel({ text }) {
   return text ? /* @__PURE__ */ jsx(Box, { style: { fontSize: 13, fontWeight: 600, color: theme.text }, children: text }) : null;
 }
-function Field({ children, height = 42, top = false, error = false }) {
-  return /* @__PURE__ */ jsx(
+function Field({ children, height = 42, top = false, error = false, mark }) {
+  return /* @__PURE__ */ jsxs(
     Box,
     {
       style: {
@@ -1202,7 +1254,10 @@ function Field({ children, height = 42, top = false, error = false }) {
         backgroundColor: theme.paper,
         fontSize: 15
       },
-      children
+      children: [
+        children,
+        mark ? /* @__PURE__ */ jsx(Marker, { color: mark }) : null
+      ]
     }
   );
 }
@@ -1241,7 +1296,7 @@ function Input({ element, dir, colors }) {
   const content = isPassword && shown ? "\u2022".repeat(Math.min(shown.length, 12)) : shown;
   return /* @__PURE__ */ jsxs(Box, { style: { flexDirection: "column", gap: 6, ...fieldWidth(p.width, dir), ...p.grow ? { flexGrow: 1 } : {} }, children: [
     /* @__PURE__ */ jsx(FieldLabel, { text: p.label }),
-    /* @__PURE__ */ jsxs(Field, { height: rows > 1 ? rows * 22 + 20 : 42, top: rows > 1, error: !!p.error, children: [
+    /* @__PURE__ */ jsxs(Field, { height: rows > 1 ? rows * 22 + 20 : 42, top: rows > 1, error: !!p.error, mark: p.__markField, children: [
       p.type === "search" ? /* @__PURE__ */ jsx(IconGlyph, { name: "search", size: 18, color: theme.muted }) : null,
       /* @__PURE__ */ jsx(Box, { style: { flexGrow: 1, color: content ? theme.ink : theme.muted }, children: content ?? p.placeholder ?? (isPassword ? "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022" : "") }),
       isPassword ? /* @__PURE__ */ jsx(IconGlyph, { name: "eye-off", size: 18, color: theme.muted }) : null,
@@ -1254,7 +1309,7 @@ function Select({ element, dir }) {
   const p = element.props;
   return /* @__PURE__ */ jsxs(Box, { style: { flexDirection: "column", gap: 6, ...fieldWidth(p.width, dir), ...p.grow ? { flexGrow: 1 } : {} }, children: [
     /* @__PURE__ */ jsx(FieldLabel, { text: p.label }),
-    /* @__PURE__ */ jsxs(Field, { children: [
+    /* @__PURE__ */ jsxs(Field, { mark: p.__markField, children: [
       /* @__PURE__ */ jsx(Box, { style: { flexGrow: 1, color: p.value ? theme.ink : theme.muted }, children: p.value ?? p.placeholder ?? "Select\u2026" }),
       /* @__PURE__ */ jsx(IconGlyph, { name: "chevron-down", size: 18, color: theme.text })
     ] })
@@ -1447,7 +1502,9 @@ var LEADING_ICON = { menu: "menu", back: "arrow-left", close: "x" };
 function NavBar({ element }) {
   const p = element.props;
   const leading = p.leading === "logo" ? /* @__PURE__ */ jsx(Box, { style: { width: 30, height: 30, borderRadius: 8, backgroundColor: theme.fill2 } }) : p.leading && p.leading !== "none" ? /* @__PURE__ */ jsx(IconGlyph, { name: LEADING_ICON[p.leading], size: 22 }) : null;
-  const actions = /* @__PURE__ */ jsx(Box, { style: { gap: 18, alignItems: "center", justifyContent: "flex-end" }, children: (p.actions ?? []).map((a, i) => /* @__PURE__ */ jsx(IconGlyph, { name: a, size: 22 }, i)) });
+  const icons2 = [...p.actions ?? []];
+  if (p.menu?.length && !/^(more-|ellipsis)/.test(icons2[icons2.length - 1] ?? "")) icons2.push("more-vertical");
+  const actions = /* @__PURE__ */ jsx(Box, { style: { gap: 18, alignItems: "center", justifyContent: "flex-end" }, children: icons2.map((a, i) => /* @__PURE__ */ jsx(IconGlyph, { name: a, size: 22 }, i)) });
   const title = p.title ? /* @__PURE__ */ jsx(Box, { style: { fontSize: 17, fontWeight: 600 }, children: p.title }) : null;
   const centered = p.align === "center";
   return /* @__PURE__ */ jsx(
@@ -1584,7 +1641,7 @@ function ListItem({ element, colors }) {
       case "icon":
         return /* @__PURE__ */ jsx(IconGlyph, { name: p.trailingIcon ?? "more-horizontal", size: 20, color: theme.muted });
       default:
-        return null;
+        return p.menu?.length ? /* @__PURE__ */ jsx(IconGlyph, { name: "more-horizontal", size: 20, color: theme.muted }) : null;
     }
   })();
   return /* @__PURE__ */ jsxs(Box, { style: { minHeight: 60, padding: "10px 0", gap: 14, alignItems: "center" }, children: [
@@ -2032,6 +2089,14 @@ function parseWireframeText(source) {
           c.next();
           c.next();
           const key = t.value;
+          if (key in UNIVERSAL_PROPS) {
+            if (takesUniversalProps(info.name)) props[key] = textWhereExpected(UNIVERSAL_PROPS[key], parseValue(c));
+            else {
+              parseValue(c);
+              issues.push({ line: lineNo, message: `${info.name}: ${universalPropMessage(info.name, key)}` });
+            }
+            continue;
+          }
           if (!(key in info.props)) {
             const elsewhere = belongsElsewhere(info.name, key, true);
             issues.push({ line: lineNo, message: `${info.name} has no prop "${key}"` + (elsewhere ? `: ${elsewhere}` : "") + ` (its props: ${Object.keys(info.props).join(", ")})` });
@@ -2209,6 +2274,155 @@ function scanLine(line, from) {
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { renderToSvg } from "@json-render/image/render";
+
+// src/anchors.tsx
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+var propsOf = (els, id) => els[id].props ?? {};
+function findAnchors(spec) {
+  const out = [];
+  const visit = (id, screen) => {
+    const el = spec.elements[id];
+    if (!el) return;
+    const p = propsOf(spec.elements, id);
+    if (el.type === "Screen") screen = id;
+    if (screen) {
+      if (el.type === "Select" && p.open) out.push({ id, kind: "options", screen, field: true });
+      if (el.type === "Input" && p.open && p.type === "date") out.push({ id, kind: "calendar", screen, field: true });
+      if (el.type === "Button" && p.open && Array.isArray(p.menu) && p.menu.length) out.push({ id, kind: "menu", screen, field: false });
+      if ((el.type === "ListItem" || el.type === "NavBar") && p.open && Array.isArray(p.menu) && p.menu.length) out.push({ id, kind: "menu", screen, field: false, end: true });
+    }
+    for (const child of el.children ?? []) visit(child, screen);
+  };
+  visit(spec.root, "");
+  const tips = [];
+  const visitTips = (id, screen) => {
+    const el = spec.elements[id];
+    if (!el) return;
+    if (el.type === "Screen") screen = id;
+    if (screen && el.type !== "Screen" && typeof propsOf(spec.elements, id).tooltip === "string") tips.push({ id, kind: "tooltip", screen, field: false });
+    for (const child of el.children ?? []) visitTips(child, screen);
+  };
+  visitTips(spec.root, "");
+  return [...out, ...tips];
+}
+var MARK = (i) => `#fe${(i >> 8).toString(16).padStart(2, "0")}${(i & 255).toString(16).padStart(2, "0")}`;
+function tagForMeasuring(spec, anchors) {
+  const tagged = structuredClone(spec);
+  const colors = /* @__PURE__ */ new Map();
+  let n = 1;
+  const tag = (id, field) => {
+    const key = field ? `${id}#field` : id;
+    if (colors.has(key)) return;
+    const color = MARK(n++);
+    colors.set(key, color);
+    const el = tagged.elements[id];
+    el.props = { ...el.props ?? {}, [field ? "__markField" : "__mark"]: color };
+  };
+  for (const a of anchors) {
+    tag(a.screen, false);
+    tag(a.id, a.field);
+  }
+  return { tagged, colors };
+}
+function readMarkers(svg, colors) {
+  const rects = [...svg.matchAll(/<rect ([^>]*?)\/?>/g)].map(
+    (m) => Object.fromEntries([...m[1].matchAll(/([\w-]+)="([^"]*)"/g)].map((a) => [a[1], a[2]]))
+  );
+  const boxes = {};
+  for (const [id, color] of colors) {
+    const r = rects.find((a) => a.fill === color);
+    if (r) boxes[id] = { x: +r.x, y: +r.y, w: +r.width, h: +r.height };
+  }
+  return boxes;
+}
+function place(anchor, size, screen, opts) {
+  const room = { above: anchor.y - screen.y - opts.gap, below: screen.y + screen.h - (anchor.y + anchor.h) - opts.gap };
+  const other = opts.prefer === "below" ? "above" : "below";
+  const side = room[opts.prefer] >= size.h || room[opts.prefer] >= room[other] ? opts.prefer : other;
+  const y = side === "below" ? anchor.y + anchor.h + opts.gap : anchor.y - opts.gap - size.h;
+  const x0 = opts.align === "start" ? anchor.x : opts.align === "end" ? anchor.x + anchor.w - size.w : anchor.x + anchor.w / 2 - size.w / 2;
+  const x = Math.max(screen.x + 8, Math.min(x0, screen.x + screen.w - 8 - size.w));
+  return { x: x - screen.x, y: y - screen.y, bottom: screen.y + screen.h - (anchor.y - opts.gap), side };
+}
+var ROW = 36;
+function ListCard({ items, width, selected, c }) {
+  return /* @__PURE__ */ jsx2("div", { style: { display: "flex", flexDirection: "column", width, padding: 4, backgroundColor: theme.paper, border: `1.5px solid ${theme.lineStrong}`, borderRadius: 8, boxShadow: "0 8px 24px rgba(0,0,0,0.18)" }, children: items.map((item, i) => {
+    const on = selected != null && item.label === selected;
+    return /* @__PURE__ */ jsxs2("div", { style: { display: "flex", alignItems: "center", gap: 10, height: ROW - 4, padding: "0 10px", borderRadius: 6, fontSize: 15, color: theme.ink, backgroundColor: on ? theme.fill : "transparent", fontWeight: on ? 600 : 400 }, children: [
+      item.icon ? /* @__PURE__ */ jsx2(IconGlyph, { name: item.icon, size: 16, color: theme.text }) : null,
+      /* @__PURE__ */ jsx2("div", { style: { display: "flex", flexGrow: 1 }, children: item.label }),
+      on ? /* @__PURE__ */ jsx2(IconGlyph, { name: "check", size: 16, color: c.accentText }) : null
+    ] }, i);
+  }) });
+}
+function parseDate(value) {
+  const s = String(value ?? "").trim();
+  const MONTHS2 = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+  const iso = s.match(/^(\d{4})-(\d{1,2})(?:-(\d{1,2}))?/);
+  if (iso) return { month: `${MONTHS2[+iso[2] - 1]} ${iso[1]}`, day: iso[3] ? +iso[3] : void 0 };
+  const name = s.match(/([A-Za-z]{3,})/)?.[1];
+  const index = name ? MONTHS2.findIndex((m) => m.toLowerCase().startsWith(name.toLowerCase().slice(0, 3))) : -1;
+  const year = s.match(/\b(\d{4})\b/)?.[1];
+  if (index < 0 || !year) return null;
+  const day2 = s.replace(year, "").match(/\b(\d{1,2})\b/)?.[1];
+  return { month: `${MONTHS2[index]} ${year}`, day: day2 ? +day2 : void 0 };
+}
+function Tooltip({ text, side, width, arrowX }) {
+  const arrow = /* @__PURE__ */ jsx2("svg", { width: "12", height: "6", viewBox: "0 0 12 6", style: { flexShrink: 0, marginLeft: Math.max(6, Math.min(arrowX, width - 6)) - 6 }, children: /* @__PURE__ */ jsx2("path", { d: side === "above" ? "M0 0 L6 6 L12 0 Z" : "M0 6 L6 0 L12 6 Z", fill: theme.ink }) });
+  return /* @__PURE__ */ jsxs2("div", { style: { display: "flex", flexDirection: "column", alignItems: "flex-start", width }, children: [
+    side === "below" ? arrow : null,
+    /* @__PURE__ */ jsx2("div", { style: { display: "flex", justifyContent: "center", width, padding: "6px 10px", borderRadius: 6, backgroundColor: theme.ink, color: theme.onPrimary, fontSize: 13, lineHeight: 1.35, textAlign: "center" }, children: text }),
+    side === "above" ? arrow : null
+  ] });
+}
+function tooltipSize(text) {
+  const width = Math.min(240, Math.ceil(text.length * 7.4) + 24);
+  const lines = Math.max(1, Math.ceil(text.length * 7.4 / 216));
+  return { w: width, h: lines * 18 + 12 + 6 };
+}
+function overlayLayer(spec, anchors, boxes, c, Calendar2) {
+  const byScreen = /* @__PURE__ */ new Map();
+  for (const a of anchors) {
+    const screen = boxes[a.screen];
+    const anchor = boxes[a.field ? `${a.id}#field` : a.id];
+    if (!screen || !anchor) continue;
+    const p = propsOf(spec.elements, a.id);
+    let node = null;
+    let pos = null;
+    if (a.kind === "options") {
+      const options = p.options?.length ? p.options : [p.value ?? "Option 1", "Option 2", "Option 3"];
+      const size = { w: anchor.w, h: options.length * ROW + 8 };
+      pos = place(anchor, size, screen, { prefer: "below", align: "start", gap: 4 });
+      node = /* @__PURE__ */ jsx2(ListCard, { items: options.map((label) => ({ label })), width: size.w, selected: p.value, c });
+    } else if (a.kind === "menu") {
+      const items = p.menu.map((i) => typeof i === "string" ? { label: i } : i);
+      const width = a.end ? 200 : Math.max(180, anchor.w);
+      const inRightHalf = anchor.x + anchor.w / 2 > screen.x + screen.w / 2;
+      pos = place(anchor, { w: width, h: items.length * ROW + 8 }, screen, { prefer: "below", align: a.end || inRightHalf ? "end" : "start", gap: a.end ? -6 : 4 });
+      node = /* @__PURE__ */ jsx2(ListCard, { items, width, c });
+    } else if (a.kind === "calendar") {
+      const date = parseDate(p.value);
+      const { start, days } = monthGrid(date?.month);
+      const weeks = Math.ceil((start + days) / 7);
+      pos = place(anchor, { w: 296, h: 92 + weeks * 38 }, screen, { prefer: "below", align: "start", gap: 4 });
+      node = /* @__PURE__ */ jsx2("div", { style: { display: "flex", boxShadow: "0 8px 24px rgba(0,0,0,0.18)", borderRadius: 12 }, children: Calendar2({ element: { type: "Calendar", props: { month: date?.month ?? "Month", selected: date?.day } }, colors: c }) });
+    } else {
+      const size = tooltipSize(p.tooltip);
+      pos = place(anchor, size, screen, { prefer: "above", align: "center", gap: 4 });
+      node = /* @__PURE__ */ jsx2(Tooltip, { text: p.tooltip, side: pos.side, width: size.w, arrowX: anchor.x + anchor.w / 2 - (screen.x + pos.x) });
+    }
+    const list = byScreen.get(a.screen) ?? [];
+    const vertical = pos.side === "above" ? { bottom: pos.bottom } : { top: pos.y };
+    list.push(/* @__PURE__ */ jsx2("div", { style: { position: "absolute", left: pos.x, ...vertical, display: "flex" }, children: node }, `${a.id}-${a.kind}`));
+    byScreen.set(a.screen, list);
+  }
+  return /* @__PURE__ */ jsx2("div", { style: { position: "absolute", top: 0, left: 0, width: "100%", height: "100%", display: "flex" }, children: [...byScreen].map(([screenId, nodes]) => {
+    const s = boxes[screenId];
+    return /* @__PURE__ */ jsx2("div", { style: { position: "absolute", left: s.x, top: s.y, width: s.w, height: s.h, overflow: "hidden", display: "flex" }, children: nodes }, screenId);
+  }) }, "__overlays");
+}
+
+// src/render.ts
 var fontFile = (name) => createRequire(import.meta.url).resolve(`@fontsource/inter/files/${name}`);
 var fontCache = null;
 function loadFonts() {
@@ -2271,6 +2485,14 @@ function checkSpec(spec) {
         }
       }
       for (const key of Object.keys(el.props ?? {})) {
+        if (key in UNIVERSAL_PROPS) {
+          if (!takesUniversalProps(el.type)) issues.push(`${id}: ${universalPropMessage(el.type, key)}`);
+          else {
+            const r = UNIVERSAL_PROPS[key].safeParse(el.props[key]);
+            if (!r.success) issues.push(`${id}.props.${key}: ${r.error.issues[0].message}`);
+          }
+          continue;
+        }
         if (!(key in def.props.shape)) {
           const elsewhere = belongsElsewhere(el.type, key, true);
           issues.push(`${id}.props: ${el.type} has no prop "${key}"${elsewhere ? `: ${elsewhere}` : ""}`);
@@ -2323,6 +2545,9 @@ function checkSpec(spec) {
         say(`value has ${String(p.value).length} characters but the code has ${p.digits ?? 6} boxes (digits)`);
       }
       if (el.type === "Input" && p.digits != null && p.type !== "code") say("digits only applies to type=code");
+      if (el.type === "Input" && p.open && p.type !== "date") say("open shows a date picker, so it needs type=date");
+      if ((el.type === "Button" || el.type === "ListItem" || el.type === "NavBar") && p.open && !(Array.isArray(p.menu) && p.menu.length)) say("open shows the menu; add menu=[\u2026] with its items");
+      if (el.type === "Select" && p.open && !(Array.isArray(p.options) && p.options.length)) say("open shows the options list; add options=[\u2026] with the choices");
     }
     if (el.type === "Table") {
       const { columns, data } = el.props ?? {};
@@ -2388,13 +2613,21 @@ async function renderWireframeSvg(spec, opts = {}) {
     if (issues.length) throw new SpecError(issues);
   }
   const { width, height } = boardSize(spec);
-  return renderToSvg(spec, {
-    registry: withPalette(paletteFor(spec.elements[spec.root]?.props?.accent)),
-    includeStandard: false,
-    fonts: await loadFonts(),
-    width,
-    height
-  });
+  const palette = paletteFor(spec.elements[spec.root]?.props?.accent);
+  const registry2 = withPalette(palette);
+  const draw = async (s, reg) => renderToSvg(s, { registry: reg, includeStandard: false, fonts: await loadFonts(), width, height });
+  const { anchors, boxes } = await measureAnchors(spec);
+  if (!anchors.length) return draw(spec, registry2);
+  return draw(spec, withTopLayer(registry2, overlayLayer(spec, anchors, boxes, palette, registry2.Calendar)));
+}
+async function measureAnchors(spec) {
+  const anchors = findAnchors(spec);
+  if (!anchors.length) return { anchors, boxes: {} };
+  const { width, height } = boardSize(spec);
+  const registry2 = withPalette(paletteFor());
+  const { tagged, colors } = tagForMeasuring(spec, anchors);
+  const svg = await renderToSvg(tagged, { registry: withMarkers(registry2), includeStandard: false, fonts: await loadFonts(), width, height });
+  return { anchors, boxes: readMarkers(svg, colors) };
 }
 async function renderWireframePng(spec, opts = {}) {
   const svg = await renderWireframeSvg(spec, opts);
@@ -2613,7 +2846,8 @@ var RULES = `## Rules
 5. Modal, Drawer and Toast are overlays. They must be direct children of a Screen.
 6. This is a low-fidelity wireframe. Prefer placeholders (Image boxes, Text with lines) over invented copy unless the copy matters.
 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) and Input error. Only add an accent if the request asks for color or a brand.`;
+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) and Input error. Only add an accent if the request asks for color or a brand.
+9. Any element except Board, Screen and Note 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.`;
 var TEXT_FORMAT = `## Output format: wireframe text
 One element per line. Indent children two spaces under their parent. The first line is the board.
 
@@ -2662,6 +2896,8 @@ export {
   DEVICES,
   ACCENTS,
   iconNames,
+  UNIVERSAL_PROPS,
+  takesUniversalProps,
   componentDefinitions,
   catalog,
   registry,

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   printWireframeText,
   renderWireframe,
   wireframePrompt
-} from "./chunks/chunk-NREXWHAE.js";
+} from "./chunks/chunk-B6KIVOSH.js";
 
 // src/cli.ts
 import { readFile, writeFile } from "node:fs/promises";

package/dist/components.d.ts

@@ -1,4 +1,4 @@
-import React from "react";
+import React, { type ReactNode } from "react";
 import { type Palette } from "./colors.js";
 import type { ComponentRenderProps } from "@json-render/image";
 /**
@@ -16,6 +16,14 @@ type Props<P = Record<string, any>> = ComponentRenderProps<P> & {
 };
 /** A registry whose components all receive this board's palette as `colors`. */
 export declare function withPalette(colors: Palette): typeof registry;
+/**
+ * A registry for the measuring pass: an element whose props carry `__mark` (a color) gets a marker on
+ * its outer box. Fields and screens place their own (`__markField`, Screen's frame), since an overlay
+ * hangs from the field, not the label, and stays inside the device frame.
+ */
+export declare function withMarkers(reg: typeof registry): typeof registry;
+/** A registry whose Board also draws `layer` on top of everything (the anchored overlays). */
+export declare function withTopLayer(reg: typeof registry, layer: ReactNode): typeof registry;
 export declare function IconGlyph({ name, size, color, strokeWidth }: {
     name?: string | null;
     size?: number;

package/dist/index.js

@@ -20,7 +20,7 @@ import {
   upgradeSpec,
   upgradeWireframe,
   wireframePrompt
-} from "./chunks/chunk-NREXWHAE.js";
+} from "./chunks/chunk-B6KIVOSH.js";
 
 // src/share.ts
 import { deflateRawSync, inflateRawSync } from "node:zlib";

package/dist/playground/index.js

@@ -1,6 +1,7 @@
 import {
   ACCENTS,
   PRIMARY_PROP,
+  UNIVERSAL_PROPS,
   bareWords,
   boardLayout,
   compileWireframe,
@@ -10,8 +11,9 @@ import {
   iconNames,
   renderWireframePng,
   renderWireframeSvg,
+  takesUniversalProps,
   wireframePrompt
-} from "../chunks/chunk-NREXWHAE.js";
+} from "../chunks/chunk-B6KIVOSH.js";
 
 // src/playground/index.ts
 import { createServer } from "node:http";
@@ -54,6 +56,7 @@ function languageData() {
   const components = Object.entries(componentDefinitions).map(([type, def]) => {
     const shape = def.props.shape;
     const props = Object.entries(shape).map(([name, schema]) => describe(name, schema));
+    if (takesUniversalProps(type)) for (const [name, schema] of Object.entries(UNIVERSAL_PROPS)) props.push(describe(name, schema));
     if (type === "Icon") props.find((p) => p.name === "name").icon = true;
     const words = bareWords(type);
     const off = words.booleans.flatMap((b) => b === "on" ? ["off"] : b === "checked" ? ["unchecked"] : [`no-${b}`]);
@@ -258,7 +261,19 @@ var EXAMPLES = {
       button secondary "Back" leadingIcon=chevron-left
       button primary "Next" trailingIcon=chevron-right
     button primary "Full width" fullWidth
-    text "With a board accent, primary buttons fill with it and ghost buttons use it for text." sm muted`,
+    text "With a board accent, primary buttons fill with it and ghost buttons use it for text." sm muted
+  screen custom "tooltip" width=380 height=170
+    spacer size=34
+    stack row gap=8
+      button secondary "Draft" tooltip="Saves without publishing"
+      button primary "Publish"
+    text "Any element inside a screen can take tooltip=." sm muted
+  screen custom "menu and open" width=380 height=300
+    stack row justify=between align=center
+      heading "Notes" level=3
+      button ghost leadingIcon=more-horizontal open menu=[{label=Rename icon=pencil}, {label=Duplicate icon=copy}, Share, {label=Delete icon=trash-2}]
+    text lines=3
+    text "menu lists the items; open shows them over the screen." sm muted`,
   Input: `board
   screen custom width=420 height=760
     input "Email" placeholder="you@example.com" helper="We never share it"
@@ -270,7 +285,10 @@ var EXAMPLES = {
       input placeholder="grow fills the row" grow
       button primary "Send"
     input "Check-in" type=date value="Oct 14, 2026"
-    input "Verification code" type=code value="4821" helper="Sent to (555) 010-2400"`,
+    input "Verification code" type=code value="4821" helper="Sent to (555) 010-2400"
+  screen custom "type=date open" width=420 height=440
+    input "Check-in" type=date value="Oct 14, 2026" open
+    input "Check-out" type=date value="Oct 18, 2026"`,
   Checkbox: `board
   screen custom width=300 height=100
     checkbox "Checked" checked
@@ -295,7 +313,10 @@ var EXAMPLES = {
     select "Size" placeholder="Choose one" width=160
     stack row gap=12
       input "City" placeholder="Monterrey" grow
-      select "State" value="Nuevo Le\xF3n" grow`,
+      select "State" value="Nuevo Le\xF3n" grow
+  screen custom "options and open" width=380 height=260
+    select "Country" value="Mexico" open options=[Canada, Mexico, United States, Spain]
+    input "City" placeholder="Monterrey"`,
   Slider: `board
   screen custom width=380 height=200
     slider "Volume" value=30
@@ -319,7 +340,10 @@ var EXAMPLES = {
     navbar "leading=menu" leading=menu actions=[search, bell]
     navbar "leading=back, centered" leading=back align=center actions=[share]
     navbar "leading=close" leading=close
-    navbar "leading=logo" leading=logo actions=[user]`,
+    navbar "leading=logo" leading=logo actions=[user]
+  screen custom "menu and open" width=380 height=240 padding=0 gap=0
+    navbar "Inbox" leading=menu actions=[search] open menu=[Mark all as read, {label=Settings icon=settings}, {label=Sign out icon=log-out}]
+    text lines=4`,
   TabBar: `board
   screen phone "Tab bar sits at the bottom"
     heading "Home"
@@ -352,7 +376,13 @@ var EXAMPLES = {
       listitem "leading=image" subtitle="trailing=badge" leading=image trailing=badge trailingText="3"
       listitem "leading=checkbox" leading=checkbox trailing=toggle
       listitem "trailingIcon=trash-2" trailingIcon=trash-2
-      listitem leading=image trailing=chevron`,
+      listitem leading=image trailing=chevron
+  screen custom "menu and open" width=400 height=330
+    list
+      listitem "Report.pdf" subtitle="2.4 MB" leadingIcon=file-text
+      listitem "Budget.xlsx" subtitle="380 KB" leadingIcon=sheet open menu=[{label=Rename icon=pencil}, {label=Move icon=folder}, {label=Delete icon=trash-2}]
+      listitem "Notes.txt" subtitle="12 KB" leadingIcon=file
+      listitem "Photo.jpg" subtitle="1.1 MB" leadingIcon=image`,
   Table: `board
   screen custom width=520 height=400
     table columns=[Name, Role, Status] data=[["Ana Ruiz", Admin, Active], ["Ben Cho", Editor, Invited]]

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.\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) and Input error. Only add an accent if the request asks for color or a brand.";
+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, 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) and Input error. Only add an accent if the request asks for color or a brand.\n9. Any element except Board, Screen and Note 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.";
 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/dist/render.d.ts

@@ -35,6 +35,19 @@ export interface RenderWireframeOptions {
     skipValidation?: boolean;
 }
 export declare function renderWireframeSvg(spec: Spec, opts?: RenderWireframeOptions): Promise<string>;
+/**
+ * The measuring pass: the board's anchored elements (and their screens) and their boxes on the
+ * canvas, keyed by element id (`<id>#field` for a field). No render at all when there are none.
+ */
+export declare function measureAnchors(spec: Spec): Promise<{
+    anchors: import("./anchors.js").Anchor[];
+    boxes: Record<string, {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }>;
+}>;
 export declare function renderWireframePng(spec: Spec, opts?: RenderWireframeOptions & {
     scale?: number;
 }): Promise<Buffer<ArrayBufferLike>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsquare",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Wireframes in plain text: easy for LLMs to write, fast to render as SVG or PNG.",
   "keywords": [
     "wireframe",
@@ -69,7 +69,7 @@
   "dependencies": {
     "@fontsource/inter": "5.3.0",
     "@json-render/core": "^0.21.0",
-    "@json-render/image": "^0.21.0",
+    "@json-render/image": "0.21.0",
     "@resvg/resvg-js": "^2.6.2",
     "@types/node": ">=20",
     "@types/react": "^19.3.0",

package/skill/tsquare/SKILL.md

@@ -51,6 +51,7 @@ If a bare word could mean more than one prop, write it as key=value.
 6. This is a low-fidelity wireframe. Prefer placeholders (Image boxes, Text with lines) over invented copy unless the copy matters.
 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) and Input error. Only add an accent if the request asks for color or a brand.
+9. Any element except Board, Screen and Note 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.
 
 ## Example
 

package/skill/tsquare/reference.md

@@ -121,13 +121,15 @@ Small pill label for counts or statuses.
 - tone: "neutral" | "success" | "warning" | "danger" — Status color. Default neutral (the accent for solid badges)
 
 ### Button
-Button. Primary is filled, secondary is outlined, ghost is text only.
+Button. Primary is filled, secondary is outlined, ghost is text only. With menu and open, a dropdown menu.
 - label: string (main text)
 - variant: "primary" | "secondary" | "ghost"
 - size: "sm" | "md" | "lg"
 - 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
+- menu: array of string | { label: string, icon: string } — Dropdown menu items, shown below the button when open
+- open: boolean — Show the menu
 
 ### Input
 Text field with optional label. Set multiline for a textarea.
@@ -136,6 +138,7 @@ Text field with optional label. Set multiline for a textarea.
 - value: string
 - type: "text" | "password" | "search" | "email" | "date" | "code" — date shows a calendar icon; code draws one box per digit
 - digits: number — Boxes for type=code, default 6
+- open: boolean — type=date: show the calendar below the field
 - multiline: number — Number of rows; 2 or more makes a textarea
 - helper: string
 - error: boolean — Validation error: red border and red helper text
@@ -158,10 +161,12 @@ On/off switch with label on the left.
 - on: boolean
 
 ### Select
-Dropdown field (closed state).
+Dropdown field. With options and open, the list shows below it.
 - label: string (main text)
 - value: string
 - placeholder: string
+- options: array of string — The choices, shown below the field when open
+- open: boolean — Show the options list
 - grow: boolean — Fill the remaining space in a row
 - width: number | string — Fixed width, e.g. 320. Default fills the space.
 
@@ -192,6 +197,8 @@ Top app bar. Place first in a Screen.
 - leading: "none" | "menu" | "back" | "close" | "logo"
 - actions: array of string — Icon names shown on the right
 - align: "left" | "center"
+- menu: array of string | { label: string, icon: string } — A menu under the last action (adds ⋮ if needed), shown when open
+- open: boolean — Show the menu
 
 ### TabBar
 Bottom tab bar for mobile. Place last in a Screen (before overlays).
@@ -222,6 +229,8 @@ Row in a List. Omit title for a placeholder bar.
 - trailing: "none" | "chevron" | "toggle" | "text" | "badge" | "icon"
 - 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
+- menu: array of string | { label: string, icon: string } — A menu for the row (shows … on the right if nothing else is there), shown when open
+- open: boolean — Show the menu
 
 ### Table
 Table with headers. Rows are placeholder bars unless `data` is given.