@sketchscreens/core-schema 0.1.0

package/src/schema.ts

@@ -0,0 +1,256 @@
+import { z } from "zod";
+
+/**
+ * The SketchScreens contract.
+ *
+ * One JSON shape, produced by the extractor and consumed by the renderer.
+ * It is deliberately stack-agnostic: a Next.js screen and a Flutter screen
+ * both reduce to the same `ScreenSpec`, so the renderer draws them identically.
+ *
+ * Design note: `ElementType` is a CLOSED enum on purpose. Each value maps 1:1
+ * onto a renderable hand-drawn primitive (mostly wired-elements). A closed set
+ * keeps every map renderable and stops the LLM extractor from inventing element
+ * types the renderer can't draw.
+ */
+
+// ---------------------------------------------------------------------------
+// Elements — the things that appear on a screen, in top-to-bottom order.
+// ---------------------------------------------------------------------------
+
+/** The closed set of wireframe primitives. Each maps to a renderable widget. */
+export const ElementType = z.enum([
+  "heading", // a title / section header
+  "text", // a paragraph or helper/caption text
+  "input", // a single-line text field
+  "textarea", // a multi-line text field
+  "button", // a clickable button (may own a nav edge via its label)
+  "checkbox", // a single checkbox
+  "radio", // a radio option (usually one of a group)
+  "toggle", // an on/off switch
+  "select", // a dropdown / combo
+  "listbox", // a scrollable option list
+  "card", // a bordered container / tile
+  "image", // an image or avatar placeholder
+  "list", // a repeated row list (feeds, tables-as-list)
+  "divider", // a visual separator
+  "nav", // a nav bar / tab bar / menu
+  "tabs", // a tab strip
+]);
+export type ElementType = z.infer<typeof ElementType>;
+
+/** Optional visual role for buttons, so the renderer can vary emphasis. */
+export const ElementVariant = z.enum([
+  "primary",
+  "secondary",
+  "destructive",
+  "ghost",
+  "link",
+]);
+export type ElementVariant = z.infer<typeof ElementVariant>;
+
+/**
+ * Which vertical band of the screen an element sits in. `top` = a header / nav
+ * bar pinned to the top; `bottom` = a footer / sticky action bar; `main` = the
+ * scrollable body (the default). Lets the sketch mirror the real screen's
+ * coarse layout without pixel positions.
+ */
+export const ElementRegion = z.enum(["top", "main", "bottom"]);
+export type ElementRegion = z.infer<typeof ElementRegion>;
+
+/**
+ * Horizontal placement of an element within its band. `full` stretches edge to
+ * edge (inputs, nav bars, lists); `center` is a centered block (a hero button,
+ * a centered card); `left`/`right` hug a side. Default is `full` for fields and
+ * `left` for text.
+ */
+export const ElementAlign = z.enum(["left", "center", "right", "full"]);
+export type ElementAlign = z.infer<typeof ElementAlign>;
+
+/**
+ * One UI element on a screen. `label` is the visible text (button caption,
+ * field label, heading text). Order in the `elements` array = top-to-bottom
+ * position in the sketch (structural fidelity, not pixel-exact).
+ */
+export const ScreenElement = z.object({
+  type: ElementType,
+  /** Visible text: caption, label, or heading. Optional for dividers/images. */
+  label: z.string().optional(),
+  /** Placeholder / hint text for inputs. */
+  placeholder: z.string().optional(),
+  /** Visual emphasis (mainly for buttons). */
+  variant: ElementVariant.optional(),
+  /** True for password / masked inputs. */
+  secure: z.boolean().optional(),
+  /** True if the element is marked required in the source. */
+  required: z.boolean().optional(),
+  /**
+   * Optional grouping key. Elements sharing a group render inside one
+   * card/section, preserving the source's visual grouping.
+   */
+  group: z.string().optional(),
+  /**
+   * Which band of the screen this element sits in (top nav / main / bottom
+   * bar). Defaults to "main". Lets the sketch mirror the real layout.
+   */
+  region: ElementRegion.optional(),
+  /**
+   * Horizontal placement within the band. Defaults sensibly by type (fields
+   * full-width, text left). Set "center" for a centered hero button/card.
+   */
+  align: ElementAlign.optional(),
+  /**
+   * Whether `label` is the app's verbatim text or the extractor's SHAPE
+   * description of a dynamic region (a list/table it couldn't read literally).
+   * Defaults to "verbatim". The renderer styles "descriptive" labels distinctly
+   * so a reviewer sees "this is the tool's summary, not the app's words."
+   */
+  labelKind: z.enum(["verbatim", "descriptive"]).optional(),
+  /** Free-form note the extractor wants to surface (e.g. "conditionally shown"). */
+  note: z.string().optional(),
+});
+export type ScreenElement = z.infer<typeof ScreenElement>;
+
+// ---------------------------------------------------------------------------
+// Screens
+// ---------------------------------------------------------------------------
+
+/** One screen = one node in the map. */
+export const ScreenSpec = z.object({
+  /** Stable id, unique within the map. Referenced by edges. */
+  id: z.string().min(1),
+  /** Human-friendly screen name (e.g. "Login"). */
+  name: z.string().min(1),
+  /**
+   * The route or address of this screen: a URL path (`/settings/profile`),
+   * a Flutter widget class (`SettingsScreen`), or an API path group. Optional
+   * because not every screen is addressable (e.g. a modal).
+   */
+  route: z.string().optional(),
+  /** Repo-relative path of the file this screen was extracted from. */
+  sourceFile: z.string().optional(),
+  /** The elements on this screen, in top-to-bottom order. */
+  elements: z.array(ScreenElement).default([]),
+  /** Optional short description / purpose of the screen. */
+  description: z.string().optional(),
+  /**
+   * Optional label-path for this screen's section, most-general first, using
+   * " › " as the separator — e.g. "Settings › AI Settings". Groups cluster and
+   * label screens; the renderer nests group labels. Deriveable from the route.
+   * (For the overall journey SHAPE, prefer `parent` below.)
+   */
+  group: z.string().optional(),
+  /**
+   * Optional id of the screen this one hangs beneath in the JOURNEY tree — the
+   * screen a user reaches this one *from*. This is what roots the map as a real
+   * flow: an entry screen has no parent; the auth screen's parent is the entry;
+   * each feature-section hub's parent is the dashboard; etc. When set, it
+   * overrides route-derived nesting so the tree matches how users actually
+   * navigate. Must reference another screen's `id`.
+   */
+  parent: z.string().optional(),
+  /**
+   * Optional hint that this screen is the app's entry point / root of the
+   * journey (what the user sees first). At most one screen should set this; the
+   * renderer roots the tree here. If none is set, the renderer infers a root.
+   */
+  isEntry: z.boolean().optional(),
+  /**
+   * How this screen is presented. "screen" (default) is a full page/route; the
+   * others are overlays. The renderer draws non-"screen" presentations with a
+   * distinct overlay frame and attaches them to their opener via an edge rather
+   * than the journey backbone.
+   */
+  presentation: z.enum(["screen", "modal", "drawer", "sheet"]).optional(),
+  /**
+   * Optional state variant this screen represents (an empty/error/loading view
+   * of another screen). The renderer can cluster it beside its base screen.
+   */
+  state: z.enum(["default", "empty", "error", "loading"]).optional(),
+});
+export type ScreenSpec = z.infer<typeof ScreenSpec>;
+
+/** Split a group path ("Settings › AI Settings") into its segments. */
+export function groupSegments(group: string | undefined): string[] {
+  if (!group) return [];
+  return group
+    .split("›")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+// ---------------------------------------------------------------------------
+// Edges — navigation between screens
+// ---------------------------------------------------------------------------
+
+/** A navigation transition from one screen to another. */
+export const Edge = z.object({
+  /** Source screen id. */
+  from: z.string().min(1),
+  /** Destination screen id. */
+  to: z.string().min(1),
+  /**
+   * What triggers the transition — usually a button/link label
+   * ("Continue", "Forgot?"). Rendered as the edge label.
+   */
+  trigger: z.string().optional(),
+  /** How the transition is expressed, if useful (e.g. "redirect", "push", "link"). */
+  kind: z.string().optional(),
+});
+export type Edge = z.infer<typeof Edge>;
+
+// ---------------------------------------------------------------------------
+// The map
+// ---------------------------------------------------------------------------
+
+/**
+ * Which surface this map represents. Each surface is its own map — a web app,
+ * a mobile app, a CRM, and a backend are mapped separately, not tangled into one.
+ */
+export const Surface = z.enum([
+  "web",
+  "mobile",
+  "crm",
+  "admin",
+  "backend",
+  "desktop",
+  "other",
+]);
+export type Surface = z.infer<typeof Surface>;
+
+/** Optional provenance / metadata about how this map was produced. */
+export const ProjectMapMeta = z.object({
+  /** The tool version that produced the map. */
+  generator: z.string().optional(),
+  /** Repo-relative or absolute root the map was extracted from. */
+  repoRoot: z.string().optional(),
+  /** ISO timestamp string (set by the producer; schema stays time-agnostic). */
+  generatedAt: z.string().optional(),
+  /** How elements were derived: "agent", "static", or "hybrid". */
+  extraction: z.enum(["agent", "static", "hybrid", "manual"]).optional(),
+});
+export type ProjectMapMeta = z.infer<typeof ProjectMapMeta>;
+
+/** The contract version this build of SketchScreens speaks. */
+export const CONTRACT_VERSION = 1;
+
+/** The whole thing: one surface's screens + the flow between them. */
+export const ProjectMap = z.object({
+  /**
+   * Contract version. Accepts any positive integer so an OLD renderer reading a
+   * NEWER map fails with a clear "upgrade" message (see validate.ts) rather than
+   * a generic zod "invalid literal". New fields are additive; bump only on a
+   * breaking change.
+   */
+  version: z.number().int().min(1).default(CONTRACT_VERSION),
+  /** Display name for this map (e.g. "AiPhone 360 — Web App"). */
+  name: z.string().min(1),
+  /** Which surface this represents. */
+  surface: Surface,
+  /** The screens (nodes). */
+  screens: z.array(ScreenSpec).default([]),
+  /** The navigation transitions (edges). */
+  edges: z.array(Edge).default([]),
+  /** Optional provenance. */
+  meta: ProjectMapMeta.optional(),
+});
+export type ProjectMap = z.infer<typeof ProjectMap>;

package/src/validate.ts

@@ -0,0 +1,165 @@
+import { ProjectMap, CONTRACT_VERSION } from "./schema.js";
+
+/** How serious a validation issue is. Errors fail the gate; warnings don't. */
+export type IssueSeverity = "error" | "warning";
+
+/** A validation problem found in a ProjectMap. */
+export interface ValidationIssue {
+  /** Machine-readable code. */
+  code:
+    // errors — the map is malformed and must not render
+    | "schema"
+    | "duplicate_screen_id"
+    | "edge_unknown_from"
+    | "edge_unknown_to"
+    | "self_edge"
+    | "parent_unknown"
+    | "parent_self"
+    | "parent_cycle"
+    // warnings — the map renders but something's off
+    | "no_screens"
+    | "entry_count"
+    | "duplicate_edge"
+    | "sourcefile_missing"
+    | "unsupported_version";
+  /** Error (fails the gate) or warning (renders anyway). Defaults to error. */
+  severity: IssueSeverity;
+  /** Human-readable message. */
+  message: string;
+  /** JSON-ish path to the offending value, when known. */
+  path?: string;
+}
+
+export interface ValidationResult {
+  /** True when there are no ERROR-severity issues (warnings don't fail it). */
+  ok: boolean;
+  /** The parsed map when the shape is valid (defaults applied), else undefined. */
+  map?: ProjectMap;
+  issues: ValidationIssue[];
+}
+
+/**
+ * Validate a raw object as a ProjectMap.
+ *
+ * Runs the zod schema first (shape + enums + defaults), then referential
+ * checks that zod can't express: unique screen ids and edges that point at
+ * screens that actually exist. This is the gate the extractor's output must
+ * pass before the renderer will draw it.
+ */
+export function validateProjectMap(input: unknown): ValidationResult {
+  const parsed = ProjectMap.safeParse(input);
+  if (!parsed.success) {
+    const issues: ValidationIssue[] = parsed.error.issues.map((i) => ({
+      code: "schema",
+      severity: "error",
+      message: i.message,
+      path: i.path.join("."),
+    }));
+    return { ok: false, issues };
+  }
+
+  const map = parsed.data;
+  const issues: ValidationIssue[] = [];
+  const err = (code: ValidationIssue["code"], message: string, path?: string) =>
+    issues.push({ code, severity: "error", message, path });
+  const warn = (code: ValidationIssue["code"], message: string, path?: string) =>
+    issues.push({ code, severity: "warning", message, path });
+
+  // A map from a newer contract version — render what we can, but flag it.
+  if (map.version > CONTRACT_VERSION) {
+    warn(
+      "unsupported_version",
+      `Map is contract version ${map.version} but this SketchScreens speaks ${CONTRACT_VERSION} — some things may not render. Upgrade SketchScreens.`,
+    );
+  }
+
+  // A map with no screens renders as a blank canvas — warn rather than crash.
+  if (map.screens.length === 0) {
+    warn("no_screens", "The map has no screens.");
+  }
+
+  // Unique screen ids.
+  const seen = new Set<string>();
+  for (const screen of map.screens) {
+    if (seen.has(screen.id)) {
+      err("duplicate_screen_id", `Duplicate screen id "${screen.id}".`, `screens[id=${screen.id}]`);
+    }
+    seen.add(screen.id);
+  }
+
+  // At most one entry screen; ideally exactly one (the renderer infers if 0).
+  const entryCount = map.screens.filter((s) => s.isEntry).length;
+  if (entryCount > 1) {
+    warn(
+      "entry_count",
+      `${entryCount} screens are marked isEntry; there should be exactly one (the app's first screen).`,
+    );
+  }
+
+  // Edges must reference existing screens, and not point a screen at itself.
+  const edgeKeys = new Set<string>();
+  map.edges.forEach((edge, idx) => {
+    if (!seen.has(edge.from)) {
+      err("edge_unknown_from", `Edge #${idx} references unknown source screen "${edge.from}".`, `edges[${idx}].from`);
+    }
+    if (!seen.has(edge.to)) {
+      err("edge_unknown_to", `Edge #${idx} references unknown target screen "${edge.to}".`, `edges[${idx}].to`);
+    }
+    if (edge.from === edge.to) {
+      err("self_edge", `Edge #${idx} points screen "${edge.from}" at itself.`, `edges[${idx}]`);
+    }
+    const key = `${edge.from}->${edge.to}`;
+    if (edgeKeys.has(key)) {
+      warn("duplicate_edge", `Edge #${idx} duplicates ${key}.`, `edges[${idx}]`);
+    }
+    edgeKeys.add(key);
+  });
+
+  // Journey `parent` links: must reference an existing screen, not self, and
+  // must not form a cycle (walking parents from any screen must terminate).
+  const parentOf = new Map<string, string>();
+  for (const screen of map.screens) {
+    if (screen.parent === undefined) continue;
+    if (screen.parent === screen.id) {
+      err("parent_self", `Screen "${screen.id}" lists itself as its parent.`, `screens[id=${screen.id}].parent`);
+      continue;
+    }
+    if (!seen.has(screen.parent)) {
+      err("parent_unknown", `Screen "${screen.id}" has unknown parent "${screen.parent}".`, `screens[id=${screen.id}].parent`);
+      continue;
+    }
+    parentOf.set(screen.id, screen.parent);
+  }
+  // Cycle detection over the parent chains.
+  for (const start of parentOf.keys()) {
+    const visited = new Set<string>([start]);
+    let cur = parentOf.get(start);
+    while (cur !== undefined) {
+      if (visited.has(cur)) {
+        err("parent_cycle", `Parent chain from "${start}" forms a cycle at "${cur}".`, `screens[id=${start}].parent`);
+        break;
+      }
+      visited.add(cur);
+      cur = parentOf.get(cur);
+    }
+  }
+
+  // The gate fails only on ERROR-severity issues; warnings render anyway.
+  const ok = !issues.some((i) => i.severity === "error");
+  return { ok, map, issues };
+}
+
+/**
+ * Like {@link validateProjectMap} but throws on failure. Useful in scripts
+ * and tests where an invalid map should hard-stop.
+ */
+export function parseProjectMap(input: unknown): ProjectMap {
+  const result = validateProjectMap(input);
+  if (!result.ok || !result.map) {
+    const detail = result.issues
+      .map((i) => `  - [${i.code}] ${i.message}${i.path ? ` (${i.path})` : ""}`)
+      .join("\n");
+    throw new Error(`Invalid ProjectMap:\n${detail}`);
+  }
+  return result.map;
+}