@sketchscreens/core-schema 0.1.0

package/dist/schema.js

@@ -0,0 +1,231 @@
+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
+]);
+/** Optional visual role for buttons, so the renderer can vary emphasis. */
+export const ElementVariant = z.enum([
+    "primary",
+    "secondary",
+    "destructive",
+    "ghost",
+    "link",
+]);
+/**
+ * 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"]);
+/**
+ * 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"]);
+/**
+ * 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(),
+});
+// ---------------------------------------------------------------------------
+// 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(),
+});
+/** Split a group path ("Settings › AI Settings") into its segments. */
+export function groupSegments(group) {
+    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(),
+});
+// ---------------------------------------------------------------------------
+// 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",
+]);
+/** 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(),
+});
+/** 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(),
+});
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/validate.d.ts

@@ -0,0 +1,36 @@
+import { ProjectMap } 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: "schema" | "duplicate_screen_id" | "edge_unknown_from" | "edge_unknown_to" | "self_edge" | "parent_unknown" | "parent_self" | "parent_cycle" | "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 declare function validateProjectMap(input: unknown): ValidationResult;
+/**
+ * Like {@link validateProjectMap} but throws on failure. Useful in scripts
+ * and tests where an invalid map should hard-stop.
+ */
+export declare function parseProjectMap(input: unknown): ProjectMap;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAoB,MAAM,aAAa,CAAC;AAE3D,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhD,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,IAAI,EAEA,QAAQ,GACR,qBAAqB,GACrB,mBAAmB,GACnB,iBAAiB,GACjB,WAAW,GACX,gBAAgB,GAChB,aAAa,GACb,cAAc,GAEd,YAAY,GACZ,aAAa,GACb,gBAAgB,GAChB,oBAAoB,GACpB,qBAAqB,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,EAAE,aAAa,CAAC;IACxB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,EAAE,EAAE,OAAO,CAAC;IACZ,iFAAiF;IACjF,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAqGnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAS1D"}

package/dist/validate.js

@@ -0,0 +1,111 @@
+import { ProjectMap, CONTRACT_VERSION } from "./schema.js";
+/**
+ * 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) {
+    const parsed = ProjectMap.safeParse(input);
+    if (!parsed.success) {
+        const issues = 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 = [];
+    const err = (code, message, path) => issues.push({ code, severity: "error", message, path });
+    const warn = (code, message, path) => 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();
+    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();
+    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();
+    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([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) {
+    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;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@sketchscreens/core-schema",
+  "version": "0.1.0",
+  "description": "The ProjectMap / ScreenSpec contract — the stack-agnostic shape that the extractor produces and the renderer consumes.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./audit": {
+      "types": "./dist/audit.d.ts",
+      "import": "./dist/audit.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test --import tsx test/*.test.ts"
+  }
+}

package/src/audit.ts

@@ -0,0 +1,67 @@
+import { existsSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import type { ProjectMap } from "./schema.js";
+import type { ValidationIssue } from "./validate.js";
+
+/**
+ * NODE-ONLY provenance audit. Separate from validate.ts (which stays
+ * browser-safe) because this touches the filesystem — only the CLI imports it.
+ *
+ * Verifies each screen's `sourceFile` actually exists under the repo root, so a
+ * hallucinated path can't masquerade as real provenance. Missing files are
+ * WARNINGS, not errors: a modal/dialog screen may legitimately have no file.
+ */
+
+export interface AuditResult {
+  /** Repo root the sourceFiles were resolved against. */
+  repoRoot: string;
+  /** How many screens declared a sourceFile. */
+  withSourceFile: number;
+  /** How many of those resolved to a real file. */
+  resolved: number;
+  /** sourceFiles that didn't resolve (repo-relative as written). */
+  missing: string[];
+  /** Warning issues (one per missing sourceFile). */
+  issues: ValidationIssue[];
+}
+
+/**
+ * Audit a map's `sourceFile`s against `repoRoot`. Pass the root from the map's
+ * `meta.repoRoot` (or the cwd the extraction ran in). `~` is expanded.
+ */
+export function auditSourceFiles(map: ProjectMap, repoRoot: string): AuditResult {
+  const root = expandHome(repoRoot);
+  const missing: string[] = [];
+  const issues: ValidationIssue[] = [];
+  let withSourceFile = 0;
+  let resolved = 0;
+
+  for (const screen of map.screens) {
+    const sf = screen.sourceFile;
+    if (!sf) continue;
+    withSourceFile++;
+    const abs = isAbsolute(sf) ? sf : resolve(root, sf);
+    if (existsSync(abs) && statSync(abs).isFile()) {
+      resolved++;
+    } else {
+      missing.push(sf);
+      issues.push({
+        code: "sourcefile_missing",
+        severity: "warning",
+        message: `Screen "${screen.id}" sourceFile does not exist: ${sf}`,
+        path: `screens[id=${screen.id}].sourceFile`,
+      });
+    }
+  }
+
+  return { repoRoot: root, withSourceFile, resolved, missing, issues };
+}
+
+/** Expand a leading ~ to the user's home directory. */
+function expandHome(p: string): string {
+  if (p === "~" || p.startsWith("~/")) {
+    const home = process.env.HOME || process.env.USERPROFILE || "";
+    return home + p.slice(1);
+  }
+  return p;
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * @sketchscreens/core-schema
+ *
+ * The contract at the center of SketchScreens: the `ProjectMap` shape that the
+ * extractor produces and the renderer consumes. Import the zod schemas to
+ * validate, or the inferred types to build maps in TypeScript.
+ */
+
+export {
+  ElementType,
+  ElementVariant,
+  ElementRegion,
+  ElementAlign,
+  ScreenElement,
+  ScreenSpec,
+  Edge,
+  Surface,
+  ProjectMapMeta,
+  ProjectMap,
+  groupSegments,
+} from "./schema.js";
+
+export type {
+  ElementType as ElementTypeT,
+  ElementVariant as ElementVariantT,
+  ElementRegion as ElementRegionT,
+  ElementAlign as ElementAlignT,
+  ScreenElement as ScreenElementT,
+  ScreenSpec as ScreenSpecT,
+  Edge as EdgeT,
+  Surface as SurfaceT,
+  ProjectMapMeta as ProjectMapMetaT,
+  ProjectMap as ProjectMapT,
+} from "./schema.js";
+
+export {
+  validateProjectMap,
+  parseProjectMap,
+  type ValidationIssue,
+  type ValidationResult,
+  type IssueSeverity,
+} from "./validate.js";
+
+// NOTE: the filesystem audit (auditSourceFiles) lives in ./audit.js and is
+// intentionally NOT re-exported here — it imports node:fs and would pollute the
+// browser bundle. CLIs import it via the "@sketchscreens/core-schema/audit"
+// subpath export (see package.json).