makersclaw 0.7.0 → 0.8.1

package/templates/next/files/components/ui/field.jsx

@@ -23,10 +23,14 @@ const CONTROL = `w-full ${BOX}`;
 const ownWidth = (className) => /(?:^|\s)!?(?:w|size)-/.test(className ?? "");
 
 /** Label, control, hint and error in one stack. Pass `id`; the label
- *  points at it. `error` (a string) marks the control invalid. */
+ *  points at it. `error` (a string) marks the control invalid.
+ *  Two Fields side by side in a grid row are stretched to the taller one;
+ *  `content-start` keeps the shorter one's label and control at the top
+ *  where they were (without it the grid spread them apart, and Start
+ *  date's box sat lower than Target date's when only Target had a hint). */
 export function Field({ id, label, hint, error, required, className, children }) {
   return (
-    <div className={cx("grid gap-1.5", className)}>
+    <div className={cx("grid content-start gap-1.5", className)}>
       {label ? (
         <label htmlFor={id} className="text-sm font-medium text-foreground">
           {label}
@@ -177,15 +181,24 @@ export function Textarea({ className, invalid, rows = 4, autoGrow = false, minRo
  * `options` is empty it renders `empty` (a short muted line, or nothing
  * when `empty` is null) rather than a disabled dropdown. For "pick a
  * saved record or make a new one" use RecordSwitcher (components/parts).
+ * A width in `className` (w-40, w-fit, w-[12rem], size-10) sets the width of
+ * the whole control, as it does on an Input (0.8.1).
  */
 export function Select({ options, empty = "Nothing to choose yet.", className, invalid, children, ...rest }) {
   if (options && options.length === 0 && !children) {
     return empty ? <p className="text-sm text-muted-foreground">{empty}</p> : null;
   }
+  // As Input: a width in className (w-40, w-auto, w-[12rem], size-10) is
+  // honoured. The chevron sits on the wrapper, so the width goes to the
+  // wrapper and the select fills it; the rest of className stays on the
+  // select. Without one it is as wide as its column, as before.
+  const tokens = String(className ?? "").split(/\s+/).filter(Boolean);
+  const own = tokens.filter((t) => /^!?(?:w|size)-/.test(t));
+  const others = tokens.filter((t) => !own.includes(t));
   return (
-    <span className="relative block">
+    <span className={cx("relative block", own.join(" "))}>
       <select
-        className={cx(CONTROL, "appearance-none pr-9", className)}
+        className={cx(CONTROL, "appearance-none pr-9", others.join(" "))}
         aria-invalid={invalid ? true : undefined}
         {...rest}
       >

package/templates/next/files/components/ui/icon.jsx

@@ -186,6 +186,19 @@ const PATHS = {
   "calendar-check": "M3 5h18v16H3zM16 3v4M8 3v4M3 10h18M9 15.5l2 2 4-4",
   "trash-2": "M3 6h18M8 6V4h8v2m-9 0 1 14h8l1-14M10 11v6M14 11v6",
   network: "M9 2h6v6H9zM2 16h6v6H2zM16 16h6v6h-6zM12 8v4M5 16v-4h14v4",
+  // Automations (flow-editor and the blocks around it): one glyph per kind
+  // of step, drawn to the same 24 box. calendar-clock is a schedule's
+  // trigger, split a condition's fork, braces a set of values, timer a
+  // wait, plug a connected tool, bot the agent, workflow another
+  // automation, book-open a read of the company brain.
+  "calendar-clock": "M12 21H5V5h14v7M3 10h18M8 3v4M16 3v4M17.5 14a4 4 0 1 0 .01 0M17.5 16v2l1.2.8",
+  split: "M3 12h5c3 0 3-6 6-6h6M8 12c3 0 3 6 6 6h6M17 3l3 3-3 3M17 15l3 3-3 3",
+  braces: "M8 3H7a2 2 0 0 0-2 2v4a2 2 0 0 1-2 2 2 2 0 0 1 2 2v4a2 2 0 0 0 2 2h1M16 3h1a2 2 0 0 1 2 2v4a2 2 0 0 0 2 2 2 2 0 0 0-2 2v4a2 2 0 0 1-2 2h-1",
+  timer: "M10 2h4M12 8v5l3 2M12 6a8 8 0 1 0 0 16 8 8 0 0 0 0-16Z",
+  plug: "M9 2v5M15 2v5M6 7h12v4a6 6 0 0 1-12 0V7ZM12 17v5",
+  bot: "M12 3v3M5 8h14v11H5ZM9 13h.01M15 13h.01M2 13v3M22 13v3M9 17h6",
+  workflow: "M3 4h7v7H3zM14 13h7v7h-7zM10 7.5h2.5a2 2 0 0 1 2 2V13",
+  "book-open": "M12 6c-2-2-5-3-9-3v15c4 0 7 1 9 3 2-2 5-3 9-3V3c-4 0-7 1-9 3ZM12 6v15",
 };
 
 const BRANDS = {

package/templates/next/files/components/ui/index.js

@@ -5,7 +5,7 @@ export { cx } from "./cx";
 export { Icon, ICON_NAMES } from "./icon";
 export { Button, IconButton } from "./button";
 export { Field, Input, TimeInput, Textarea, Select, Switch, Checkbox } from "./field";
-export { Card, Notice, Badge, Kicker, Empty } from "./notice";
+export { Card, ActionCard, Notice, Badge, Kicker, Empty } from "./notice";
 export { Sheet, Confirm } from "./sheet";
 export { Tabs, TabPanel } from "./tabs";
 export { Menu, MenuPanel } from "./menu";
@@ -48,6 +48,8 @@ export { Stat, StatGroup, Delta, StatusDot, Legend, Meter } from "./stat";
 export { Steps } from "./steps";
 export { Separator, Kbd, KbdGroup, AspectRatio } from "./separator";
 export { ScrollArea } from "./scroll-area";
+export { AppLayout, DocumentLayout } from "./layout";
+export { PageLayout } from "./page";
 export { Slider } from "./slider";
 export { InputGroup, PasswordInput } from "./input-group";
 export { Image } from "./image";

package/templates/next/files/components/ui/layout.jsx

@@ -0,0 +1,382 @@
+"use client";
+
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+import { cx } from "./cx";
+import { Button, IconButton } from "./button";
+import { Sheet } from "./sheet";
+
+// Layouts — who owns the window's height, and who scrolls.
+//
+// Every design-first build of 2026-10-07 shipped a shell of `min-h-dvh`
+// that grew with its content: the page itself scrolled, no pane scrolled
+// on its own, and a footer, an inspector or a button below a long
+// article sat past the end of the iframe, where nothing could reach it.
+// So the kit owns the window's height, once, and the app's code never
+// sizes anything by the window (`npm run check` refuses min-h-dvh,
+// h-screen, 100vh, h-[80vh]… outside the kit, rule 12).
+//
+// AppLayout — the app frame. Exactly one owns the viewport: the
+// outermost. A layout inside another fills the slot it is in instead,
+// whatever `height` says, so there is never a second viewport owner. The
+// shell (app/shell.jsx) is the outermost one in every app the template
+// lays; a surface that needs an inspector or a fill of its own returns
+// an AppLayout as its outermost element, and it fills the shell's
+// content edge to edge (the content's padding drops for it).
+//
+//   header         the top bar, always in view (title, the surface's
+//                  commands). The bar draws its own bottom border
+//   navigation     the surfaces, a page tree: a rail beside the content
+//                  from md (768px); below md a Sheet from the leading
+//                  edge, opened by the menu button in the top bar. A
+//                  press on a link or a button inside closes it
+//   navigationLabel  the Sheet's title and the menu button's words
+//                  ("Navigation")
+//   navigationWidth  the rail, in px (176; 160 to 320)
+//   children       the content. It scrolls inside its own region
+//   contentMode    scroll (the default): the content region scrolls ·
+//                  fill: the region is a bounded flex column and the
+//                  child owns its own scrolling (a canvas, a grid, a
+//                  spreadsheet, an editor that scrolls itself)
+//   contentLabel   the content region's name for a screen reader ("Content")
+//   contentClassName  spacing and token backgrounds for the content
+//                  region (p-4 sm:p-6, bg-card). Never a height or an
+//                  overflow: the layout owns those
+//   scrollKey      when it changes the content scrolls back to its top
+//                  and the navigation Sheet closes: pass the route
+//                  (usePathname()), since the frame stays mounted while
+//                  the surfaces change inside it
+//   inspector      the details, review or feedback panel beside the
+//                  content, scrolling on its own
+//   inspectorLabel the inspector region's name ("Details")
+//   inspectorWidth in px (360; 240 to 560). Builds have needed 300 and 440
+//   inspectorAt    md · lg (the default) · xl: the width from which the
+//                  inspector sits beside the content
+//   inspectorIn    window (the default): inspectorAt is the window's
+//                  width (768 · 1024 · 1280 px) · frame: it is the
+//                  width of the body between the rail and the dock
+//                  (42 · 48 · 64 rem), so an agent dock that takes a
+//                  quarter of the window makes the inspector go under
+//                  the work when there is no room, not squeeze it
+//   footer         under the content, always in view (the save state,
+//                  the composer, the commands for what is above)
+//   dock           a column beside the whole body (rail, content and
+//                  inspector), under the header, that the app's own
+//                  block draws: the agent's dock (blocks/agent-dock).
+//                  It sizes itself, remembers its width and, where the
+//                  body is too narrow, lays itself over the app as a
+//                  sheet; the layout only gives it a place in the row
+//                  and takes no part in its width. Nothing when it is
+//                  not given
+//   height         viewport (the default): the frame is the window's
+//                  height · parent: it fills a bounded parent. Nested,
+//                  it is parent whatever this says
+//   className      the frame's own tokens; never a height or an overflow
+//
+// Below `inspectorAt`, where there is no room for two columns:
+//   - contentMode scroll: the content and the inspector share ONE scroll
+//     region, the inspector after the content. Everything is reachable
+//     by scrolling, and nothing is hidden behind a button.
+//   - contentMode fill: the content keeps the room and the inspector is
+//     a bounded pane under it (at most 45% of the height), scrolling on
+//     its own. A fill child has no flow to stack into, and a pane with
+//     no bound under it is cut off (workspace-layout's fault, 2026-10-07).
+//   The footer stays under both, in view.
+//
+// In print the frame lets go: no bound, no overflow, no navigation, no
+// header, inspector or footer; the content flows onto pages. A page meant
+// for print or export is a DocumentLayout inside the content.
+
+const Nested = createContext(false);
+
+const px = (value, fallback, min, max) => {
+  const n = Number(value);
+  return `${Number.isFinite(n) && n > 0 ? Math.min(max, Math.max(min, Math.round(n))) : fallback}px`;
+};
+
+// Tailwind reads class names whole from the source, so every breakpoint
+// is written out.
+const BESIDE = {
+  md: {
+    main: "md:grid md:grid-cols-[minmax(0,1fr)_var(--app-inspector)] md:grid-rows-[minmax(0,1fr)_auto]",
+    flow: "md:contents",
+    content: "md:col-start-1 md:row-start-1",
+    scrolls: "md:min-h-0 md:overflow-y-auto md:overscroll-contain",
+    inspector: "md:col-start-2 md:row-span-2 md:row-start-1 md:max-h-none md:min-h-0 md:overflow-y-auto md:border-l md:border-t-0",
+    footer: "md:col-start-1 md:row-start-2",
+  },
+  lg: {
+    main: "lg:grid lg:grid-cols-[minmax(0,1fr)_var(--app-inspector)] lg:grid-rows-[minmax(0,1fr)_auto]",
+    flow: "lg:contents",
+    content: "lg:col-start-1 lg:row-start-1",
+    scrolls: "lg:min-h-0 lg:overflow-y-auto lg:overscroll-contain",
+    inspector: "lg:col-start-2 lg:row-span-2 lg:row-start-1 lg:max-h-none lg:min-h-0 lg:overflow-y-auto lg:border-l lg:border-t-0",
+    footer: "lg:col-start-1 lg:row-start-2",
+  },
+  xl: {
+    main: "xl:grid xl:grid-cols-[minmax(0,1fr)_var(--app-inspector)] xl:grid-rows-[minmax(0,1fr)_auto]",
+    flow: "xl:contents",
+    content: "xl:col-start-1 xl:row-start-1",
+    scrolls: "xl:min-h-0 xl:overflow-y-auto xl:overscroll-contain",
+    inspector: "xl:col-start-2 xl:row-span-2 xl:row-start-1 xl:max-h-none xl:min-h-0 xl:overflow-y-auto xl:border-l xl:border-t-0",
+    footer: "xl:col-start-1 xl:row-start-2",
+  },
+};
+
+// The same classes by the width of the body's own column (a container
+// query on the frame between the rail and the dock), for an app whose dock
+// takes a quarter of the window: md is a body 42rem wide, lg 48rem, xl 64rem.
+const BESIDE_FRAME = {
+  md: {
+    main: "@2xl:grid @2xl:grid-cols-[minmax(0,1fr)_var(--app-inspector)] @2xl:grid-rows-[minmax(0,1fr)_auto]",
+    flow: "@2xl:contents",
+    content: "@2xl:col-start-1 @2xl:row-start-1",
+    scrolls: "@2xl:min-h-0 @2xl:overflow-y-auto @2xl:overscroll-contain",
+    inspector: "@2xl:col-start-2 @2xl:row-span-2 @2xl:row-start-1 @2xl:max-h-none @2xl:min-h-0 @2xl:overflow-y-auto @2xl:border-l @2xl:border-t-0",
+    footer: "@2xl:col-start-1 @2xl:row-start-2",
+  },
+  lg: {
+    main: "@3xl:grid @3xl:grid-cols-[minmax(0,1fr)_var(--app-inspector)] @3xl:grid-rows-[minmax(0,1fr)_auto]",
+    flow: "@3xl:contents",
+    content: "@3xl:col-start-1 @3xl:row-start-1",
+    scrolls: "@3xl:min-h-0 @3xl:overflow-y-auto @3xl:overscroll-contain",
+    inspector: "@3xl:col-start-2 @3xl:row-span-2 @3xl:row-start-1 @3xl:max-h-none @3xl:min-h-0 @3xl:overflow-y-auto @3xl:border-l @3xl:border-t-0",
+    footer: "@3xl:col-start-1 @3xl:row-start-2",
+  },
+  xl: {
+    main: "@5xl:grid @5xl:grid-cols-[minmax(0,1fr)_var(--app-inspector)] @5xl:grid-rows-[minmax(0,1fr)_auto]",
+    flow: "@5xl:contents",
+    content: "@5xl:col-start-1 @5xl:row-start-1",
+    scrolls: "@5xl:min-h-0 @5xl:overflow-y-auto @5xl:overscroll-contain",
+    inspector: "@5xl:col-start-2 @5xl:row-span-2 @5xl:row-start-1 @5xl:max-h-none @5xl:min-h-0 @5xl:overflow-y-auto @5xl:border-l @5xl:border-t-0",
+    footer: "@5xl:col-start-1 @5xl:row-start-2",
+  },
+};
+
+// inspectorIn="frame": the body's column is the container the BESIDE_FRAME
+// classes answer to. Off, it is nothing: the children, in the same place.
+function FrameBox({ on, children }) {
+  if (!on) return children;
+  return (
+    <div data-layout-frame className={cx("@container flex min-h-0 min-w-0 flex-1 flex-col", LETS_GO)}>
+      {children}
+    </div>
+  );
+}
+
+const REGION = "outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring";
+
+// The inspector holds its width and its contents fit it (UI review X4: a
+// shelf's row ran out of the panel and its title was cut at the edge). A
+// grid with no grid-cols-* has one `auto` column, and `auto` grows to its
+// widest child's minimum width, past the panel; the usual inspector is
+// exactly `<div className="grid content-start gap-3 p-4">`. So the panel's
+// own direct children may not grow it (min-w-0), a direct child that is a
+// grid with no columns of its own gets the one column that can shrink
+// (minmax(0,1fr)), and nothing paints past the panel's edge (overflow-x
+// hidden: a wide child wraps or truncates, it does not sideways-scroll).
+const INSPECTOR_FIT =
+  "min-w-0 max-w-full overflow-x-hidden [&>*]:min-w-0 [&>.grid:not([class*=grid-cols])]:grid-cols-[minmax(0,1fr)]";
+const LETS_GO = "print:block print:h-auto print:min-h-0 print:overflow-visible";
+
+export function AppLayout({
+  header,
+  navigation,
+  navigationLabel = "Navigation",
+  navigationWidth,
+  children,
+  contentMode = "scroll",
+  contentLabel = "Content",
+  contentClassName,
+  scrollKey,
+  inspector,
+  inspectorLabel = "Details",
+  inspectorWidth,
+  inspectorAt = "lg",
+  inspectorIn = "window",
+  footer,
+  dock,
+  height = "viewport",
+  className,
+}) {
+  const nested = useContext(Nested);
+  const bounded = nested || height === "parent";
+  const fill = contentMode === "fill";
+  const byFrame = inspectorIn === "frame";
+  const table = byFrame ? BESIDE_FRAME : BESIDE;
+  const at = table[inspectorAt] ?? table.lg;
+  const hasInspector = inspector != null && inspector !== false;
+  const hasNavigation = navigation != null && navigation !== false;
+  const shared = hasInspector && !fill; // below `at`: content and inspector in one scroll region
+  const [open, setOpen] = useState(false);
+  const flowRef = useRef(null);
+  const contentRef = useRef(null);
+
+  useEffect(() => {
+    if (flowRef.current) flowRef.current.scrollTop = 0;
+    if (contentRef.current) contentRef.current.scrollTop = 0;
+    setOpen(false);
+  }, [scrollKey]);
+
+  return (
+    <Nested.Provider value={true}>
+      <div
+        data-app-layout={bounded ? "parent" : "viewport"}
+        style={{ "--app-nav": px(navigationWidth, 176, 160, 320), "--app-inspector": px(inspectorWidth, 360, 240, 560) }}
+        className={cx(
+          "flex min-w-0 flex-col overflow-hidden bg-background text-foreground",
+          bounded ? "h-full min-h-0 flex-1" : "h-dvh",
+          LETS_GO,
+          className,
+        )}
+      >
+        {header != null && header !== false ? (
+          <div data-layout-header className="flex shrink-0 items-center gap-1 border-b border-border print:hidden">
+            {hasNavigation ? (
+              <IconButton icon="menu" label={`Open ${navigationLabel.toLowerCase()}`} onClick={() => setOpen(true)} className="ml-1 md:hidden" />
+            ) : null}
+            <div className="min-w-0 flex-1">{header}</div>
+          </div>
+        ) : hasNavigation ? (
+          <div data-layout-header className="flex shrink-0 items-center border-b border-border px-1 py-1 md:hidden print:hidden">
+            <Button variant="quiet" size="sm" icon="menu" onClick={() => setOpen(true)}>
+              {navigationLabel}
+            </Button>
+          </div>
+        ) : null}
+
+        {hasNavigation ? (
+          <Sheet open={open} onClose={() => setOpen(false)} title={navigationLabel} side="start">
+            {open ? (
+              <div
+                onClick={(e) => {
+                  if (e.target instanceof Element && e.target.closest("a,button")) setOpen(false);
+                }}
+              >
+                {navigation}
+              </div>
+            ) : null}
+          </Sheet>
+        ) : null}
+
+        <div data-layout-body className={cx("flex min-h-0 min-w-0 flex-1", LETS_GO)}>
+          {hasNavigation ? (
+            <div
+              data-layout-navigation
+              className="hidden shrink-0 flex-col overflow-y-auto overscroll-contain border-r border-border md:flex md:w-(--app-nav) print:hidden"
+            >
+              {navigation}
+            </div>
+          ) : null}
+
+          <FrameBox on={byFrame && hasInspector}>
+          <div data-layout-main className={cx("flex min-h-0 min-w-0 flex-1 flex-col", hasInspector && at.main, LETS_GO)}>
+            <div
+              ref={flowRef}
+              data-layout-flow
+              className={cx(
+                "flex min-h-0 min-w-0 flex-1 flex-col",
+                shared && "overflow-y-auto overscroll-contain",
+                hasInspector && at.flow,
+                LETS_GO,
+              )}
+            >
+              <div
+                ref={contentRef}
+                data-layout-content
+                role="region"
+                aria-label={contentLabel}
+                tabIndex={0}
+                className={cx(
+                  "flex min-w-0 flex-col",
+                  REGION,
+                  fill
+                    ? "min-h-0 flex-1 overflow-hidden"
+                    : shared
+                      ? cx("shrink-0", at.scrolls)
+                      : "min-h-0 flex-1 overflow-y-auto overscroll-contain",
+                  hasInspector && at.content,
+                  LETS_GO,
+                  contentClassName,
+                  // A surface that is a frame of its own runs to the edges.
+                  "has-[>[data-app-layout]]:p-0",
+                )}
+              >
+                {children}
+              </div>
+              {hasInspector ? (
+                <div
+                  data-layout-inspector
+                  role="region"
+                  aria-label={inspectorLabel}
+                  tabIndex={0}
+                  className={cx(
+                    "shrink-0 border-t border-border print:hidden",
+                    INSPECTOR_FIT,
+                    REGION,
+                    fill && "max-h-[45%] overflow-y-auto overscroll-contain",
+                    at.inspector,
+                  )}
+                >
+                  {inspector}
+                </div>
+              ) : null}
+            </div>
+            {footer != null && footer !== false ? (
+              <div data-layout-footer className={cx("shrink-0 border-t border-border print:hidden", hasInspector && at.footer)}>
+                {footer}
+              </div>
+            ) : null}
+          </div>
+          </FrameBox>
+          {dock != null && dock !== false ? dock : null}
+        </div>
+      </div>
+    </Nested.Provider>
+  );
+}
+
+// DocumentLayout — a page that flows: a report, an invoice, an article
+// meant for print or export. It owns no height and scrolls nothing; it
+// sits in the AppLayout's content (contentMode scroll), which scrolls it,
+// and in print the frame lets go and it flows onto pages.
+//
+//   children   the document
+//   toolbar    a bar held at the top while the document scrolls under it
+//              (Print, Export, the zoom); never printed
+//   width      prose (the default: a measure for reading) · page (A4,
+//              210mm) · letter (8.5in) · full. In print it is the paper's
+//   paper      true: drawn as a sheet on the desk on screen (bg-card, a
+//              hairline, padding); plain in print
+//   align      start (the default) · center
+//   label      the document's name for a screen reader ("Document")
+//   className  the document's own spacing and tokens; never a height
+const WIDTHS = {
+  prose: "max-w-prose",
+  page: "max-w-[210mm]",
+  letter: "max-w-[8.5in]",
+  full: "max-w-none",
+};
+
+export function DocumentLayout({ children, toolbar, width = "prose", paper = false, align = "start", label = "Document", className }) {
+  return (
+    <div data-document-layout className="flex min-w-0 flex-col">
+      {toolbar != null && toolbar !== false ? (
+        <div data-document-toolbar className="sticky top-0 z-10 border-b border-border bg-background print:hidden">
+          {toolbar}
+        </div>
+      ) : null}
+      <article
+        aria-label={label}
+        className={cx(
+          "w-full min-w-0 print:max-w-none",
+          WIDTHS[width] ?? WIDTHS.prose,
+          align === "center" && "mx-auto",
+          paper && "my-6 rounded-lg border border-border bg-card p-8 text-card-foreground shadow-sm print:my-0 print:rounded-none print:border-0 print:p-0 print:shadow-none",
+          className,
+        )}
+      >
+        {children}
+      </article>
+    </div>
+  );
+}

package/templates/next/files/components/ui/notice.jsx

@@ -53,6 +53,76 @@ export function Card({
   );
 }
 
+const STATUS_ICON = {
+  success: { name: "circle-check", box: "text-success" },
+  warning: { name: "warning", box: "text-warning" },
+  danger: { name: "warning", box: "text-destructive" },
+  neutral: { name: "info", box: "text-muted-foreground" },
+};
+
+/** A card that is one step the member takes: a title (with an icon), what
+ *  it does, optionally the state it is in, and ONE action under it.
+ *  Stacked, always: the status line above a full-width button, so neither
+ *  squeezes the other and the button's label has the room it needs.
+ *
+ *  Cards in a row are the same height, and their buttons line up (UI
+ *  review X6). A card stretches to the height of its row, and the status
+ *  and the action are pinned to the card's bottom: title, words, children,
+ *  then whatever room is left, then the status, then the button. So in a
+ *  row of four the buttons sit on one line, however long each card's words
+ *  are, and a status line in only some of them sits just above its button.
+ *  It was `self-start` (each card only as tall as its own words) from 0.8.1's
+ *  first cut: that meant ragged heights and buttons at different heights.
+ *  The big empty block it was meant to stop came from a squeezed row (check
+ *  rule 16, squeeze), not from stretching, and it cannot come back here:
+ *  the spare room is a gap above the footer, never a blank box below it.
+ *    icon         a kit icon name, before the title
+ *    title        the step ("Connect your mailbox")
+ *    description  what it does, in a sentence or two (muted)
+ *    children     anything between the description and the state (a price
+ *                 line, a form, a list of rows)
+ *    status       { tone: success · warning · danger · neutral, children } the
+ *                 state it is in, with its mark, above the action. Say
+ *                 "Connected" only when the thing exists (an account, a file).
+ *    action       the one button (or a link), laid full width below
+ *    fit          true: only as tall as its own words (self-start), for ONE
+ *                 card on its own beside something unrelated. Never for
+ *                 cards in a row: check rule 19 (stretch) refuses a row of
+ *                 ActionCards that sets self-start, or items-start on the row
+ *  For a card that holds a table or a list, use Card (padding none). For
+ *  a screen's boxes in general: Card, ActionCard, Notice, never a hand-drawn
+ *  bordered div. */
+export function ActionCard({ icon, title, description, status, action, className, children, fit = false, as: Tag = "section" }) {
+  const mark = status ? (STATUS_ICON[status.tone] ?? STATUS_ICON.neutral) : null;
+  return (
+    <Tag
+      className={cx(
+        "flex min-w-0 flex-col gap-2.5 rounded-lg border border-border bg-card p-4 text-sm text-card-foreground",
+        fit && "self-start",
+        className,
+      )}
+    >
+      <h2 className="flex min-w-0 items-center gap-2 font-semibold leading-tight">
+        {icon ? <Icon name={icon} size={16} className="shrink-0 text-muted-foreground" /> : null}
+        <span className="min-w-0">{title}</span>
+      </h2>
+      {description ? <p className="text-muted-foreground">{description}</p> : null}
+      {children}
+      {status || action ? (
+        <div className="mt-auto grid gap-2.5">
+          {status ? (
+            <div className="flex items-start gap-2 border-t border-border pt-2.5 text-[13px]">
+              <Icon name={mark.name} size={14} className={cx("mt-0.5 shrink-0", mark.box)} />
+              <div className="min-w-0">{status.children}</div>
+            </div>
+          ) : null}
+          {action ? <div className="grid">{action}</div> : null}
+        </div>
+      ) : null}
+    </Tag>
+  );
+}
+
 /** One line the user should read, with an optional action. `tone`
  *  neutral · info · success · warning · danger. Colour is the signal, so
  *  status tones are for status only — never decoration. */

package/templates/next/files/components/ui/page.jsx

@@ -0,0 +1,124 @@
+"use client";
+
+import { cx } from "./cx";
+
+// PageLayout — a screen's main area with an optional side column, taking the
+// full height of the content it sits in. The MAIN is the column that scrolls.
+// The SIDE is the fixed one: it holds its place, top to bottom, while the
+// main scrolls, and it is short.
+//
+// Why (UI review X12, 2026-10-12): Project Roadmap's Today ended at 680px in
+// a 1240px window. The screen drew its own two-column grid inside the
+// scrolling content, so it was only as tall as its words: the side column's
+// divider stopped halfway down and the bottom half of the window was empty.
+// Every screen with a side drew that grid by hand. This is the one.
+// `npm run check` (rule 23, page) refuses a hand-drawn main + side with a
+// ruled <aside>.
+//
+// What goes in the side, and what never does (UI review X13, 2026-10-12:
+// Newsletter Engine's first run was a short intro on the left and a long
+// "Name it" form in the right column. "this can only work if one column is
+// fixed, usually the 3rd column, and the middle one is scrolling"): the side
+// is a summary, the next step, a small panel, a few facts, a short list. It
+// never needs a scroll of its own. A form, a paste box, a long list, a
+// shelf of examples belong in the MAIN, where the page scrolls: a step that
+// opens reveals its own card there. The side's own scroll is a last resort
+// for a window shorter than the side (the bar is thin to say so), never how
+// a long thing is meant to be read. `npm run check` (rule 27, sidelong)
+// refuses a side column that holds a form or a long list.
+//
+// It lives INSIDE an AppLayout (the shell or the screen's own): the layout
+// owns the window's height, this fills the content region it is given. Use
+// the AppLayout's `contentMode="fill"` and give its content no padding
+// (omit `contentClassName`): the columns pad themselves, so the divider can
+// run to the edges. In contentMode scroll it fills the same.
+//
+//   children     the main area
+//   side         the side column, the FIXED one: short things (a summary, the
+//                next step, a record's facts, a small panel). It stays put
+//                while the main scrolls; never a long form or a long list.
+//                Without it the page is one scrolling column
+//   sideWidth    px (304; 220 to 560)
+//   sideAt       md · lg (the default) · xl: the width of THIS page from
+//                which the side sits beside the main (42 · 48 · 64 rem). It
+//                is the page's own width, not the window's: an open agent
+//                dock takes a quarter of the window, and the page must not
+//                be squeezed by it. Narrower, the side goes under the main in
+//                one scroll, nothing hidden behind a button
+//   mainLabel    the main area's name for a screen reader ("Content")
+//   sideLabel    the side's name ("Details")
+//   padded       default true: p-4 sm:p-6 on the main, p-4 on the side. false
+//                for a page that draws its own edges
+//   fill         true: the main is a flex column, so a child with `flex-1`
+//                (a list, a table) grows into the height instead of stopping
+//                where its rows end. With the side beside it, or alone; with
+//                the side under it (narrow) the page is one scroll and there
+//                is no height to grow into
+//   className, mainClassName, sideClassName   spacing and token backgrounds
+//                (bg-muted). Never a height or an overflow: the layout owns those
+const px = (value, fallback, min, max) => {
+  const n = Number(value);
+  return `${Number.isFinite(n) && n > 0 ? Math.min(max, Math.max(min, Math.round(n))) : fallback}px`;
+};
+
+// Tailwind reads class names whole from the source, so every size is written
+// out. md is a page 42rem wide, lg 48rem, xl 64rem (the AppLayout's
+// inspectorIn="frame" sizes).
+const BESIDE = {
+  md: {
+    grid: "@2xl:grid-cols-[minmax(0,1fr)_var(--page-side)] @2xl:grid-rows-[minmax(0,1fr)] @2xl:overflow-hidden",
+    column: "@2xl:min-h-0 @2xl:overflow-y-auto @2xl:overscroll-contain",
+    side: "@2xl:border-l @2xl:border-t-0 @2xl:[scrollbar-width:thin]",
+  },
+  lg: {
+    grid: "@3xl:grid-cols-[minmax(0,1fr)_var(--page-side)] @3xl:grid-rows-[minmax(0,1fr)] @3xl:overflow-hidden",
+    column: "@3xl:min-h-0 @3xl:overflow-y-auto @3xl:overscroll-contain",
+    side: "@3xl:border-l @3xl:border-t-0 @3xl:[scrollbar-width:thin]",
+  },
+  xl: {
+    grid: "@5xl:grid-cols-[minmax(0,1fr)_var(--page-side)] @5xl:grid-rows-[minmax(0,1fr)] @5xl:overflow-hidden",
+    column: "@5xl:min-h-0 @5xl:overflow-y-auto @5xl:overscroll-contain",
+    side: "@5xl:border-l @5xl:border-t-0 @5xl:[scrollbar-width:thin]",
+  },
+};
+
+const REGION = "outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring";
+const LETS_GO = "print:block print:h-auto print:min-h-0 print:overflow-visible";
+
+export function PageLayout({ children, side, sideWidth, sideAt = "lg", mainLabel = "Content", sideLabel = "Details", padded = true, fill = false, className, mainClassName, sideClassName }) {
+  const has = side != null && side !== false;
+  const at = BESIDE[sideAt] ?? BESIDE.lg;
+  return (
+    <div data-page-layout className={cx("@container flex min-h-0 min-w-0 flex-1 flex-col", LETS_GO, className)}>
+      <div
+        data-page-scroll
+        style={{ "--page-side": px(sideWidth, 304, 220, 560) }}
+        className={cx(
+          "grid min-h-0 min-w-0 flex-1 grid-cols-[minmax(0,1fr)] content-start",
+          has ? cx("overflow-y-auto overscroll-contain", at.grid) : "grid-rows-[minmax(0,1fr)] overflow-hidden",
+          LETS_GO,
+        )}
+      >
+        <div
+          data-page-main
+          role="region"
+          aria-label={mainLabel}
+          tabIndex={0}
+          className={cx("min-w-0", REGION, has ? at.column : "min-h-0 overflow-y-auto overscroll-contain", fill && "flex flex-col", padded && "p-4 sm:p-6", LETS_GO, mainClassName)}
+        >
+          {children}
+        </div>
+        {has ? (
+          <aside
+            data-page-side
+            aria-label={sideLabel}
+            tabIndex={0}
+            className={cx("min-w-0 border-t border-border print:hidden", REGION, at.column, at.side, padded && "p-4", sideClassName)}
+          >
+            {side}
+          </aside>
+        ) : null}
+      </div>
+    </div>
+  );
+}