@frt-platform/report-core 1.2.1 → 1.4.0

package/README.md

@@ -1,695 +1,500 @@
 # `@frt-platform/report-core`
 
-Core engine for building, validating, and migrating **report templates** – plus validating **report responses** and exporting **JSON Schema**.
+Core engine for defining, validating, migrating, diffing, and serializing **dynamic report templates**.
 
 This package is:
 
-* **Framework-agnostic** (no React)
-* **Storage-agnostic** (no DB assumptions)
-* **Runtime-safe** (Zod-based validation)
+* 🧠 **Framework-agnostic**
+* 🧩 **UI-agnostic**
+* 🔒 **Safe by design (Zod-based)**
+* 🧱 **The foundation of the FRT incident & reporting platform**
 
-It gives you:
-
-* A **typed schema** for report templates (templates → sections → fields)
-* **Zod-based validation** and parsing from unknown / JSON input
-* **Legacy schema migration** (flat `fields` → `sections`, old type names, etc.)
-* **Normalization** helpers to ensure safe IDs & consistent structure
-* **Field defaults** and **ID utilities** you can use to build your own UI
-* **Response validation** based on templates (`validateReportResponse`)
-* **Conditional logic** for fields (`visibleIf` / `requiredIf`)
-* **Template diffing** (`diffTemplates`) to compare template versions (including ordering)
-* **Type-level response inference** (`InferResponse`) for fully typed responses
-* **Field registry** (`FieldRegistry`) for custom / extensible field types
-* **JSON Schema export** (`exportJSONSchema`) for integration with OpenAPI / external validators
-
-It’s the core that powers a flexible incident/report builder, but it’s generic enough to be reused in any app.
+It contains **no React**, **no database code**, and **no styling**.  
+You can use it in **Node**, **Next.js**, **backend services**, or custom form engines.
 
 ---
 
-## Installation
+# ✨ Features
 
-```bash
-# npm
-npm install @frt-platform/report-core zod
+### 📄 Template Schema
 
-# yarn
-yarn add @frt-platform/report-core zod
+* Sections → fields
+* Field IDs, labels, descriptions, placeholders
+* Built-in field types:
 
-# pnpm
-pnpm add @frt-platform/report-core zod
-```
+  * `shortText`, `longText`
+  * `number`
+  * `date`
+  * `checkbox`
+  * `singleSelect`, `multiSelect`
+  * `repeatGroup` (nested fieldsets)
 
-`zod` is a peer dependency and is used for schema validation & parsing.
+### 🎛 Field Constraints
 
----
+* min/max length (`shortText`, `longText`)
+* min/max value (`number`)
+* min/max selections (`multiSelect`)
+* allowed options
+* checkbox required semantics
+* default values
 
-## Concepts
+### 🔀 Conditional Logic
 
-The core model looks like this:
+* `visibleIf`
+* `requiredIf`
+* Supports:
+  `equals`, `any`, `all`, `not`
+* Fully integrated into validation.
 
-* A **template** contains multiple **sections**
-* A **section** contains multiple **fields**
-* A **field** has a `type` (short text, long text, number, select, etc.) and optional constraints
-* Fields can have **conditional logic** (`visibleIf`, `requiredIf`)
+### 🔥 Validation Engine
 
-Supported field types:
+* Build response schema dynamically with conditions
+* DX helper: `buildResponseSchema(template)` (no response needed)
+* Throwing API: `validateReportResponse()`
+* Non-throwing API: `validateReportResponseDetailed()`
+* Rich `ResponseFieldError` objects with:
 
-```ts
-import { REPORT_TEMPLATE_FIELD_TYPES } from "@frt-platform/report-core";
-
-console.log(REPORT_TEMPLATE_FIELD_TYPES);
-// [
-//   "shortText",
-//   "longText",
-//   "number",
-//   "date",
-//   "checkbox",
-//   "singleSelect",
-//   "multiSelect",
-//   "repeatGroup", // reserved for repeating groups / fieldsets
-// ]
-```
+  * section title
+  * field label
+  * error code
+  * full message
+  * nested repeatGroup row context
 
-> `repeatGroup` is reserved for repeating fieldsets (e.g. multiple injured people); the core schema knows about it and provides defaults, and the full runtime semantics can be layered on top in your app/React package.
+### 🔄 Template Migration & Normalization
 
----
+* Legacy format migration (`fields → sections`)
+* Automatic ID normalization & uniqueness enforcement
+* Stable `"lowercase_with_underscores"`-style IDs
+* Fallback IDs for missing values: `section_1`, `field_1`, etc.
 
-## Quick Start
+### 🔍 Schema Diffing
 
-### 1. Define a template in JSON
+Detect:
 
-You can define templates statically or load them from DB / API:
+* Added / removed / reordered sections
+* Added / removed / reordered fields
+* Modified fields
+* Nested diffs inside repeat groups
 
-```ts
-import type { ReportTemplateSchema } from "@frt-platform/report-core";
+### 📦 JSON Schema Export
 
-const templateJson: ReportTemplateSchema = {
-  version: 1,
-  title: "Incident follow-up",
-  description: "Collect a quick summary after an incident has been resolved.",
-  sections: [
-    {
-      id: "section-overview",
-      title: "Incident overview",
-      fields: [
-        {
-          id: "summary",
-          type: "longText",
-          label: "What happened?",
-          required: true,
-          minLength: 10,
-        },
-        {
-          id: "status",
-          type: "singleSelect",
-          label: "Incident status",
-          required: true,
-          options: ["Pending review", "Resolved", "Escalated"],
-          defaultValue: "Resolved",
-        },
-      ],
-    },
-  ],
-};
-```
+* Export a template as a valid JSON Schema (2020-12 draft)
+* Includes vendor extensions:
 
-### 2. Validate and normalize the template
+  * `x-frt-visibleIf`
+  * `x-frt-requiredIf`
+  * `x-frt-minIf` / `x-frt-maxIf` for repeatGroup
+  * placeholders
+* Useful for OpenAPI, Postman, or other backend runtimes.
 
-Use the helpers to safely parse and normalize unknown input:
+### 🏗 Field Registry
 
-```ts
-import {
-  parseReportTemplateSchema,
-  normalizeReportTemplateSchema,
-} from "@frt-platform/report-core";
+Extend the system at runtime:
 
-const raw = /* from DB, file, API, etc. */ templateJson;
+* Add custom types (`richText`, `fileUpload`, etc.)
+* Override validation logic
+* Provide metadata for UI packages
+* Unknown/unregistered field types safely fall back to `z.any()` so they never break the core engine.
 
-// 1) parse + validate (throws on invalid input)
-const parsed = parseReportTemplateSchema(raw);
+### 🧬 Type Inference
 
-// 2) optional extra normalization step (IDs, trimming, de-duplication, etc.)
-const normalized = normalizeReportTemplateSchema(parsed);
+Get a fully typed response type from a template:
 
-console.log(normalized.sections[0].fields[0].id);
-// always a non-empty, safe identifier
-```
+```ts
+type MyResponse = InferResponse<typeof template>;
+````
 
-### 3. Serialize for storage
+### 🧾 Serialization Helpers
 
-```ts
-import { serializeReportTemplateSchema } from "@frt-platform/report-core";
+Deterministic JSON output with sorting options:
 
-const jsonString = serializeReportTemplateSchema(normalized);
-// ready to store in DB, file, etc.
+```ts
+serializeReportTemplateSchema(template, {
+  pretty: true,
+  sortSectionsById: true,
+  sortFieldsById: true,
+});
 ```
 
----
-
-## Parsing from a JSON string
+Perfect for Git diffs and storage.
 
-If you have a JSON string (e.g. from a form textarea):
+---
 
-```ts
-import { parseReportTemplateSchemaFromString } from "@frt-platform/report-core";
+# 📦 Installation
 
-try {
-  const template = parseReportTemplateSchemaFromString(userInputString);
-  // valid template here
-} catch (err) {
-  // invalid JSON or schema – show error to user
-}
+```bash
+npm install @frt-platform/report-core zod
 ```
 
----
+`zod` is a peer dependency.
 
-## Validating report responses
+---
 
-Once you have a template, you can validate **user-submitted responses** against it.
+# 🧹 Parsing & Normalization
 
-### Runtime validation
+The core exposes helpers for safely **parsing**, **migrating**, and **normalizing** templates.
 
 ```ts
-import { validateReportResponse } from "@frt-platform/report-core";
-
-const template = /* a valid ReportTemplateSchema */ normalized;
+import {
+  parseReportTemplateSchema,
+  parseReportTemplateSchemaFromString,
+} from "@frt-platform/report-core";
 
-const responseData = {
-  summary: "Student slipped in the hallway, no serious injuries.",
-  status: "Resolved",
-};
+// From a raw JS object (e.g. loaded from DB, file, etc.)
+const template = parseReportTemplateSchema(rawTemplateObject);
 
-// Validate (throws ZodError on failure)
-const safeResponse = validateReportResponse(template, responseData);
+// From a JSON string
+const templateFromString = parseReportTemplateSchemaFromString(jsonString);
 ```
 
-`validateReportResponse` respects:
+Under the hood, `parseReportTemplateSchema` does:
 
-* `required` flags
-* `minLength` / `maxLength` (short/long text)
-* `minValue` / `maxValue` (numbers)
-* `minSelections` / `maxSelections` (multiSelect)
-* `options` (singleSelect + multiSelect)
-* `checkbox` semantics (required checkbox must be `true`)
-* **Conditional logic**:
+1. **Legacy migration**
 
-  * `visibleIf`: if false, the field is treated as invisible and removed from the parsed output
-  * `requiredIf`: if true, the field is treated as required for this specific response
+   * Accepts both the new `{ sections: [...] }` format and legacy flat:
 
-You can still build a raw schema yourself using the conditional builder:
+     ```ts
+     {
+       version: 1,
+       fields: [ /* ... */ ]
+     }
+     ```
 
-```ts
-import { buildResponseSchemaWithConditions } from "@frt-platform/report-core";
+   * Legacy `fields` are automatically wrapped into a single `section_1`.
 
-const responseSchema = buildResponseSchemaWithConditions(template, responseData);
-const safeResponse = responseSchema.parse(responseData);
-```
+2. **Schema validation**
 
----
+   * Uses a Zod validator for `ReportTemplateSchema` to ensure the template is structurally valid.
 
-## Conditional logic (`visibleIf` / `requiredIf`)
+3. **Normalization**
 
-Fields can declare conditions that refer to other field values.
+   * Section and field IDs are normalized to **lowercase** with spaces → underscores:
 
-Example:
+     * `"My Field!"` → `"my_field"`
 
-```json
-{
-  "id": "injury_details",
-  "type": "longText",
-  "label": "Describe the injury",
-  "visibleIf": { "equals": { "injured": true } },
-  "requiredIf": { "equals": { "severity": "High" } }
-}
-```
+   * Invalid characters are stripped (only `[a-z0-9_-]` are kept).
 
-Supported condition shapes:
+   * IDs are made **unique per namespace** by appending `-1`, `-2`, … as needed:
 
-* `{"equals": { "fieldId": value } }`
-* `{"any": [cond1, cond2, ...] }`
-* `{"all": [cond1, cond2, ...] }`
-* `{"not": cond }`
+     * `my_field`, `my_field-1`, `my_field-2`, …
 
-At runtime:
+   * Missing IDs get deterministic fallbacks:
 
-* If `visibleIf` is **false** → field is treated as **invisible**, becomes optional, and is stripped from the validated response.
-* If `requiredIf` is **true** → field is treated as **required** for that specific response.
+     * Sections: `section_1`, `section_2`, …
+     * Fields: `field_1`, `field_2`, …
+
+This makes templates safe to store, diff, and round-trip in a stable way.
 
 ---
 
-## Type-level response inference (`InferResponse`)
+# 🚀 Quickstart
 
-If you define templates statically (`as const`), you can get a fully-typed response type from the template:
+## 1. Define a template
 
 ```ts
-import type { InferResponse } from "@frt-platform/report-core";
+import type { ReportTemplateSchema } from "@frt-platform/report-core";
 
-const incidentTemplate = {
+const template: ReportTemplateSchema = {
   version: 1,
   sections: [
     {
-      id: "section-overview",
+      id: "general",
+      title: "General Info",
       fields: [
         {
-          id: "summary",
-          type: "longText",
-          label: "What happened?",
+          id: "title",
+          type: "shortText",
+          label: "Incident title",
           required: true,
-          minLength: 10,
         },
         {
-          id: "status",
+          id: "severity",
           type: "singleSelect",
-          label: "Status",
+          label: "Severity",
           required: true,
-          options: ["Pending", "Resolved", "Escalated"] as const,
-        },
-        {
-          id: "follow_up_date",
-          type: "date",
-          label: "Follow-up date",
+          options: ["Low", "Medium", "High"],
         },
         {
-          id: "tags",
-          type: "multiSelect",
-          label: "Tags",
-          options: ["Safety", "Medical", "Security"] as const,
-        },
-        {
-          id: "confirmed",
-          type: "checkbox",
-          label: "I confirm this report is accurate",
-          required: true,
+          id: "details",
+          type: "longText",
+          label: "Details",
+          minLength: 10,
         },
       ],
     },
   ],
-} as const;
-
-type IncidentResponse = InferResponse<typeof incidentTemplate>;
-```
-
-`IncidentResponse` will be inferred as:
-
-```ts
-type IncidentResponse = {
-  summary: string; // required
-  status: "Pending" | "Resolved" | "Escalated"; // required
-  follow_up_date?: string; // optional
-  tags?: ("Safety" | "Medical" | "Security")[]; // optional
-  confirmed: boolean; // required checkbox
 };
 ```
 
-This is extremely useful for:
-
-* API handlers (`(body: IncidentResponse) => { ... }`)
-* DB layers that store `data` blobs
-* Frontend forms with type-safe state
-
 ---
 
-## Using field defaults
-
-The package includes core defaults for each field type (no UI, no icons):
+## 2. Validate a response (throwing API)
 
 ```ts
-import {
-  CORE_FIELD_DEFAULTS,
-  DEFAULT_FIELD_LABEL,
-  type ReportTemplateFieldType,
-} from "@frt-platform/report-core";
-
-function createDefaultField(type: ReportTemplateFieldType) {
-  const defaults = CORE_FIELD_DEFAULTS[type] ?? {};
-  return {
-    id: "your-id-here",
-    type,
-    label: (defaults.label as string) ?? DEFAULT_FIELD_LABEL,
-    ...defaults,
-  };
-}
+import { validateReportResponse } from "@frt-platform/report-core";
 
-const field = createDefaultField("shortText");
+const parsed = validateReportResponse(template, {
+  title: "Broken fire alarm",
+  severity: "High",
+  details: "Triggered after smoke test",
+});
 ```
 
-`CORE_FIELD_DEFAULTS` includes basic defaults for:
-
-* `shortText`, `longText`, `number`, `date`, `checkbox`, `singleSelect`, `multiSelect`
-* `repeatGroup` (with an empty `fields` array; your builder populates nested fields)
-
-This is especially useful in a form builder UI when the user adds a new field of a given type.
+If invalid → throws a ZodError.
 
 ---
 
-## Field Registry (`FieldRegistry`)
-
-You can register **custom field types** or override core types at runtime:
+## 3. Validate without throwing (UI-friendly)
 
 ```ts
-import { FieldRegistry } from "@frt-platform/report-core";
-import { z } from "zod";
-
-// Simple example: a "richText" field that behaves like a string
-FieldRegistry.register("richText", {
-  defaults: {
-    label: "Details",
-    placeholder: "Write here...",
-  },
-  buildResponseSchema: (field) => {
-    let schema = z.string();
+import { validateReportResponseDetailed } from "@frt-platform/report-core";
 
-    if (typeof field.minLength === "number") {
-      schema = schema.min(field.minLength);
-    }
-    if (typeof field.maxLength === "number") {
-      schema = schema.max(field.maxLength);
-    }
-
-    return field.required ? schema : schema.optional();
-  },
+const result = validateReportResponseDetailed(template, {
+  title: "",
+  severity: "High",
 });
-```
 
-At validation time, `validateReportResponse` and `buildBaseFieldSchema` will:
-
-1. Check the registry for a custom handler.
-2. Use the built-in fallback if none is registered.
+if (!result.success) {
+  console.log(result.errors);
+}
+```
 
-Use this for:
+Produces:
 
-* App-specific field types (e.g. `fileUpload`, `signature`, `mapLocation`)
-* Tenant-specific extensions in a multi-tenant platform
-* Gradually introducing new field behaviors without changing the core package
+```ts
+[
+  {
+    fieldId: "title",
+    sectionId: "general",
+    sectionTitle: "General Info",
+    label: "Incident title",
+    code: "field.too_small",
+    message:
+      'Section "General Info" → Field "Incident title": String must contain at least 1 character(s).'
+  }
+]
+```
 
 ---
 
-## Generating unique IDs
-
-The core package exposes a generic `createUniqueId` helper:
+# 🔀 Conditional Logic Example
 
 ```ts
-import { createUniqueId } from "@frt-platform/report-core";
-
-const existingSectionIds = ["section-1", "section-2"];
-const newId = createUniqueId("section", existingSectionIds);
-// "section-3" (or the next available)
+{
+  id: "follow_up_notes",
+  type: "longText",
+  label: "Follow-up notes",
+  visibleIf: { equals: { follow_up_required: true } },
+  requiredIf: { equals: { follow_up_required: true } },
+}
 ```
 
-You can use this for both section and field IDs when building templates dynamically.
-
----
-
-## Legacy schema migration
+Behavior:
 
-If you had older templates that:
+* If `follow_up_required = false` → field is **hidden** and **ignored**
+* If `true` → field becomes **required**
 
-* Used a flat `fields` array instead of `sections`, or
-* Used older field type names (`text`, `textarea`, `dropdown`, `multiselect`, …)
+---
 
-you can pass them through the migration pipeline:
+# 🔁 Repeat Group Example
 
 ```ts
-import {
-  migrateLegacySchema,
-  parseReportTemplateSchema,
-} from "@frt-platform/report-core";
-
-const legacy = {
-  title: "Old template",
-  description: "Using flat fields",
+{
+  id: "injured",
+  type: "repeatGroup",
+  label: "Injured people",
+  min: 1,
+  max: 5,
   fields: [
-    { id: "summary", type: "textarea", label: "Summary" },
-    { id: "status", type: "dropdown", label: "Status", options: ["Open", "Closed"] },
-  ],
-};
-
-const migrated = migrateLegacySchema(legacy);
-const parsed = parseReportTemplateSchema(migrated);
-
-console.log(parsed.sections.length); // 1
-console.log(parsed.sections[0].fields[0].type); // "longText"
+    { id: "name", type: "shortText", label: "Name", required: true },
+    { id: "injury", type: "longText", label: "Injury description" }
+  ]
+}
 ```
 
-You don’t normally need to call `migrateLegacySchema` yourself – `parseReportTemplateSchema` already does:
+Response shape:
 
 ```ts
-// internally:
-const migrated = migrateLegacySchema(raw);
-const parsed = ReportTemplateSchemaValidator.parse(migrated);
+injured: Array<{ name: string; injury?: string }>;
 ```
 
----
+### 📝 repeatGroup behavior & limitations
 
-## Diffing templates
+* **Base constraints**
 
-When you version templates (e.g. editing in a UI), you might want to see what changed between versions. The core exposes a diff utility:
+  * `min` / `max` are always enforced on the row array.
+  * Each row is an object keyed by nested field IDs.
 
-```ts
-import { diffTemplates } from "@frt-platform/report-core";
+* **Conditional `minIf` / `maxIf`**
 
-const beforeTemplate = /* old template */;
-const afterTemplate = /* updated template */;
+  * If `minIf` / `maxIf` are present, they are evaluated against the **current response**.
+  * When the condition is `true`, the conditional value overrides the static `min` / `max` for that validation pass.
+  * When the condition is `false`, the engine falls back to the static `min` / `max` (if any).
 
-const diff = diffTemplates(beforeTemplate, afterTemplate);
+* **Conditional logic inside rows**
 
-console.log(diff.addedSections);
-console.log(diff.removedSections);
-console.log(diff.reorderedSections);
-console.log(diff.modifiedSections);
+  * Nested fields in a repeatGroup support the same `visibleIf` / `requiredIf` semantics as top-level fields.
+  * Hidden nested fields are treated as **optional** and are **stripped** from the parsed response, just like hidden top-level fields.
+  * For now, row-level conditions see the **full response object**, not just the row. This matches top-level behavior and keeps the logic model simple.
 
-console.log(diff.addedFields);
-console.log(diff.removedFields);
-console.log(diff.reorderedFields);
-console.log(diff.modifiedFields);
-```
+* **JSON Schema export**
 
-`diff.modifiedFields` contains entries like:
-
-```ts
-{
-  sectionId: "section-overview",
-  fieldId: "summary",
-  before: { label: "What happened?", required: false, ... },
-  after: { label: "What happened exactly?", required: true, ... },
-  changes: [
-    { key: "label", before: "What happened?", after: "What happened exactly?" },
-    { key: "required", before: false, after: true },
-  ],
-}
-```
-
-Use this for:
-
-* “Changes” tabs in your UI
-* Migration & compatibility warnings
-* Audit trails
-* Showing ordered changes (section/field reorder is explicitly tracked)
+  * repeatGroup constraints and conditions are exported via `x-frt-*` vendor extensions (e.g. `x-frt-minIf`, `x-frt-maxIf`, `x-frt-visibleIf`, `x-frt-requiredIf`), so you can mirror this behavior in other runtimes.
 
 ---
 
-## JSON Schema export
-
-You can export a template as a **JSON Schema** object for use with OpenAPI, Swagger, Postman, or other runtimes that don’t speak TypeScript/Zod.
+# 🧩 Field Registry (Custom Types)
 
 ```ts
-import { exportJSONSchema } from "@frt-platform/report-core";
+import { FieldRegistry } from "@frt-platform/report-core";
+import { z } from "zod";
 
-const jsonSchema = exportJSONSchema(template);
+FieldRegistry.register("richText", {
+  defaults: { label: "Details" },
+  buildResponseSchema(field) {
+    let schema = z.string();
+    if (field.minLength) schema = schema.min(field.minLength);
+    return field.required ? schema : schema.optional();
+  },
+});
 ```
 
-Shape (simplified):
+Now templates may include fields like:
 
-```json
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "summary": { "type": "string", "minLength": 10 },
-    "status": { "type": "string", "enum": ["Pending", "Resolved", "Escalated"] }
-  },
-  "required": ["summary", "status"],
-  "additionalProperties": false,
-  "x-frt-templateTitle": "Incident follow-up",
-  "x-frt-version": 1
-}
+```ts
+{ id: "body", type: "richText", label: "Report body" }
 ```
 
-Key points:
-
-* String/number/boolean/array mapping matches the runtime validation semantics.
-* `required` only includes **unconditionally required** fields (no `visibleIf` / `requiredIf`), but we expose conditional logic as vendor extensions.
-* Extra metadata is available under `x-frt-*` keys, e.g. `x-frt-placeholder`, `x-frt-dataClassification`, `x-frt-visibleIf`, `x-frt-requiredIf`.
+If a template uses a field type that is **not** registered and not one of the built-in core types, the engine safely falls back to `z.any()` so unknown types never crash validation.
 
 ---
 
-## API Overview
-
-### Types
+# 🧾 JSON Schema Export
 
 ```ts
-import type {
-  ReportTemplateSchema,
-  ReportTemplateSection,
-  ReportTemplateField,
-  ReportTemplateFieldType,
-  InferResponse,
-} from "@frt-platform/report-core";
-```
-
-* `ReportTemplateFieldType` – union of all field type strings
-* `ReportTemplateField` – one question/field in a section
-* `ReportTemplateSection` – a logical grouping of fields
-* `ReportTemplateSchema` – full template
-* `InferResponse<TTemplate>` – builds a typed response object from a static template
-
-### Constants
+import { exportJSONSchema } from "@frt-platform/report-core";
 
-```ts
-import {
-  REPORT_TEMPLATE_VERSION,
-  REPORT_TEMPLATE_FIELD_TYPES,
-  DEFAULT_FIELD_LABEL,
-  CORE_FIELD_DEFAULTS,
-} from "@frt-platform/report-core";
+const jsonSchema = exportJSONSchema(template);
 ```
 
-* `REPORT_TEMPLATE_VERSION: number`
-* `REPORT_TEMPLATE_FIELD_TYPES: readonly ReportTemplateFieldType[]`
-* `DEFAULT_FIELD_LABEL: string`
-* `CORE_FIELD_DEFAULTS: Record<ReportTemplateFieldType, Record<string, unknown>>`
+Produces JSON Schema with:
 
-### Validation & parsing
+* field types
+* enums
+* min/max constraints
+* default values
+* conditional logic preserved as custom `x-frt-*` properties
 
-```ts
-import {
-  ReportTemplateFieldSchema,
-  ReportTemplateSectionSchema,
-  ReportTemplateSchemaValidator,
-  parseReportTemplateSchema,
-  parseReportTemplateSchemaFromString,
-  normalizeReportTemplateSchema,
-  serializeReportTemplateSchema,
-} from "@frt-platform/report-core";
-```
+---
 
-Use the Zod schemas directly if you want:
+# 🔍 Diff Templates
 
 ```ts
-import { ReportTemplateSchemaValidator } from "@frt-platform/report-core";
+import { diffTemplates } from "@frt-platform/report-core";
 
-const result = ReportTemplateSchemaValidator.safeParse(raw);
-if (!result.success) {
-  // handle validation errors
-}
+const diff = diffTemplates(oldTemplate, newTemplate);
 ```
 
-### Migration
+Detects:
 
-```ts
-import { migrateLegacySchema } from "@frt-platform/report-core";
-```
+* added/removed/reordered sections
+* added/removed/reordered fields
+* modified fields
+* nested diffs for repeat groups
 
-Takes `unknown` legacy input and returns a shape better suited for current schema validation.
+Perfect for:
 
-### Response validation
+* Version history
+* Audit logs
+* Template editing UI
 
-```ts
-import {
-  validateReportResponse,
-  buildResponseSchemaWithConditions,
-  type InferResponse,
-} from "@frt-platform/report-core";
-```
+---
+
+# 🧬 Type Inference
 
-### Template diffing
+Given a template:
 
 ```ts
-import { diffTemplates } from "@frt-platform/report-core";
+export const myTemplate = {
+  version: 1,
+  sections: [
+    {
+      id: "s",
+      fields: [
+        { id: "title", type: "shortText", required: true },
+        { id: "tags", type: "multiSelect", options: ["A", "B"] },
+      ]
+    }
+  ]
+} as const;
 ```
 
-### JSON Schema export
+Infer response type:
 
 ```ts
-import { exportJSONSchema } from "@frt-platform/report-core";
+type MyResponse = InferResponse<typeof myTemplate>;
 ```
 
-### Field registry
+Produces:
 
 ```ts
-import { FieldRegistry } from "@frt-platform/report-core";
+type MyResponse = {
+  title: string;
+  tags?: ("A" | "B")[];
+};
 ```
 
 ---
 
-## Integration Ideas
-
-This package is intentionally minimal. You can layer it into:
+# 🧾 Serialization
 
-* **Next.js / React** apps for:
-
-  * Template builders
-  * Dynamic report forms
-  * Admin panels for managing report templates
-* **Node/Edge backends** for:
-
-  * Validating templates on save
-  * Migrating old template shapes
-  * Ensuring consistent data before persisting to a DB
-  * Validating report responses before saving them
-  * Serving JSON Schema to other services
-
-Typical pattern in a full stack app:
-
-1. **Frontend**
-
-   * Build a visual editor for templates
-   * Send template JSON to server
-
-2. **Backend**
+```ts
+import { serializeReportTemplateSchema } from "@frt-platform/report-core";
 
-   * `parseReportTemplateSchema` to validate templates
-   * Store `ReportTemplateSchema` JSON in your DB (e.g. Mongo via Prisma)
-   * On response submission:
+const json = serializeReportTemplateSchema(template, {
+  pretty: true,
+  sortSectionsById: true,
+  sortFieldsById: true,
+});
+```
 
-     * Load template from DB
-     * `validateReportResponse(template, data)` before insert
+Useful for deterministic output in Git and stable diffs across environments.
 
-3. **Runtime**
+---
 
-   * Load templates from DB
-   * Use them to render dynamic forms
-   * Use `validateReportResponse` / `buildResponseSchemaWithConditions` to validate and normalize responses
-   * Use `exportJSONSchema` for interoperability with other stacks
+# 🧱 Roadmap
 
----
+### Phase 1 — Core Maturation (✔️ COMPLETE)
 
-## Roadmap / Extensions (ideas)
+* Validation
+* Conditional logic
+* Diffing
+* Field Registry
+* Error helpers
+* Serialization features
+* Parsing & normalization helpers
 
-Things you might add on top (in a separate package, e.g. `@frt-platform/report-react`):
+### Phase 2 — Advanced Field System (IN PROGRESS)
 
-* React components for:
+* Richer repeatGroup UX
+* Computed fields (design)
+* RichText / FileUpload via registry
 
-  * Template builder UI
-  * Field editors/renderers (short text, selects, etc.)
-  * Auto-generated `<ReportForm />` that consumes a template
-* More advanced field types:
+### Phase 3 — Reactions & Analytics (Planned)
 
-  * File uploads
-  * Signature pads
-  * Matrix / grid fields
-  * Fully-featured `repeatGroup` UI & runtime
-* Richer conditional logic:
+* Scoring rules
+* Auto-tagging
+* Suggested outcomes
 
-  * `visibleIf`
-  * `requiredIf`
-  * multi-step branching
-* Multi-language labels & descriptions
+### Phase 4 — React UI Package (Planned)
 
-The core stays simple: **schema + validation + conditional logic + migration + diffing + registry + JSON Schema export**.
+* Form renderer
+* Template builder
+* Field palette
+* Full ShadCN integration
 
 ---
 
-## License
+# 📄 License
 
-MIT – use it in your projects, commercial or not. Contributions welcome.
+MIT — feel free to use, extend, or contribute.