ajustacv-resume-schema 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# ajustacv-resume-schema
+
+The canonical `ResumeDocument` model (issue #69), shared by the AjustaCV
+frontend and API so neither repo keeps its own copy.
+
+Zod schemas are the source of truth. Every exported TypeScript type is inferred
+from them with `z.infer`, so the runtime validator and the compile-time types
+cannot drift apart.
+
+## Install
+
+`ajustacv.com` consumes it through the Bun workspace and always builds from
+source in this directory, so schema edits need no release:
+
+```json
+{ "dependencies": { "ajustacv-resume-schema": "workspace:*" } }
+```
+
+`api.ajustacv.com` is a separate repo whose Dockerfile copies only its own
+files, so it cannot reach this directory at build time and depends on the
+published version instead:
+
+```json
+{ "dependencies": { "ajustacv-resume-schema": "^0.1.0" } }
+```
+
+The published tarball is source-only and carries no rights (`UNLICENSED`) —
+publishing keeps the API's Docker build credential-free, it does not make the
+repo open source.
+
+## Usage
+
+```ts
+import { validateResumeDocument, type ResumeDocument } from "ajustacv-resume-schema";
+
+const result = validateResumeDocument(await request.json());
+if (!result.ok) return { status: 400, issues: result.issues };
+
+const doc: ResumeDocument = result.document;
+```
+
+Sample documents live behind a separate entry point so they never reach the
+frontend bundle:
+
+```ts
+import { FULL_RESUME, RESUME_FIXTURES } from "ajustacv-resume-schema/fixtures";
+```
+
+## The model
+
+```
+ResumeDocument
+├── header    ResumeHeader     name, headline, contacts, links, optional photo
+├── sections  ResumeSection[]  ordered; discriminated union over 8 types
+├── design    DesignSettings   templateId, free-hex accent, curated fontId, A4
+└── meta      DocumentMeta     schemaVersion, targetRole, nullable ownerId
+```
+
+The eight section types are `summary`, `experience`, `education`, `skills`,
+`languages`, `certifications`, `projects` and `custom`. `custom` is the
+catch-all that keeps parsing lossless — content an extractor cannot classify
+lands there rather than being dropped. Duplicates are allowed: a resume may
+carry two `custom` sections, or two `experience` ones.
+
+`summary` is the single-entry section (it has `entry`, not `entries`), because
+a resume has one summary paragraph and a list would allow states no UI can
+produce. Every other section holds an array.
+
+### Conventions worth knowing
+
+- **`RichLine`** is one line of an inline markdown subset — `**bold**`,
+  `*italic*`, `[label](url)`. Block structure is modelled in the schema itself
+  (bullets are arrays, not `- ` prefixes), so a line break inside a `RichLine`
+  means the producer flattened structure away and is rejected.
+- **Dates** are structured `YearMonth` (`month` optional) inside a `DateRange`
+  with a `current` flag. An ongoing range must have a null `end`, and `end` may
+  not precede `start`. Use `compareYearMonth` to order them; a missing month
+  sorts as January.
+- **Hiding is non-destructive.** A section carries `visible`, and every entry
+  carries `hiddenFields`. The values stay in the document and templates skip
+  rendering them, so nothing is lost by tucking a detail away.
+- **Page breaks** are `pageBreakBefore` flags on sections and on entries.
+- **URLs are restricted to http/https**, and markdown links inside a `RichLine`
+  to http/https/mailto. Resume content comes from parsed uploads and AI output
+  and is rendered as `href`s in the editor and the exported PDF, and a bare
+  `z.url()` accepts `javascript:` targets.
+- **Unknown keys are stripped, not rejected**, so a newer producer degrades to
+  a valid document. Real incompatibility is caught by `meta.schemaVersion`.
+- **Ids** must be unique among sections, and among entries within a section.
+  They anchor editor selection, undo/redo and version diffs, so a duplicate
+  would make those features address the wrong node.
+
+## Validation
+
+`validateResumeDocument(input)` returns a discriminated result rather than
+throwing:
+
+```ts
+{ ok: true, document: ResumeDocument } | { ok: false, issues: SchemaIssue[] }
+```
+
+Each issue carries a dotted `path` — `sections.1.entries.0.dateRange.end` — so
+the editor can anchor the error to the field that caused it. All problems are
+reported at once, not just the first.
+
+Also exported: `parseResumeDocumentJson` for text arriving from the Draft Slot
+or a request body, `isResumeDocument` as a type guard, `assertResumeDocument`
+for call sites where invalid input is a bug rather than user input, and
+`formatIssues` for logging.
+
+## Fixtures
+
+| Fixture | Covers |
+| --- | --- |
+| `FULL_RESUME` | realistic pt-BR resume, all 8 section types, a hidden field, a page break |
+| `MINIMAL_RESUME` | the smallest valid document — an untouched anonymous draft |
+| `ALL_SECTION_TYPES_RESUME` | one entry per section type, plus a hidden section |
+| `HIDDEN_FIELDS_RESUME` | every hideable field, hidden, values retained |
+| `PAGE_BREAKS_RESUME` | manual breaks at both section and entry level |
+
+Each is authored as schema *input* and parsed at module load, so a fixture that
+falls behind a schema change fails on import instead of quietly teaching tests
+the wrong shape.
+
+## Releasing
+
+The frontend builds from source, so a release is only needed when the API needs
+a schema change:
+
+```bash
+cd packages/resume-schema
+bun test && bunx tsc --noEmit
+npm version patch   # minor instead for a breaking change while on 0.x
+npm publish
+```
+
+Then bump the range in `api.ajustacv.com/package.json` and run `bun install`
+there. While the version is `0.x`, a caret range allows patches but not minors,
+so a breaking change cannot reach the API silently.
+
+Only `src` ships, minus the tests — `bun test` and `bunx tsc --noEmit` must both
+pass before publishing, since consumers compile this source directly.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ajustacv-resume-schema",
+  "version": "0.1.0",
+  "description": "Canonical ResumeDocument schema, validators and fixtures shared by ajustacv.com and api.ajustacv.com",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juninhopo/ajustacv.com.git",
+    "directory": "packages/resume-schema"
+  },
+  "keywords": [
+    "ajustacv",
+    "resume",
+    "curriculo",
+    "schema"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./fixtures": "./src/fixtures.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/src/fixtures.ts

@@ -0,0 +1,464 @@
+// Sample documents for tests, prototypes and template development.
+//
+// Each fixture is authored as schema *input* and run through the validator at
+// module load, so a fixture that falls behind a schema change fails loudly on
+// import instead of quietly teaching every test the wrong shape.
+
+import { SCHEMA_VERSION, type ResumeDocument, type ResumeDocumentInput } from "./schema";
+import { assertResumeDocument } from "./validate";
+
+const DEFAULT_DESIGN = {
+  templateId: "classic",
+  accentColor: "#2062F5",
+  fontId: "dm",
+  pageSize: "a4",
+} as const;
+
+function fixture(input: ResumeDocumentInput): ResumeDocument {
+  return assertResumeDocument(input);
+}
+
+// A realistic pt-BR resume exercising all eight section types, inline
+// markdown, dates with and without a month, an ongoing role, a hidden field
+// and a manual page break — the document template work is developed against.
+export const FULL_RESUME: ResumeDocument = fixture({
+  header: {
+    fullName: "Mariana Ferreira",
+    headline: "Desenvolvedora Full Stack Sênior",
+    email: "mariana.ferreira@email.com",
+    phone: "(11) 98765-4321",
+    location: "São Paulo, SP",
+    links: [
+      {
+        id: "l1",
+        label: "linkedin.com/in/marianaferreira",
+        url: "https://linkedin.com/in/marianaferreira",
+      },
+      { id: "l2", label: "github.com/marifer", url: "https://github.com/marifer" },
+    ],
+    photoUrl: null,
+    showPhoto: false,
+  },
+  design: DEFAULT_DESIGN,
+  meta: { schemaVersion: SCHEMA_VERSION, targetRole: "Tech Lead", ownerId: null },
+  sections: [
+    {
+      id: "s-summary",
+      type: "summary",
+      title: "Resumo",
+      visible: true,
+      entry: {
+        text: "Desenvolvedora full stack com **8 anos de experiência** construindo produtos web de alto tráfego. Especialista em React, Node.js e arquitetura de microsserviços, com histórico de liderança técnica em times de até 12 pessoas.",
+      },
+    },
+    {
+      id: "s-exp",
+      type: "experience",
+      title: "Experiência Profissional",
+      visible: true,
+      entries: [
+        {
+          id: "e1",
+          role: "Desenvolvedora Full Stack Sênior",
+          company: "Nubank",
+          location: "São Paulo, SP",
+          dateRange: { start: { year: 2022, month: 3 }, end: null, current: true },
+          bullets: [
+            "Liderei a migração do fluxo de onboarding para arquitetura de micro-frontends, reduzindo o tempo de carregamento em **43%**.",
+            "Implementei pipeline de CI/CD que cortou o tempo de deploy de 40 para **8 minutos**.",
+            "Mentoria de 4 pessoas desenvolvedoras júnior, com 2 promoções no período.",
+          ],
+        },
+        {
+          id: "e2",
+          role: "Desenvolvedora Full Stack Pleno",
+          company: "iFood",
+          location: "Osasco, SP",
+          dateRange: {
+            start: { year: 2019, month: 6 },
+            end: { year: 2022, month: 2 },
+            current: false,
+          },
+          bullets: [
+            "Desenvolvi o módulo de cupons do app, usado por **2M+ usuários/mês**.",
+            "Reduzi em 60% os erros de pagamento com *retry* idempotente na integração com adquirentes.",
+          ],
+        },
+        {
+          id: "e3",
+          role: "Desenvolvedora Front-end Júnior",
+          company: "Agência Wide",
+          // The oldest role keeps its city in the data but hides it, so the
+          // entry stays compact without losing information.
+          location: "Campinas, SP",
+          hiddenFields: ["location"],
+          dateRange: {
+            start: { year: 2017, month: 1 },
+            end: { year: 2019, month: 5 },
+            current: false,
+          },
+          bullets: [
+            "Entreguei mais de 20 sites institucionais responsivos para clientes de varejo e educação.",
+          ],
+        },
+      ],
+    },
+    {
+      id: "s-edu",
+      type: "education",
+      title: "Formação Acadêmica",
+      visible: true,
+      entries: [
+        {
+          id: "ed1",
+          institution: "Universidade de São Paulo (USP)",
+          course: "Bacharelado em Ciência da Computação",
+          dateRange: { start: { year: 2013 }, end: { year: 2016 }, current: false },
+          bullets: [],
+        },
+      ],
+    },
+    {
+      id: "s-skills",
+      type: "skills",
+      title: "Habilidades",
+      visible: true,
+      entries: [
+        {
+          id: "sg1",
+          name: "Técnicas",
+          skills: ["React", "TypeScript", "Node.js", "PostgreSQL", "AWS", "Docker", "GraphQL"],
+        },
+        {
+          id: "sg2",
+          name: "Comportamentais",
+          skills: ["Liderança técnica", "Comunicação", "Mentoria"],
+        },
+      ],
+    },
+    {
+      id: "s-lang",
+      type: "languages",
+      title: "Idiomas",
+      visible: true,
+      entries: [
+        { id: "lg1", language: "Português", level: "nativo" },
+        { id: "lg2", language: "Inglês", level: "avancado" },
+        { id: "lg3", language: "Espanhol", level: "intermediario" },
+      ],
+    },
+    {
+      id: "s-cert",
+      type: "certifications",
+      title: "Certificações",
+      visible: true,
+      entries: [
+        {
+          id: "c1",
+          name: "AWS Certified Solutions Architect",
+          issuer: "Amazon Web Services",
+          date: { year: 2023, month: 8 },
+          url: "https://aws.amazon.com/verification/ABC123",
+        },
+        { id: "c2", name: "Scrum Master Certified", issuer: "Scrum Alliance", date: { year: 2021 } },
+      ],
+    },
+    {
+      id: "s-proj",
+      type: "projects",
+      // Everything below here belongs on page two of the printed resume.
+      pageBreakBefore: true,
+      title: "Projetos",
+      visible: true,
+      entries: [
+        {
+          id: "p1",
+          name: "Radar de Vagas",
+          description:
+            "Agregador open source de vagas remotas em tecnologia, com **1.2k estrelas** no GitHub.",
+          url: "https://github.com/marifer/radar-de-vagas",
+          dateRange: { start: { year: 2021, month: 2 }, end: null, current: true },
+        },
+      ],
+    },
+    {
+      id: "s-custom",
+      type: "custom",
+      title: "Voluntariado",
+      visible: true,
+      entries: [
+        {
+          id: "cu1",
+          title: "Instrutora de programação",
+          subtitle: "[Reprograma](https://reprograma.com.br)",
+          dateRange: { start: { year: 2021 }, end: null, current: true },
+          bullets: ["Aulas de JavaScript para mulheres em transição de carreira."],
+        },
+      ],
+    },
+  ],
+});
+
+// The smallest document the schema accepts: what an anonymous visitor who has
+// typed nothing still has in their Draft Slot.
+export const MINIMAL_RESUME: ResumeDocument = fixture({
+  header: {
+    fullName: "",
+    headline: "",
+    email: "",
+    phone: "",
+    location: "",
+    links: [],
+    photoUrl: null,
+    showPhoto: false,
+  },
+  sections: [],
+  design: DEFAULT_DESIGN,
+  meta: { schemaVersion: SCHEMA_VERSION, targetRole: null, ownerId: null },
+});
+
+// One entry per section type, content trimmed to the minimum. Template tests
+// render this to prove every section type has a renderer.
+export const ALL_SECTION_TYPES_RESUME: ResumeDocument = fixture({
+  header: {
+    fullName: "Joana Silva",
+    headline: "Analista de Dados",
+    email: "joana@email.com",
+    phone: "(21) 91234-5678",
+    location: "Rio de Janeiro, RJ",
+    links: [],
+    photoUrl: "https://cdn.ajustacv.com/foto/joana.jpg",
+    showPhoto: true,
+  },
+  design: { ...DEFAULT_DESIGN, templateId: "sidebar", fontId: "serif" },
+  meta: { schemaVersion: SCHEMA_VERSION, targetRole: "Analista de Dados Sênior", ownerId: "user_1" },
+  sections: [
+    { id: "t-summary", type: "summary", title: "Resumo", visible: true, entry: { text: "Analista de dados." } },
+    {
+      id: "t-exp",
+      type: "experience",
+      title: "Experiência",
+      visible: true,
+      entries: [
+        {
+          id: "t-exp-1",
+          role: "Analista de Dados",
+          company: "Petrobras",
+          dateRange: { start: { year: 2020 }, end: null, current: true },
+          bullets: ["Construí painéis de acompanhamento operacional."],
+        },
+      ],
+    },
+    {
+      id: "t-edu",
+      type: "education",
+      title: "Formação",
+      visible: true,
+      entries: [
+        {
+          id: "t-edu-1",
+          institution: "UFRJ",
+          course: "Estatística",
+          dateRange: { start: { year: 2015 }, end: { year: 2019 }, current: false },
+          bullets: [],
+        },
+      ],
+    },
+    {
+      id: "t-skills",
+      type: "skills",
+      title: "Habilidades",
+      visible: true,
+      entries: [{ id: "t-skills-1", name: "Ferramentas", skills: ["SQL", "Python", "Power BI"] }],
+    },
+    {
+      id: "t-lang",
+      type: "languages",
+      title: "Idiomas",
+      visible: true,
+      entries: [{ id: "t-lang-1", language: "Inglês", level: "fluente" }],
+    },
+    {
+      id: "t-cert",
+      type: "certifications",
+      title: "Certificações",
+      visible: true,
+      entries: [{ id: "t-cert-1", name: "DP-203", issuer: "Microsoft", date: { year: 2022 } }],
+    },
+    {
+      id: "t-proj",
+      type: "projects",
+      title: "Projetos",
+      visible: true,
+      entries: [{ id: "t-proj-1", name: "Painel COVID-RJ", description: "Painel público de indicadores." }],
+    },
+    {
+      id: "t-custom",
+      type: "custom",
+      title: "Prêmios",
+      visible: true,
+      entries: [{ id: "t-custom-1", title: "Menção honrosa", bullets: [] }],
+    },
+    // A renamed, hidden section: the content survives, templates skip it.
+    {
+      id: "t-hidden",
+      type: "custom",
+      title: "Rascunho",
+      visible: false,
+      entries: [{ id: "t-hidden-1", title: "Conteúdo guardado para depois", bullets: [] }],
+    },
+  ],
+});
+
+// Every hideable field, hidden. Templates must render this document without
+// showing any of the hidden values — and without losing them on round-trip.
+export const HIDDEN_FIELDS_RESUME: ResumeDocument = fixture({
+  header: {
+    fullName: "Paulo Mendes",
+    headline: "Designer de Produto",
+    email: "paulo@email.com",
+    phone: "(31) 99999-0000",
+    location: "Belo Horizonte, MG",
+    links: [],
+    photoUrl: "https://cdn.ajustacv.com/foto/paulo.jpg",
+    // The photo is stored but not rendered — the header's own hide switch.
+    showPhoto: false,
+  },
+  design: DEFAULT_DESIGN,
+  meta: { schemaVersion: SCHEMA_VERSION, targetRole: null, ownerId: null },
+  sections: [
+    {
+      id: "h-exp",
+      type: "experience",
+      title: "Experiência",
+      visible: true,
+      entries: [
+        {
+          id: "h-exp-1",
+          role: "Designer de Produto",
+          company: "Hotmart",
+          location: "Belo Horizonte, MG",
+          hiddenFields: ["location", "dates", "bullets"],
+          dateRange: { start: { year: 2021, month: 4 }, end: null, current: true },
+          bullets: ["Redesenhei o fluxo de checkout."],
+        },
+      ],
+    },
+    {
+      id: "h-cert",
+      type: "certifications",
+      title: "Certificações",
+      visible: true,
+      entries: [
+        {
+          id: "h-cert-1",
+          name: "Nielsen Norman UX Certification",
+          issuer: "Nielsen Norman Group",
+          hiddenFields: ["issuer", "url"],
+          date: { year: 2023, month: 5 },
+          url: "https://nngroup.com/certificate/123",
+        },
+      ],
+    },
+    {
+      id: "h-proj",
+      type: "projects",
+      title: "Projetos",
+      visible: true,
+      entries: [
+        {
+          id: "h-proj-1",
+          name: "Design System Aurora",
+          description: "Biblioteca de componentes usada por 6 times.",
+          hiddenFields: ["description", "url"],
+          url: "https://aurora.design",
+        },
+      ],
+    },
+    {
+      id: "h-custom",
+      type: "custom",
+      title: "Palestras",
+      visible: true,
+      entries: [
+        {
+          id: "h-custom-1",
+          title: "Design de produto em escala",
+          subtitle: "TDC Floripa",
+          hiddenFields: ["subtitle"],
+          bullets: [],
+        },
+      ],
+    },
+  ],
+});
+
+// Manual page breaks at both levels the schema allows: before a section and
+// before an entry inside one. Pagination tests assert the breaks land here.
+export const PAGE_BREAKS_RESUME: ResumeDocument = fixture({
+  header: {
+    fullName: "Renata Alves",
+    headline: "Gerente de Projetos",
+    email: "renata@email.com",
+    phone: "(41) 98888-1111",
+    location: "Curitiba, PR",
+    links: [],
+    photoUrl: null,
+    showPhoto: false,
+  },
+  design: { ...DEFAULT_DESIGN, templateId: "executive" },
+  meta: { schemaVersion: SCHEMA_VERSION, targetRole: "Gerente de Projetos Sênior", ownerId: "user_2" },
+  sections: [
+    {
+      id: "b-exp",
+      type: "experience",
+      title: "Experiência",
+      visible: true,
+      entries: [
+        {
+          id: "b-exp-1",
+          role: "Gerente de Projetos",
+          company: "Positivo",
+          dateRange: { start: { year: 2020 }, end: null, current: true },
+          bullets: ["Coordenei 8 projetos simultâneos de hardware educacional."],
+        },
+        {
+          id: "b-exp-2",
+          // This role must start a fresh page rather than be split across two.
+          pageBreakBefore: true,
+          role: "Analista de Projetos",
+          company: "Boticário",
+          dateRange: { start: { year: 2016 }, end: { year: 2020 }, current: false },
+          bullets: ["Implantei o processo de gestão de portfólio da área digital."],
+        },
+      ],
+    },
+    {
+      id: "b-edu",
+      type: "education",
+      // The whole education section opens page two.
+      pageBreakBefore: true,
+      title: "Formação",
+      visible: true,
+      entries: [
+        {
+          id: "b-edu-1",
+          institution: "UFPR",
+          course: "Administração",
+          dateRange: { start: { year: 2011 }, end: { year: 2015 }, current: false },
+          bullets: [],
+        },
+      ],
+    },
+  ],
+});
+
+export const RESUME_FIXTURES = {
+  full: FULL_RESUME,
+  minimal: MINIMAL_RESUME,
+  allSectionTypes: ALL_SECTION_TYPES_RESUME,
+  hiddenFields: HIDDEN_FIELDS_RESUME,
+  pageBreaks: PAGE_BREAKS_RESUME,
+} as const;
+
+export type ResumeFixtureName = keyof typeof RESUME_FIXTURES;

package/src/index.ts

@@ -0,0 +1,8 @@
+// Public surface of ajustacv-resume-schema.
+//
+// Fixtures are deliberately NOT re-exported here: they are sample data for
+// tests and prototypes, and importing them from "ajustacv-resume-schema"
+// would drag them into the frontend bundle. Import "ajustacv-resume-schema/fixtures".
+
+export * from "./schema";
+export * from "./validate";

package/src/schema.ts

@@ -0,0 +1,366 @@
+// Canonical ResumeDocument schema (issue #69, packaged by #108).
+//
+// Zod schemas are the source of truth; every exported TypeScript type is
+// inferred from them, so the runtime validator and the compile-time types
+// cannot drift apart.
+
+import { z } from "zod";
+
+// Bounds exist so the API can accept untrusted JSON without unbounded work.
+// They are deliberately generous — no realistic resume comes close.
+export const LIMITS = {
+  shortText: 200,
+  richLine: 5000,
+  url: 2000,
+  sections: 60,
+  entriesPerSection: 100,
+  bulletsPerEntry: 60,
+  skillsPerGroup: 100,
+  links: 20,
+} as const;
+
+const shortText = z.string().max(LIMITS.shortText);
+const nonEmptyId = z.string().min(1).max(LIMITS.shortText);
+// Restricted to http(s) on purpose: every URL here is rendered as an href in
+// the editor and the exported PDF, and a bare z.url() happily accepts
+// "javascript:alert(1)" — parsed resumes are untrusted input.
+const url = z.url({ protocol: /^https?$/ }).max(LIMITS.url);
+
+// ── Primitives ─────────────────────────────────────────────────────
+
+// Inline markdown subset only: **bold**, *italic*, [label](url). Block
+// structure lives in the schema itself (bullets are arrays, not "- " lines),
+// so a line break here always means the producer flattened structure away.
+export const RichLineSchema = z
+  .string()
+  .max(LIMITS.richLine)
+  .refine((value) => !/[\r\n]/.test(value), {
+    message:
+      "RichLine is a single line of inline markdown — use structured bullets instead of line breaks",
+  })
+  .refine((value) => linkTargets(value).every(isSafeLinkTarget), {
+    message: "markdown links must point at http, https or mailto",
+  });
+
+// Anchored on "](" rather than on the label, because the label is not reliably
+// parseable: "[a\]b](…)" and "[a[b]c](…)" are both links CommonMark renders,
+// and any pattern that reads the label first stops at the wrong bracket and
+// misses the target entirely. The optional "<" covers the pointy-bracket
+// destination form, "[label](<url>)".
+const LINK_TARGET = /\]\(\s*<?([^)>\s]*)/g;
+
+// CommonMark autolinks carry the scheme directly: <javascript:alert(1)>.
+const AUTOLINK_TARGET = /<([a-zA-Z][a-zA-Z0-9+.-]*:[^>\s]*)>/g;
+
+function linkTargets(value: string): string[] {
+  const inline = [...value.matchAll(LINK_TARGET)];
+  const autolinks = [...value.matchAll(AUTOLINK_TARGET)];
+  return [...inline, ...autolinks].map((match) => match[1] ?? "");
+}
+
+// An allowlist, so no case, whitespace or percent-encoding trick reaches a
+// renderer: a target is safe only if it plainly begins with a web or mail
+// scheme. Defence in depth — the renderer must still sanitise its own hrefs.
+function isSafeLinkTarget(target: string): boolean {
+  return /^(https?:\/\/|mailto:)/i.test(target);
+}
+
+export const YearMonthSchema = z.object({
+  year: z.int().min(1900).max(2100),
+  month: z.int().min(1).max(12).optional(),
+});
+
+export const DateRangeSchema = z
+  .object({
+    start: YearMonthSchema.nullable(),
+    end: YearMonthSchema.nullable(),
+    current: z.boolean(),
+  })
+  .check((ctx) => {
+    const { start, end, current } = ctx.value;
+
+    if (current && end !== null) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["end"],
+        message: "an ongoing date range (current: true) must not have an end",
+      });
+    }
+
+    if (start && end && compareYearMonth(start, end) > 0) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["end"],
+        message: "end date must not be earlier than start date",
+      });
+    }
+  });
+
+export const LANGUAGE_LEVELS = [
+  "basico",
+  "intermediario",
+  "avancado",
+  "fluente",
+  "nativo",
+] as const;
+
+export const LanguageLevelSchema = z.enum(LANGUAGE_LEVELS);
+
+// Fields an entry can hide non-destructively: the value stays in the
+// document, templates skip rendering it. Deleting is a separate action.
+export const HIDEABLE_FIELDS = [
+  "location",
+  "dates",
+  "bullets",
+  "subtitle",
+  "issuer",
+  "url",
+  "description",
+] as const;
+
+export const HideableFieldSchema = z.enum(HIDEABLE_FIELDS);
+
+// ── Header ─────────────────────────────────────────────────────────
+
+export const HeaderLinkSchema = z.object({
+  id: nonEmptyId,
+  label: shortText,
+  url,
+});
+
+export const ResumeHeaderSchema = z.object({
+  fullName: shortText,
+  headline: shortText,
+  email: z.union([z.literal(""), z.email().max(LIMITS.shortText)]),
+  phone: shortText,
+  location: shortText,
+  links: z.array(HeaderLinkSchema).max(LIMITS.links),
+  photoUrl: url.nullable(),
+  showPhoto: z.boolean(),
+});
+
+// ── Entries ────────────────────────────────────────────────────────
+
+const entryBase = {
+  id: nonEmptyId,
+  pageBreakBefore: z.boolean().default(false),
+  hiddenFields: z.array(HideableFieldSchema).default([]),
+};
+
+export const SummaryEntrySchema = z.object({ text: RichLineSchema });
+
+export const ExperienceEntrySchema = z.object({
+  ...entryBase,
+  role: shortText,
+  company: shortText,
+  location: shortText.default(""),
+  dateRange: DateRangeSchema,
+  bullets: z.array(RichLineSchema).max(LIMITS.bulletsPerEntry),
+});
+
+export const EducationEntrySchema = z.object({
+  ...entryBase,
+  institution: shortText,
+  course: shortText,
+  location: shortText.default(""),
+  dateRange: DateRangeSchema,
+  bullets: z.array(RichLineSchema).max(LIMITS.bulletsPerEntry),
+});
+
+export const SkillGroupSchema = z.object({
+  ...entryBase,
+  name: shortText,
+  skills: z.array(shortText).max(LIMITS.skillsPerGroup),
+});
+
+export const LanguageEntrySchema = z.object({
+  ...entryBase,
+  language: shortText,
+  level: LanguageLevelSchema.nullable(),
+});
+
+export const CertificationEntrySchema = z.object({
+  ...entryBase,
+  name: shortText,
+  issuer: shortText,
+  date: YearMonthSchema.nullable(),
+  url: url.nullable().default(null),
+});
+
+export const ProjectEntrySchema = z.object({
+  ...entryBase,
+  name: shortText,
+  description: RichLineSchema,
+  url: url.nullable().default(null),
+  dateRange: DateRangeSchema.nullable().default(null),
+});
+
+// The catch-all that keeps parsing lossless: anything the extractor cannot
+// map to a typed section still lands here rather than being dropped.
+export const CustomEntrySchema = z.object({
+  ...entryBase,
+  title: shortText.default(""),
+  subtitle: shortText.default(""),
+  dateRange: DateRangeSchema.nullable().default(null),
+  bullets: z.array(RichLineSchema).max(LIMITS.bulletsPerEntry),
+});
+
+// ── Sections ───────────────────────────────────────────────────────
+
+export const SECTION_TYPES = [
+  "summary",
+  "experience",
+  "education",
+  "skills",
+  "languages",
+  "certifications",
+  "projects",
+  "custom",
+] as const;
+
+export const SectionTypeSchema = z.enum(SECTION_TYPES);
+
+const sectionBase = {
+  id: nonEmptyId,
+  title: shortText,
+  visible: z.boolean(),
+  pageBreakBefore: z.boolean().default(false),
+};
+
+const entryList = <T extends z.ZodType>(entry: T) =>
+  z.array(entry).max(LIMITS.entriesPerSection);
+
+// Summary is the one single-entry section: a resume has one summary
+// paragraph, so modelling it as a list would allow states no UI can produce.
+export const ResumeSectionSchema = z.discriminatedUnion("type", [
+  z.object({ ...sectionBase, type: z.literal("summary"), entry: SummaryEntrySchema }),
+  z.object({ ...sectionBase, type: z.literal("experience"), entries: entryList(ExperienceEntrySchema) }),
+  z.object({ ...sectionBase, type: z.literal("education"), entries: entryList(EducationEntrySchema) }),
+  z.object({ ...sectionBase, type: z.literal("skills"), entries: entryList(SkillGroupSchema) }),
+  z.object({ ...sectionBase, type: z.literal("languages"), entries: entryList(LanguageEntrySchema) }),
+  z.object({ ...sectionBase, type: z.literal("certifications"), entries: entryList(CertificationEntrySchema) }),
+  z.object({ ...sectionBase, type: z.literal("projects"), entries: entryList(ProjectEntrySchema) }),
+  z.object({ ...sectionBase, type: z.literal("custom"), entries: entryList(CustomEntrySchema) }),
+]);
+
+// ── Design ─────────────────────────────────────────────────────────
+
+export const TEMPLATE_IDS = ["classic", "centered", "sidebar", "executive"] as const;
+
+export const TemplateIdSchema = z.enum(TEMPLATE_IDS);
+
+export const FONT_IDS = ["dm", "sans", "serif"] as const;
+
+export const FontIdSchema = z.enum(FONT_IDS);
+
+export const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+
+export const DesignSettingsSchema = z.object({
+  templateId: TemplateIdSchema,
+  // Free choice, not a palette — but normalised to #RRGGBB so templates can
+  // derive tints from it without re-parsing shorthand or named colours.
+  accentColor: z.string().regex(HEX_COLOR, "accentColor must be a #RRGGBB hex colour"),
+  fontId: FontIdSchema,
+  pageSize: z.literal("a4"),
+});
+
+// ── Meta ───────────────────────────────────────────────────────────
+
+export const SCHEMA_VERSION = 1;
+
+export const DocumentMetaSchema = z.object({
+  schemaVersion: z.literal(SCHEMA_VERSION),
+  targetRole: shortText.nullable(),
+  // null while the document lives in an anonymous Draft Slot; set at Claim.
+  ownerId: nonEmptyId.nullable(),
+});
+
+// ── Document ───────────────────────────────────────────────────────
+
+export const ResumeDocumentSchema = z
+  .object({
+    header: ResumeHeaderSchema,
+    sections: z.array(ResumeSectionSchema).max(LIMITS.sections),
+    design: DesignSettingsSchema,
+    meta: DocumentMetaSchema,
+  })
+  .check((ctx) => {
+    collectDuplicateIdIssues(ctx);
+  });
+
+// ── Inferred types ─────────────────────────────────────────────────
+
+export type RichLine = z.infer<typeof RichLineSchema>;
+export type YearMonth = z.infer<typeof YearMonthSchema>;
+export type DateRange = z.infer<typeof DateRangeSchema>;
+export type LanguageLevel = z.infer<typeof LanguageLevelSchema>;
+export type HideableField = z.infer<typeof HideableFieldSchema>;
+export type HeaderLink = z.infer<typeof HeaderLinkSchema>;
+export type ResumeHeader = z.infer<typeof ResumeHeaderSchema>;
+export type SummaryEntry = z.infer<typeof SummaryEntrySchema>;
+export type ExperienceEntry = z.infer<typeof ExperienceEntrySchema>;
+export type EducationEntry = z.infer<typeof EducationEntrySchema>;
+export type SkillGroup = z.infer<typeof SkillGroupSchema>;
+export type LanguageEntry = z.infer<typeof LanguageEntrySchema>;
+export type CertificationEntry = z.infer<typeof CertificationEntrySchema>;
+export type ProjectEntry = z.infer<typeof ProjectEntrySchema>;
+export type CustomEntry = z.infer<typeof CustomEntrySchema>;
+export type SectionType = z.infer<typeof SectionTypeSchema>;
+export type ResumeSection = z.infer<typeof ResumeSectionSchema>;
+export type TemplateId = z.infer<typeof TemplateIdSchema>;
+export type FontId = z.infer<typeof FontIdSchema>;
+export type DesignSettings = z.infer<typeof DesignSettingsSchema>;
+export type DocumentMeta = z.infer<typeof DocumentMetaSchema>;
+export type ResumeDocument = z.infer<typeof ResumeDocumentSchema>;
+
+// The shape callers construct: fields carrying a default may be omitted.
+export type ResumeDocumentInput = z.input<typeof ResumeDocumentSchema>;
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+// Negative when a precedes b, positive when a follows b, 0 when equal.
+// A missing month sorts as January so partial dates stay orderable.
+export function compareYearMonth(a: YearMonth, b: YearMonth): number {
+  const monthsA = a.year * 12 + ((a.month ?? 1) - 1);
+  const monthsB = b.year * 12 + ((b.month ?? 1) - 1);
+  return monthsA - monthsB;
+}
+
+// Ids anchor editor selection, undo/redo and version diffs, so a duplicate
+// makes those features address the wrong node. Reported per offender rather
+// than as one document-level failure so the caller can point at the entry.
+function collectDuplicateIdIssues(ctx: {
+  value: { sections: ResumeSection[] };
+  issues: z.core.$ZodRawIssue[];
+}): void {
+  const seenSectionIds = new Set<string>();
+
+  ctx.value.sections.forEach((section, sectionIndex) => {
+    if (seenSectionIds.has(section.id)) {
+      ctx.issues.push({
+        code: "custom",
+        input: section.id,
+        path: ["sections", sectionIndex, "id"],
+        message: `duplicate section id "${section.id}"`,
+      });
+    }
+    seenSectionIds.add(section.id);
+
+    if (section.type === "summary") return;
+
+    const seenEntryIds = new Set<string>();
+    section.entries.forEach((entry, entryIndex) => {
+      if (seenEntryIds.has(entry.id)) {
+        ctx.issues.push({
+          code: "custom",
+          input: entry.id,
+          path: ["sections", sectionIndex, "entries", entryIndex, "id"],
+          message: `duplicate entry id "${entry.id}" in section "${section.id}"`,
+        });
+      }
+      seenEntryIds.add(entry.id);
+    });
+  });
+}

package/src/validate.ts

@@ -0,0 +1,70 @@
+// Runtime validation entry points. Everything here is a thin, allocation-free
+// wrapper over ResumeDocumentSchema — the value it adds is a stable error
+// shape both repos can render, log and anchor to a field in the editor.
+
+import type { z } from "zod";
+
+import { ResumeDocumentSchema, type ResumeDocument } from "./schema";
+
+export interface SchemaIssue {
+  // Dotted path to the offending value, array indices included:
+  // "sections.1.entries.0.dateRange.end". Empty for whole-document failures.
+  path: string;
+  message: string;
+}
+
+export type ValidationResult =
+  | { ok: true; document: ResumeDocument }
+  | { ok: false; issues: SchemaIssue[] };
+
+// Unknown keys are stripped rather than rejected: a newer producer (a future
+// schemaVersion, an over-eager extractor) should degrade to a valid document,
+// not fail outright. Genuine incompatibility is caught by meta.schemaVersion.
+export function validateResumeDocument(input: unknown): ValidationResult {
+  const result = ResumeDocumentSchema.safeParse(input);
+
+  if (result.success) return { ok: true, document: result.data };
+
+  return { ok: false, issues: toSchemaIssues(result.error) };
+}
+
+// The Draft Slot and API request bodies both arrive as text, and a truncated
+// or hand-edited payload must read as an invalid document rather than a crash.
+export function parseResumeDocumentJson(raw: string | null | undefined): ValidationResult {
+  if (raw === null || raw === undefined) {
+    return { ok: false, issues: [{ path: "", message: "no document JSON was provided" }] };
+  }
+
+  try {
+    return validateResumeDocument(JSON.parse(raw));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return { ok: false, issues: [{ path: "", message: `invalid JSON: ${detail}` }] };
+  }
+}
+
+export function isResumeDocument(input: unknown): input is ResumeDocument {
+  return ResumeDocumentSchema.safeParse(input).success;
+}
+
+// For call sites where an invalid document is a bug rather than user input —
+// fixtures, migrations, tests. Prefer validateResumeDocument at any boundary.
+export function assertResumeDocument(input: unknown): ResumeDocument {
+  const result = validateResumeDocument(input);
+  if (result.ok) return result.document;
+
+  throw new Error(`invalid ResumeDocument:\n${formatIssues(result.issues)}`);
+}
+
+export function formatIssues(issues: SchemaIssue[]): string {
+  return issues
+    .map((issue) => (issue.path === "" ? issue.message : `${issue.path}: ${issue.message}`))
+    .join("\n");
+}
+
+function toSchemaIssues(error: z.ZodError): SchemaIssue[] {
+  return error.issues.map((issue) => ({
+    path: issue.path.map(String).join("."),
+    message: issue.message,
+  }));
+}