@407dev/blocks

Purpose

• Define code-first schemas using Zod as single source of truth for validation, form rendering, database storage, and edge snapshots.

Surface

• Block definition: src/define-block.ts (defineBlock, createBlockRegistry)
• Custom scalars: src/scalars.ts (assetRef, globalRef, CmsAsset, AssetRef, GlobalRef)
• JSON Schema serializer & refinement linting: src/serializer.ts (zodToJsonSchema, detectRefinements, isAdditiveOptional, RefinementError)
• Content validation: src/validator.ts (validateContent, validateBlockContent, ValidationErrorDetail, ValidationResult)
• Canonical hashing: src/canonical.ts (canonicalStringify, hashSchema)
• Types: src/types.ts (BlockConfig, BlockDefinition, JsonSchema, BlockRegistry)
• Main export: src/index.ts

Patterns

• Single Source of Truth: Zod schemas generate TS types, editor forms, API validations, and JSON Schema DB definitions.
• Custom Scalars: Branded Zod strings serialize to JSON Schema formats (cms-asset-ref, cms-global-ref) to drive UI picker controls.
• Canonical Serialization: Object keys are recursively sorted and formatted with zero whitespace before hashing for stable drift checks.
• JSON Schema Validation: Edge-compatible Draft 2020-12 validation engine (@cfworker/json-schema) validates content payloads without dynamic code generation (eval/new Function).

Integrations

• Consumed by @407dev/cli (packages/cli) for schema hashing.
• Consumed by apps/api (apps/api) for content validation on entry and block writes.
• Consumed by @407dev/cms-astro (packages/astro) for asset types.
• Consumed by @407dev/schema-form (packages/schema-form) for dynamic form rendering.

Constraints

• Publishable to public npm with ESM output and .d.ts declaration maps via tsup.
• Any exported structural changes require a changeset (pnpm changeset).
• Zero dependencies on application packages (apps/*).
• Must not use Node.js-only APIs or dynamic code generation (eval, new Function) so validation can execute in secure edge runtimes (Cloudflare Workers).

Gotchas

• No Refinements in Block Schemas: Refinements (.refine(), .superRefine()) cannot be serialized to JSON Schema and will cause zodToJsonSchema to throw RefinementError. Use serializable constraints (min, max, length, regex, enum) instead.
• Hash Stability: Drift checking relies on deterministic key-sorted JSON Schema hashing via src/canonical.ts. Never compare standard JSON.stringify outputs.
• Edge Runtime Evaluation: Validation engine must not use eval() / new Function() because Cloudflare Workers isolates disallow dynamic code generation.