@stdout-design/core 0.1.1

package/dist/schema.d.mts

@@ -0,0 +1,2 @@
+import { i as defineSchema, t as PropSchema } from "./validation-BUNZnc-5.mjs";
+export { type PropSchema, defineSchema };

package/dist/schema.mjs

@@ -0,0 +1,2 @@
+import { n as defineSchema } from "./validation-CMTs74Vm.mjs";
+export { defineSchema };

package/dist/validation-BUNZnc-5.d.mts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+//#region src/shared/validation.d.ts
+/**
+ * Single source of truth for the prop-schema type. Previously declared
+ * identically in both `props.ts` and `validation.ts` -- consolidated here
+ * so there is exactly one place this type can drift from zod's own types.
+ */
+type PropSchema = z.ZodObject<Record<string, z.ZodTypeAny>>;
+/** Identity helper purely for inference ergonomics at the template definition site. */
+declare const defineSchema: <T extends PropSchema>(schema: T) => T;
+interface PropValidationIssue {
+  field: string;
+  expected: string;
+  received: string;
+  message: string;
+  code: string;
+  suggestion?: string;
+}
+declare class PropValidationError extends Error {
+  readonly issues: PropValidationIssue[];
+  constructor(issues: PropValidationIssue[]);
+}
+/**
+ * Validates props against a template's zod schema, reshaping any failure
+ * into a structured, agent-consumable error rather than letting a raw
+ * ZodError (verbose, deeply nested, not designed for programmatic
+ * consumption) escape to CLI/HTTP/MCP callers.
+ *
+ * This is the ONLY validation entry point in the package -- it is the
+ * function `index.ts` re-exports at the package root, and every downstream
+ * consumer (CLI exit-code reporting, MCP "error strings returned to LLM",
+ * dev-server field-level error boundaries) is expected to catch
+ * `PropValidationError` and read `.issues`, not a raw `ZodError`.
+ */
+declare const validateProps: <T extends PropSchema>(schema: T, props: unknown) => z.infer<T>;
+declare const isZodObject: (schema: unknown) => schema is z.ZodObject<Record<string, z.ZodTypeAny>>;
+declare const zodToJsonSchemaShape: (schema: z.ZodTypeAny) => Record<string, unknown>;
+//#endregion
+export { isZodObject as a, defineSchema as i, PropValidationError as n, validateProps as o, PropValidationIssue as r, zodToJsonSchemaShape as s, PropSchema as t };

package/dist/validation-CMTs74Vm.mjs

@@ -0,0 +1,202 @@
+import { z } from "zod";
+//#region src/shared/validation.ts
+/** Identity helper purely for inference ergonomics at the template definition site. */
+const defineSchema = (schema) => schema;
+var PropValidationError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(`Invalid props: ${issues.map((i) => `${i.field || "(root)"} - ${i.message}${i.suggestion ? `. Suggestion: ${i.suggestion}` : ""}`).join("; ")}`);
+		this.name = "PropValidationError";
+		this.issues = issues;
+	}
+};
+const isObject = (schema) => schema.type === "object";
+const isArray = (schema) => schema.type === "array";
+const isEnum = (schema) => schema.type === "enum";
+const isUnion = (schema) => schema.type === "union";
+const isZodString = (schema) => schema.type === "string";
+const isWrappable = (schema) => schema.type === "default" || schema.type === "optional" || schema.type === "nullable";
+const resolveFieldSchema = (schema, path) => {
+	let current = schema;
+	for (let i = 0; i < path.length; i += 1) {
+		const segment = path[i];
+		if (!(i === path.length - 1) && isWrappable(current)) current = current.unwrap();
+		if (typeof segment === "number") {
+			if (isArray(current)) {
+				current = current.element;
+				continue;
+			}
+			return;
+		}
+		if (isObject(current)) {
+			const fieldType = current.shape[segment];
+			if (fieldType) {
+				current = fieldType;
+				continue;
+			}
+		}
+		return;
+	}
+	return current;
+};
+const primitiveLabels = {
+	any: "any value",
+	bigint: "bigint",
+	boolean: "boolean",
+	date: "date",
+	never: "never",
+	null: "null",
+	number: "number",
+	string: "string",
+	symbol: "symbol",
+	undefined: "undefined",
+	unknown: "unknown value",
+	void: "void"
+};
+const describeType = (schema) => {
+	const { type } = schema;
+	if (isWrappable(schema)) {
+		const desc = describeType(schema.unwrap());
+		if (type === "optional") return `${desc} (optional)`;
+		if (type === "nullable") return `${desc} | null`;
+		return desc;
+	}
+	if (type in primitiveLabels) return primitiveLabels[type];
+	if (isObject(schema)) return `object (${Object.entries(schema.shape).map(([key, val]) => {
+		const inner = isWrappable(val) ? val.unwrap() : val;
+		return `${key}: ${describeType(inner)}`;
+	}).join(", ")})`;
+	if (isArray(schema)) return `array of ${describeType(schema.element)}`;
+	if (isEnum(schema)) return `one of: ${schema.options.join(", ")}`;
+	if (isUnion(schema)) return `one of: ${schema.options.map((o) => {
+		const inner = isWrappable(o) ? o.unwrap() : o;
+		return describeType(inner);
+	}).join(" | ")}`;
+	if (schema.type === "literal") {
+		const val = schema.value;
+		return JSON.stringify(val ?? "?");
+	}
+	if (schema.type === "record") return "object (record)";
+	if (isZodString(schema)) {
+		if (schema.format === "url") return "URL string";
+		if (schema.format === "email") return "email string";
+		if (schema.format === "uuid") return "UUID string";
+		if (schema.minLength !== null) return `string (min ${schema.minLength} characters)`;
+		return "string";
+	}
+	return type;
+};
+const getObjectShapeKeys = (schema) => {
+	const inner = isWrappable(schema) ? schema.unwrap() : schema;
+	if (!isObject(inner)) return;
+	return Object.keys(inner.shape);
+};
+const handleInvalidType = (issue, fieldSchema) => {
+	const received = "received" in issue ? String(issue.received) : "unknown";
+	if (isWrappable(fieldSchema)) {
+		const inner = fieldSchema.unwrap();
+		return `expected ${describeType(inner)} but received ${received} — this field has a default value configured, ensure props are merged correctly before validation`;
+	}
+	if (isObject(fieldSchema) || isWrappable(fieldSchema) && isObject(fieldSchema.unwrap())) {
+		const keys = getObjectShapeKeys(fieldSchema);
+		return `expected object${keys ? ` with properties (${keys.join(", ")})` : ""} but received ${received} — add .default({}) to make this field optional`;
+	}
+	if (isArray(fieldSchema)) return `expected ${describeType(fieldSchema)} but received ${received} — add .default([]) to make this field optional`;
+	return issue.message;
+};
+const handleInvalidFormat = (issue, field) => {
+	const { format: fmt } = issue;
+	if (fmt === "url") return `invalid URL format for field '${field}' — expected a valid URL (e.g., https://example.com/image.png)`;
+	if (fmt === "email") return `invalid email format for field '${field}' — expected a valid email address`;
+	return issue.message;
+};
+const handleInvalidValue = (issue) => {
+	const { values } = issue;
+	return `expected one of: ${values?.join(", ") ?? "unknown"}`;
+};
+const handleTooSmall = (issue) => {
+	const { minimum: min, origin } = issue;
+	if (min !== null) {
+		let suffix = "";
+		if (origin === "string") suffix = "character(s)";
+		else if (origin === "array") suffix = "item(s)";
+		return `must be at least ${min} ${suffix}`;
+	}
+	return issue.message;
+};
+const enhanceMessage = (issue, fieldSchema) => {
+	const field = issue.path.join(".");
+	if (!fieldSchema) return issue.message;
+	switch (issue.code) {
+		case "invalid_type": return handleInvalidType(issue, fieldSchema);
+		case "invalid_format": return handleInvalidFormat(issue, field);
+		case "invalid_value": return handleInvalidValue(issue);
+		case "too_small": return handleTooSmall(issue);
+		case "too_big": return issue.message;
+		case "unrecognized_keys": {
+			const { keys } = issue;
+			return `unexpected field '${keys?.join(", ") ?? field}' — not recognized by the schema, check for typos or remove it`;
+		}
+		case "invalid_union": {
+			const inner = isWrappable(fieldSchema) ? fieldSchema.unwrap() : fieldSchema;
+			if (isUnion(inner)) return `did not match any valid type — expected ${describeType(inner)}`;
+			return issue.message;
+		}
+		default: return issue.message;
+	}
+};
+const getSuggestion = (issue, fieldSchema) => {
+	if (!fieldSchema) return;
+	if (issue.code === "invalid_type") {
+		if (isObject(fieldSchema)) return "add .default({}) to make this object optional";
+		if (isArray(fieldSchema)) return "add .default([]) to make this array optional";
+		if (isWrappable(fieldSchema)) return "ensure props are merged correctly before validation";
+	}
+	if (issue.code === "invalid_value") {
+		const { values } = issue;
+		if (values) return `use one of: ${values.join(", ")}`;
+	}
+	if (issue.code === "invalid_format") {
+		const { format: fmt } = issue;
+		if (fmt === "url") return "provide a valid URL starting with http:// or https://";
+		if (fmt === "email") return "provide a valid email address";
+	}
+};
+/**
+* Validates props against a template's zod schema, reshaping any failure
+* into a structured, agent-consumable error rather than letting a raw
+* ZodError (verbose, deeply nested, not designed for programmatic
+* consumption) escape to CLI/HTTP/MCP callers.
+*
+* This is the ONLY validation entry point in the package -- it is the
+* function `index.ts` re-exports at the package root, and every downstream
+* consumer (CLI exit-code reporting, MCP "error strings returned to LLM",
+* dev-server field-level error boundaries) is expected to catch
+* `PropValidationError` and read `.issues`, not a raw `ZodError`.
+*/
+const validateProps = (schema, props) => {
+	const result = schema.safeParse(props);
+	if (result.success) return result.data;
+	throw new PropValidationError(result.error.issues.map((issue) => {
+		const path = issue.path;
+		const fieldSchema = resolveFieldSchema(schema, path);
+		return {
+			code: String(issue.code),
+			expected: "expected" in issue ? String(issue.expected) : "unknown",
+			field: path.join("."),
+			message: enhanceMessage(issue, fieldSchema),
+			received: "received" in issue ? String(issue.received) : "unknown",
+			suggestion: getSuggestion(issue, fieldSchema)
+		};
+	}));
+};
+const isZodObject = (schema) => {
+	if (typeof schema !== "object" || schema === null) return false;
+	return schema.type === "object";
+};
+const zodToJsonSchemaShape = (schema) => {
+	if (typeof schema !== "object" || !schema || !("shape" in schema)) return {};
+	return z.toJSONSchema(schema);
+};
+//#endregion
+export { zodToJsonSchemaShape as a, validateProps as i, defineSchema as n, isZodObject as r, PropValidationError as t };

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@stdout-design/core",
+  "version": "0.1.1",
+  "description": "Core rendering engine for stdout-design — compile TSX templates to pixel-perfect images via Takumi",
+  "keywords": [
+    "design",
+    "image-generation",
+    "rendering",
+    "social-media",
+    "takumi",
+    "tsx"
+  ],
+  "homepage": "https://github.com/m7md1alaa/stdout-design#readme",
+  "bugs": {
+    "url": "https://github.com/m7md1alaa/stdout-design/issues"
+  },
+  "license": "MIT",
+  "author": "Mohammed alaa",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m7md1alaa/stdout-design.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": {
+        "import": "./src/index.ts",
+        "types": "./src/index.ts"
+      },
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    },
+    "./schema": {
+      "development": {
+        "import": "./src/schema.ts",
+        "types": "./src/schema.ts"
+      },
+      "import": "./dist/schema.mjs",
+      "types": "./dist/schema.d.mts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "bun test",
+    "check-types": "tsc --noEmit",
+    "check-types:tsgo": "tsgo --noEmit",
+    "lint": "ultracite check"
+  },
+  "dependencies": {
+    "@takumi-rs/core": "^2.0.0",
+    "@takumi-rs/helpers": "^2.0.0",
+    "csv-parse": "^7.0.1",
+    "kysely": "^0.29.3",
+    "kysely-bun-sqlite": "^0.4.0",
+    "p-limit": "^7.0.0",
+    "proper-lockfile": "^4.1.2",
+    "react": "^19.2.7",
+    "takumi-js": "^2.0.0",
+    "write-file-atomic": "^8.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@sinonjs/fake-timers": "^15.4.0",
+    "@stdout-design/config": "workspace:*",
+    "@takumi-rs/wasm": "^2.0.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/react": "^19.2.17",
+    "@types/sinonjs__fake-timers": "^15.0.1",
+    "@types/write-file-atomic": "^4.0.3",
+    "tsdown": "^0.22.4",
+    "typescript": "^7"
+  }
+}