@yrest/cli 0.9.0 → 0.11.0

package/dist/cli/index.mjs

@@ -97,11 +97,11 @@ _rel:
     userId: users
     # many2many \u2014 posts can have multiple tags via the post_tags pivot
     tags:
-      type: many2many
-      target: tags
-      through: post_tags
-      foreignKey: postId
-      otherKey: tagId
+      _type: many2many
+      _target: tags
+      _through: post_tags
+      _foreignKey: postId
+      _otherKey: tagId
   comments:
     postId: posts
     userId: users
@@ -109,8 +109,8 @@ _rel:
   # one2one \u2014 each user has exactly one profile
   profiles:
     userId:
-      type: one2one
-      target: users
+      _type: one2one
+      _target: users
 
 users:
   - id: 1
@@ -259,52 +259,52 @@ _rel:
   # many2many \u2014 products belong to multiple categories via pivot
   products:
     categories:
-      type: many2many
-      target: categories
-      through: product_categories
-      foreignKey: productId
-      otherKey: categoryId
+      _type: many2many
+      _target: categories
+      _through: product_categories
+      _foreignKey: productId
+      _otherKey: categoryId
 
 _routes:
   # Login with conditional scenarios
-  - method: POST
-    path: /auth/login
-    scenarios:
-      - when:
+  - _method: POST
+    _path: /auth/login
+    _scenarios:
+      - _when:
           body.email: admin@example.com
           body.password: secret
-        response:
-          status: 200
-          body:
+        _response:
+          _status: 200
+          _body:
             token: tok-admin-abc123
             role: admin
             userId: 1
-      - when:
+      - _when:
           body.email: user@example.com
           body.password: secret
-        response:
-          status: 200
-          body:
+        _response:
+          _status: 200
+          _body:
             token: tok-user-xyz789
             role: user
             userId: 2
-    otherwise:
-      status: 401
-      body:
+    _otherwise:
+      _status: 401
+      _body:
         error: Invalid credentials
 
   # Logout \u2014 always 204
-  - method: POST
-    path: /auth/logout
-    response:
-      status: 204
+  - _method: POST
+    _path: /auth/logout
+    _response:
+      _status: 204
 
   # Static featured products list
-  - method: GET
-    path: /store/featured
-    response:
-      status: 200
-      body:
+  - _method: GET
+    _path: /store/featured
+    _response:
+      _status: 200
+      _body:
         - id: 1
           name: Laptop Pro 15
           price: 1299.99
@@ -319,31 +319,31 @@ _routes:
           badge: On Sale
 
   # Template variables \u2014 echoes the requested product id
-  - method: GET
-    path: /products/:id/summary
-    response:
-      status: 200
-      body:
+  - _method: GET
+    _path: /products/:id/summary
+    _response:
+      _status: 200
+      _body:
         productId: "{{params.id}}"
         requestedAt: "{{now}}"
         source: mock
 
   # Cancel order with simulated latency and template vars
-  - method: POST
-    path: /orders/:id/cancel
-    delay: 500
-    response:
-      status: 200
-      body:
+  - _method: POST
+    _path: /orders/:id/cancel
+    _delay: 500
+    _response:
+      _status: 200
+      _body:
         orderId: "{{params.id}}"
         status: cancelled
         cancelledAt: "{{now}}"
 
   # Simulate a service outage for testing error handling
-  - method: GET
-    path: /store/inventory/sync
-    error: 503
-    errorBody:
+  - _method: GET
+    _path: /store/inventory/sync
+    _error: 503
+    _errorBody:
       message: Inventory service temporarily unavailable
       retryAfter: 30
 
@@ -538,33 +538,173 @@ function parseRelations(raw) {
 }
 function normaliseRelationDef(key, value) {
   if (typeof value === "string") {
-    return { type: "many2one", target: value };
+    return value.includes(":") ? parseDslString(value) : { type: "many2one", target: value };
   }
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const v = value;
-  const type = v["type"];
-  const nested = v["nested"] === true ? true : void 0;
+  const type = v["_type"];
+  const nested = v["_nested"] === true ? true : void 0;
+  const carDirect = typeof v["_car-direct"] === "string" ? v["_car-direct"] : void 0;
+  const carInverse = typeof v["_car-inverse"] === "string" ? v["_car-inverse"] : void 0;
   if (type === "many2one" || type === void 0) {
-    const target = v["target"];
+    const target = v["_target"];
     if (typeof target !== "string") return null;
-    return nested ? { type: "many2one", target, nested } : { type: "many2one", target };
+    const foreignKey = typeof v["_foreignKey"] === "string" ? v["_foreignKey"] : void 0;
+    return compact({ type: "many2one", target, foreignKey, nested, carDirect, carInverse });
   }
   if (type === "one2one") {
-    const target = v["target"];
+    const target = v["_target"];
     if (typeof target !== "string") return null;
-    return nested ? { type: "one2one", target, nested } : { type: "one2one", target };
+    const foreignKey = typeof v["_foreignKey"] === "string" ? v["_foreignKey"] : void 0;
+    return compact({ type: "one2one", target, foreignKey, nested, carDirect, carInverse });
   }
   if (type === "many2many") {
-    const target = typeof v["target"] === "string" ? v["target"] : key;
-    const through = v["through"];
-    const foreignKey = v["foreignKey"];
-    const otherKey = v["otherKey"];
+    const target = typeof v["_target"] === "string" ? v["_target"] : key;
+    const through = v["_through"];
+    const foreignKey = v["_foreignKey"];
+    const otherKey = v["_otherKey"];
     if (typeof through !== "string" || typeof foreignKey !== "string" || typeof otherKey !== "string")
       return null;
-    return nested ? { type: "many2many", target, through, foreignKey, otherKey, nested } : { type: "many2many", target, through, foreignKey, otherKey };
+    return compact({
+      type: "many2many",
+      target,
+      through,
+      foreignKey,
+      otherKey,
+      nested,
+      carDirect,
+      carInverse
+    });
   }
   return null;
 }
+var TYPE_ALIASES = {
+  many2one: "many2one",
+  m2o: "many2one",
+  one2one: "one2one",
+  o2o: "one2one",
+  many2many: "many2many",
+  m2m: "many2many"
+};
+function parseDslString(raw) {
+  const nested = raw.endsWith("+nested") ? true : void 0;
+  let s = nested ? raw.slice(0, -7) : raw;
+  let carDirect;
+  let carInverse;
+  const carMatch = s.match(/\[([^[\]]+)->([^[\]]+)\]$/);
+  if (carMatch) {
+    carDirect = carMatch[1];
+    carInverse = carMatch[2];
+    s = s.slice(0, s.length - carMatch[0].length);
+  }
+  const colonIdx = s.indexOf(":");
+  if (colonIdx === -1) return null;
+  const typeAlias = s.slice(0, colonIdx);
+  const body = s.slice(colonIdx + 1);
+  const type = TYPE_ALIASES[typeAlias];
+  if (!type) return null;
+  if (type === "many2many") {
+    const m = body.match(/^([^@()[\]]+)@([^@()[\]]+)\(([^,)]+),\s*([^,)]+)\)$/);
+    if (!m) return null;
+    const [, target2, through, foreignKey2, otherKey] = m;
+    return compact({
+      type: "many2many",
+      target: target2,
+      through,
+      foreignKey: foreignKey2,
+      otherKey,
+      nested,
+      carDirect,
+      carInverse
+    });
+  }
+  const atIdx = body.indexOf("@");
+  const target = atIdx === -1 ? body : body.slice(0, atIdx);
+  const foreignKey = atIdx === -1 ? void 0 : body.slice(atIdx + 1);
+  if (!target) return null;
+  return compact({ type, target, foreignKey, nested, carDirect, carInverse });
+}
+function compact(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
+}
+
+// src/storage/parseRoutes.ts
+function parseRoutes(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw.map(normaliseRoute).filter((r) => r !== null);
+}
+function normaliseRoute(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const v = raw;
+  const method = v["_method"];
+  const path = v["_path"];
+  if (typeof method !== "string" || typeof path !== "string") return null;
+  const route = { method, path };
+  if (typeof v["_handler"] === "string") route.handler = v["_handler"];
+  if (typeof v["_delay"] === "number") route.delay = v["_delay"];
+  if (typeof v["_error"] === "number") route.error = v["_error"];
+  if (v["_errorBody"] !== void 0) route.errorBody = v["_errorBody"];
+  const response = normaliseResponse(v["_response"]);
+  if (response) route.response = response;
+  const otherwise = normaliseResponse(v["_otherwise"]);
+  if (otherwise) route.otherwise = otherwise;
+  const scenarios = normaliseScenarios(v["_scenarios"]);
+  if (scenarios.length > 0) route.scenarios = scenarios;
+  return route;
+}
+function normaliseResponse(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const v = raw;
+  const response = {};
+  if (typeof v["_status"] === "number") response.status = v["_status"];
+  if (v["_body"] !== void 0) response.body = v["_body"];
+  if (v["_headers"] && typeof v["_headers"] === "object" && !Array.isArray(v["_headers"]))
+    response.headers = v["_headers"];
+  return Object.keys(response).length > 0 ? response : void 0;
+}
+function normaliseScenarios(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw.map(normaliseScenario).filter((s) => s !== null);
+}
+function normaliseScenario(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const v = raw;
+  const when = v["_when"];
+  if (!when || typeof when !== "object") return null;
+  const response = normaliseResponse(v["_response"]);
+  if (!response) return null;
+  return { when, response };
+}
+
+// src/storage/parseSchema.ts
+function parseSchema(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const result = {};
+  for (const [collection, fields] of Object.entries(raw)) {
+    if (!fields || typeof fields !== "object" || Array.isArray(fields)) continue;
+    result[collection] = {};
+    for (const [field, value] of Object.entries(fields)) {
+      const def = normaliseFieldDef(value);
+      if (def) result[collection][field] = def;
+    }
+  }
+  return result;
+}
+function normaliseFieldDef(value) {
+  if (value === "required") return { required: true };
+  if (value === "optional") return { required: false };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const v = value;
+  const def = {};
+  if (v["_required"] === true || v["_required"] === false) def.required = v["_required"];
+  if (typeof v["_type"] === "string" && ["string", "integer", "number", "boolean", "object", "array"].includes(v["_type"]))
+    def.type = v["_type"];
+  if (typeof v["_format"] === "string") def.format = v["_format"];
+  if (Array.isArray(v["_enum"])) def.enum = v["_enum"];
+  if (typeof v["_description"] === "string") def.description = v["_description"];
+  if (v["_default"] !== void 0) def.default = v["_default"];
+  return def;
+}
 
 // src/utils/deepCopy.ts
 function deepCopyData(source) {
@@ -574,13 +714,69 @@ function deepCopyData(source) {
 }
 
 // src/storage/yrestStorage.ts
+function serializeRelations(relations) {
+  const out = {};
+  for (const [col, fields] of Object.entries(relations)) {
+    out[col] = {};
+    for (const [key, def] of Object.entries(fields)) {
+      out[col][key] = serializeRelationDef(def);
+    }
+  }
+  return out;
+}
+function serializeRelationDef(def) {
+  if (def.type === "many2many") {
+    const entry2 = {
+      _type: def.type,
+      _target: def.target,
+      _through: def.through,
+      _foreignKey: def.foreignKey,
+      _otherKey: def.otherKey
+    };
+    if (def.nested) entry2._nested = true;
+    if (def.carDirect) entry2["_car-direct"] = def.carDirect;
+    if (def.carInverse) entry2["_car-inverse"] = def.carInverse;
+    return entry2;
+  }
+  const entry = { _type: def.type, _target: def.target };
+  if (def.foreignKey) entry._foreignKey = def.foreignKey;
+  if (def.nested) entry._nested = true;
+  if (def.carDirect) entry["_car-direct"] = def.carDirect;
+  if (def.carInverse) entry["_car-inverse"] = def.carInverse;
+  return entry;
+}
+function serializeRoutes(routes) {
+  return routes.map((r) => {
+    const entry = { _method: r.method, _path: r.path };
+    if (r.handler) entry._handler = r.handler;
+    if (r.delay !== void 0) entry._delay = r.delay;
+    if (r.error !== void 0) entry._error = r.error;
+    if (r.errorBody !== void 0) entry._errorBody = r.errorBody;
+    if (r.response) entry._response = serializeResponse(r.response);
+    if (r.otherwise) entry._otherwise = serializeResponse(r.otherwise);
+    if (r.scenarios?.length) entry._scenarios = r.scenarios.map(serializeScenario);
+    return entry;
+  });
+}
+function serializeResponse(res) {
+  const out = {};
+  if (res.status !== void 0) out._status = res.status;
+  if (res.body !== void 0) out._body = res.body;
+  if (res.headers) out._headers = res.headers;
+  return out;
+}
+function serializeScenario(s) {
+  return { _when: s.when, _response: serializeResponse(s.response) };
+}
 function createYrestStorage(filePath) {
   const absPath = resolve2(filePath);
   const raw = parse(readFileSync(absPath, "utf8")) ?? {};
+  const RESERVED = /* @__PURE__ */ new Set(["_rel", "_routes", "_schema"]);
   const relations = parseRelations(raw["_rel"]);
-  const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
+  const routes = parseRoutes(raw["_routes"]);
+  const schema = parseSchema(raw["_schema"]);
   const data = Object.fromEntries(
-    Object.entries(raw).filter(([key]) => key !== "_rel" && key !== "_routes")
+    Object.entries(raw).filter(([key]) => !RESERVED.has(key))
   );
   let snapshot = {
     data: deepCopyData(data),
@@ -594,6 +790,9 @@ function createYrestStorage(filePath) {
     getRelations() {
       return relations;
     },
+    getSchema() {
+      return schema;
+    },
     getRoutes() {
       return routes;
     },
@@ -605,8 +804,8 @@ function createYrestStorage(filePath) {
     },
     persist() {
       const payload = {};
-      if (Object.keys(relations).length > 0) payload._rel = relations;
-      if (routes.length > 0) payload._routes = routes;
+      if (Object.keys(relations).length > 0) payload._rel = serializeRelations(relations);
+      if (routes.length > 0) payload._routes = serializeRoutes(routes);
       Object.assign(payload, data);
       const tmp = resolve2(dirname(absPath), `.yrest-${randomUUID()}.tmp`);
       writeFileSync2(tmp, stringify(payload), "utf8");
@@ -616,7 +815,7 @@ function createYrestStorage(filePath) {
       const fresh = parse(readFileSync(absPath, "utf8")) ?? {};
       const freshRelations = parseRelations(fresh["_rel"]);
       const freshData = Object.fromEntries(
-        Object.entries(fresh).filter(([key]) => key !== "_rel" && key !== "_routes")
+        Object.entries(fresh).filter(([key]) => !RESERVED.has(key))
       );
       for (const key of Object.keys(data)) delete data[key];
       Object.assign(data, freshData);
@@ -728,7 +927,7 @@ function endpointRow(method, path, desc) {
 }
 function resourceAccordion(name, base, isOpen) {
   const p = `${base}/${name}`;
-  const singular = name.endsWith("s") ? name.slice(0, -1) : name;
+  const singular2 = name.endsWith("s") ? name.slice(0, -1) : name;
   const rows = [
     endpointRow(
       "GET",
@@ -738,20 +937,20 @@ function resourceAccordion(name, base, isOpen) {
     endpointRow(
       "POST",
       p,
-      `Create a new ${singular}. Auto-assigns <code>id</code> if not provided.`
+      `Create a new ${singular2}. Auto-assigns <code>id</code> if not provided.`
     ),
-    endpointRow("GET", `${p}/:id`, `Get a single ${singular} by id.`),
+    endpointRow("GET", `${p}/:id`, `Get a single ${singular2} by id.`),
     endpointRow(
       "PUT",
       `${p}/:id`,
-      `Fully replace a ${singular}. Original <code>id</code> is always preserved.`
+      `Fully replace a ${singular2}. Original <code>id</code> is always preserved.`
     ),
     endpointRow(
       "PATCH",
       `${p}/:id`,
-      `Partially update a ${singular} \u2014 only provided fields change.`
+      `Partially update a ${singular2} \u2014 only provided fields change.`
     ),
-    endpointRow("DELETE", `${p}/:id`, `Delete a ${singular} and return it as confirmation.`)
+    endpointRow("DELETE", `${p}/:id`, `Delete a ${singular2} and return it as confirmation.`)
   ].join("");
   return `
   <details class="resource-card" ${isOpen ? "open" : ""}>
@@ -770,13 +969,13 @@ function nestedRoutesAccordion(relations, base) {
     for (const [key, def] of Object.entries(fields)) {
       const nestedBadge = def.nested ? ` ${badge("nested", "#facc15", "#facc1518")}` : "";
       if (def.type === "many2many") {
-        const singular = source.endsWith("s") ? source.slice(0, -1) : source;
+        const singular2 = source.endsWith("s") ? source.slice(0, -1) : source;
         const m2mBadge = badge("many2many", "#818cf8", "#818cf818");
         rows.push(
           endpointRow(
             "GET",
             `${base}/${source}/:id/${key}`,
-            `List ${def.target} linked to a ${singular} via ${def.through}. ${m2mBadge}${nestedBadge}`
+            `List ${def.target} linked to a ${singular2} via ${def.through}. ${m2mBadge}${nestedBadge}`
           )
         );
         const targetSingular = def.target.endsWith("s") ? def.target.slice(0, -1) : def.target;
@@ -902,7 +1101,7 @@ function examplesBlock(collections, relations, base, host, options, firstCustomR
   const firstCol = collections[0];
   if (firstCol) {
     const p = `${host}${base}/${firstCol}`;
-    const singular = firstCol.endsWith("s") ? firstCol.slice(0, -1) : firstCol;
+    const singular2 = firstCol.endsWith("s") ? firstCol.slice(0, -1) : firstCol;
     examples.push(
       `# List all ${firstCol}
 curl ${p}`,
@@ -910,17 +1109,17 @@ curl ${p}`,
 curl "${p}?name=value"`,
       `# Sort and paginate
 curl "${p}?_sort=id&_order=desc&_page=1&_limit=5"`,
-      `# Get single ${singular}
+      `# Get single ${singular2}
 curl ${p}/1`,
-      `# Create ${singular}
+      `# Create ${singular2}
 curl -X POST ${p} \\
   -H "Content-Type: application/json" \\
   -d '{"name":"example"}'`,
-      `# Partially update ${singular}
+      `# Partially update ${singular2}
 curl -X PATCH ${p}/1 \\
   -H "Content-Type: application/json" \\
   -d '{"name":"updated"}'`,
-      `# Delete ${singular}
+      `# Delete ${singular2}
 curl -X DELETE ${p}/1`
     );
   }
@@ -983,12 +1182,508 @@ curl ${curlFlag}${fullPath}`);
   return `<pre>${highlighted}</pre>`;
 }
 
+// src/router/templates/about.diagram.ts
+function inferType(value) {
+  if (value === null || value === void 0) return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "object";
+  return "string";
+}
+function generateERData(storage) {
+  const data = storage.getData();
+  const relations = storage.getRelations();
+  const schema = storage.getSchema();
+  const pivotTables = /* @__PURE__ */ new Set();
+  for (const fields of Object.values(relations)) {
+    for (const def of Object.values(fields)) {
+      if (def.type === "many2many") pivotTables.add(def.through);
+    }
+  }
+  const fkFields = /* @__PURE__ */ new Map();
+  for (const [source, fields] of Object.entries(relations)) {
+    for (const [key, def] of Object.entries(fields)) {
+      if (def.type !== "many2many") {
+        if (!fkFields.has(source)) fkFields.set(source, /* @__PURE__ */ new Set());
+        fkFields.get(source).add(key);
+      }
+    }
+  }
+  const entities = Object.entries(data).map(([name, items]) => {
+    const sample = items[0] ?? {};
+    const schemaFields = schema[name] ?? {};
+    const allFields = /* @__PURE__ */ new Set([...Object.keys(sample), ...Object.keys(schemaFields)]);
+    const fields = [...allFields].map((fieldName) => ({
+      name: fieldName,
+      type: schemaFields[fieldName]?.type ?? inferType(sample[fieldName]),
+      pk: fieldName === "id",
+      fk: fkFields.get(name)?.has(fieldName) ?? false,
+      required: schemaFields[fieldName]?.required ?? false
+    }));
+    fields.sort((a, b) => {
+      if (a.pk) return -1;
+      if (b.pk) return 1;
+      if (a.fk && !b.fk) return 1;
+      if (!a.fk && b.fk) return -1;
+      return 0;
+    });
+    return { name, fields, isPivot: pivotTables.has(name) };
+  });
+  const erRelations = [];
+  for (const [source, fields] of Object.entries(relations)) {
+    for (const [key, def] of Object.entries(fields)) {
+      if (def.type === "many2many") {
+        erRelations.push({
+          source,
+          target: def.target,
+          type: "many2many",
+          label: def.through,
+          through: def.through,
+          foreignKey: def.foreignKey,
+          otherKey: def.otherKey
+        });
+      } else {
+        erRelations.push({
+          source,
+          target: def.target,
+          type: def.type,
+          label: key,
+          carDirect: def.carDirect,
+          carInverse: def.carInverse
+        });
+      }
+    }
+  }
+  return { entities, relations: erRelations };
+}
+
+// src/router/templates/about.diagram.canvas.ts
+function erDiagramSection(data) {
+  if (!data.entities.length) return "";
+  const json = JSON.stringify(data);
+  return (
+    /*html*/
+    `
+  <h2>Data Model</h2>
+
+  <div class="card" style="padding:0;overflow:hidden;position:relative;">
+    <canvas id="er-canvas" style="width:100%;display:block;cursor:grab;"></canvas>
+    <button id="er-dl" title="Download PNG" style="position:absolute;top:10px;right:14px;background:#161b22;border:1px solid #30363d;color:#7d8590;padding:4px 10px;border-radius:6px;font-size:11px;cursor:pointer;line-height:1.4;">\u2193 PNG</button>
+  </div>
+
+  <script>${/*js*/
+    `
+    (function(){
+
+    var D=${json};
+
+    // \u2500\u2500 Constants \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    var NW=178,HH=34,FH=22,FP=10,ROW_GAP=44,COL_GAP=100,BR=8,BO=14,LGH=56;
+
+    var C={bg:'#0d1117',nb:'#161b22',nh:'#1c2128',pb:'#0d1117',ph:'#161b22',
+      bo:'#30363d',bs:'#58a6ff',tx:'#e6edf3',mu:'#7d8590',
+      pk:'#e3b341',fk:'#79c0ff',m2o:'#58a6ff',o2o:'#34d399',m2m:'#818cf8'};
+
+    // \u2500\u2500 Canvas \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    var cv = document.getElementById('er-canvas');
+    var dpr = window.devicePixelRatio||1;
+    var ctx = cv.getContext('2d');
+
+    function resize(h){
+      if(h)cv.style.height = h + 'px';
+      var r = cv.getBoundingClientRect();
+      cv.width = Math.round(r.width*dpr);
+      cv.height = Math.round(r.height*dpr);
+    }
+
+    // \u2500\u2500 Nodes & adjacency \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    var nodes = D.entities.map(function(e){
+      return{e:e,x:0,y:0,w:NW,h:HH+e.fields.length*FH+6};
+    });
+
+    var nIdx={};D.entities.forEach(function(e,i){nIdx[e.name]=i;});
+
+    var adj=nodes.map(function(){return[];}); // forward
+    var radj=nodes.map(function(){return[];}); // reverse
+
+    D.relations.forEach(function(r){
+      if(r.type==='many2many'&&r.through&&nIdx[r.through]!=null){
+        var s=nIdx[r.source],p=nIdx[r.through],t=nIdx[r.target];
+        if(s!=null&&p!=null&&s!==p){adj[s].push(p);radj[p].push(s);}
+        if(t!=null&&p!=null&&t!==p){adj[t].push(p);radj[p].push(t);}
+      }else{
+        var s=nIdx[r.source],t=nIdx[r.target];
+        if(s==null||t==null||s===t)return;
+        adj[s].push(t);radj[t].push(s);
+      }
+    });
+
+    // \u2500\u2500 Layered layout (simplified Sugiyama) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    var groups=[];
+
+    function median(arr){
+      if(!arr.length)return 0;
+      var s=[].concat(arr).sort(function(a,b){return a-b;});
+      return s[Math.floor(s.length/2)];
+    }
+
+    function computeLayout(W,H){
+      var layer=nodes.map(function(){return 0;});
+      var inDeg=nodes.map(function(){return 0;});
+      adj.forEach(function(ts){ts.forEach(function(t){inDeg[t]++;});});
+      var q=[],qi=0;
+      for(var i=0;i<nodes.length;i++)if(inDeg[i]===0)q.push(i);
+      if(!q.length)for(var i=0;i<nodes.length;i++)q.push(i);
+      while(qi<q.length){
+        var u=q[qi++];
+        adj[u].forEach(function(v){if(layer[v]<=layer[u]){layer[v]=layer[u]+1;q.push(v);}});
+      }
+      var maxL=layer.reduce(function(m,l){return Math.max(m,l);},0);
+      groups=[];
+      for(var l=0;l<=maxL;l++)groups.push([]);
+      for(var i=0;i<nodes.length;i++)groups[layer[i]].push(i);
+      for(var l=1;l<=maxL;l++){
+        var pp={};groups[l-1].forEach(function(i,p){pp[i]=p;});
+        groups[l].sort(function(a,b){
+          return median(radj[a].map(function(x){return pp[x]!=null?pp[x]:0;}))-
+                median(radj[b].map(function(x){return pp[x]!=null?pp[x]:0;}));
+        });
+      }
+      for(var l=maxL-1;l>=0;l--){
+        var np={};groups[l+1].forEach(function(i,p){np[i]=p;});
+        groups[l].sort(function(a,b){
+          return median(adj[a].map(function(x){return np[x]!=null?np[x]:0;}))-
+                median(adj[b].map(function(x){return np[x]!=null?np[x]:0;}));
+        });
+      }
+      var colW=NW+COL_GAP;
+      var totalW=(maxL+1)*colW-COL_GAP;
+      var startX=Math.max(20,(W-totalW)/2);
+      for(var l=0;l<=maxL;l++){
+        var g=groups[l];
+        var totalH=g.reduce(function(s,i){return s+nodes[i].h;},0)+(g.length-1)*ROW_GAP;
+        var y=Math.max(20,(H-totalH)/2);
+        g.forEach(function(i){nodes[i].x=startX+l*colW;nodes[i].y=y;y+=nodes[i].h+ROW_GAP;});
+      }
+    }
+
+    function requiredH(){
+      return Math.max(340,Math.min(720,groups.reduce(function(m,g){
+        return Math.max(m,g.reduce(function(s,i){return s+nodes[i].h;},0)+(g.length-1)*ROW_GAP+LGH+70);
+      },300)));
+    }
+
+    // \u2500\u2500 View \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    var pan={x:0,y:0},zm=1;
+    var origPos=[];
+
+    function savePos(){origPos=nodes.map(function(n){return{x:n.x,y:n.y};});}
+
+    function fitView(W,H){
+      var x0=1e9,y0=1e9,x1=-1e9,y1=-1e9;
+      nodes.forEach(function(n){x0=Math.min(x0,n.x);y0=Math.min(y0,n.y);x1=Math.max(x1,n.x+n.w);y1=Math.max(y1,n.y+n.h);});
+      var pad=28,gW=x1-x0+pad*2,gH=y1-y0+pad*2;
+      zm=Math.min(W/gW,(H-LGH)/gH,1);
+      pan.x=(W-gW*zm)/2+pad*zm-x0*zm;
+      pan.y=((H-LGH)-gH*zm)/2+pad*zm-y0*zm;
+    }
+
+    // \u2500\u2500 Rendering \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    function rr(x,y,w,h,r){
+      if(ctx.roundRect){ctx.beginPath();ctx.roundRect(x,y,w,h,r);return;}
+      ctx.beginPath();ctx.moveTo(x+r,y);ctx.arcTo(x+w,y,x+w,y+h,r);
+      ctx.arcTo(x+w,y+h,x,y+h,r);ctx.arcTo(x,y+h,x,y,r);ctx.arcTo(x,y,x+w,y,r);ctx.closePath();
+    }
+
+    function edgePt(n,tx,ty){
+      var cx=n.x+n.w/2,cy=n.y+n.h/2,dx=tx-cx,dy=ty-cy;
+      if(!dx&&!dy)return{x:cx,y:cy};
+      var s=Math.min((n.w/2)/Math.abs(dx||.001),(n.h/2)/Math.abs(dy||.001));
+      return{x:cx+dx*s,y:cy+dy*s};
+    }
+
+    var badges=[];
+
+    function pushBadge(x,y,ux,uy,many,col){
+      badges.push({x:x,y:y,ux:ux,uy:uy,many:many,col:col});
+    }
+
+    // Badge: solid colored circle; crow's foot (many) or double-bar (one) in dark ink inside.
+    // ux,uy points outward from the node \u2014 badge is offset BO px into the gap.
+    // Crow's foot tines open toward the node (-x in rotated frame), tip toward line (+x).
+    function drawBadge(b){
+      var bx=b.x+b.ux*BO,by=b.y+b.uy*BO;
+      ctx.fillStyle=b.col;ctx.strokeStyle=b.col;ctx.lineWidth=1;
+      ctx.beginPath();ctx.arc(bx,by,BR,0,Math.PI*2);ctx.fill();ctx.stroke();
+      ctx.save();ctx.translate(bx,by);ctx.rotate(Math.atan2(b.uy,b.ux));
+      ctx.strokeStyle=C.bg;ctx.lineWidth=1.4;ctx.lineCap='round';
+      ctx.beginPath();
+      if(b.many){
+        ctx.moveTo(-5,-4);ctx.lineTo(5,0);  // upper tine \u2192 tip
+        ctx.moveTo(-5,4);ctx.lineTo(5,0);   // lower tine \u2192 tip
+        ctx.moveTo(-5,0);ctx.lineTo(5,0);   // center line
+        ctx.moveTo(-5,-4);ctx.lineTo(-5,4); // base bar (near node)
+      }else{
+        ctx.moveTo(-3,-5);ctx.lineTo(-3,5); // near bar
+        ctx.moveTo(2,-5);ctx.lineTo(2,5);   // far bar
+      }
+      ctx.stroke();
+      ctx.restore();
+    }
+
+    function ecol(t){return t==='one2one'?C.o2o:t==='many2many'?C.m2m:C.m2o;}
+
+    // offset: pixels to shift perpendicular to the edge direction (for parallel edges)
+    function drawEdgeLine(a,b,col,dashed,label,manyA,manyB,off){
+      var p1=edgePt(a,b.x+b.w/2,b.y+b.h/2);
+      var p2=edgePt(b,a.x+a.w/2,a.y+a.h/2);
+      var dx=p2.x-p1.x,dy=p2.y-p1.y,d=Math.sqrt(dx*dx+dy*dy)||1;
+      var ux=dx/d,uy=dy/d;
+      var px=-uy*off,py=ux*off; // perpendicular shift
+      var q1x=p1.x+px,q1y=p1.y+py,q2x=p2.x+px,q2y=p2.y+py;
+      ctx.strokeStyle=col+'55';ctx.lineWidth=1.5;
+      ctx.setLineDash(dashed?[5,4]:[]);
+      ctx.beginPath();ctx.moveTo(q1x,q1y);ctx.lineTo(q2x,q2y);ctx.stroke();
+      ctx.setLineDash([]);
+      pushBadge(q1x,q1y,ux,uy,manyA,col);
+      pushBadge(q2x,q2y,-ux,-uy,manyB,col);
+      if(label){
+        var mx=(q1x+q2x)/2,my=(q1y+q2y)/2;
+        ctx.fillStyle=C.mu;ctx.font='10px monospace';ctx.textAlign='center';ctx.textBaseline='middle';
+        ctx.fillText(label,mx-uy*14,my+ux*14);
+        ctx.textBaseline='alphabetic';
+      }
+    }
+
+    // canonical key for a node pair regardless of direction
+    function pairKey(a,b){
+      var ai=nodes.indexOf(a),bi=nodes.indexOf(b);
+      return ai<bi?ai+'-'+bi:bi+'-'+ai;
+    }
+
+    function collectEdges(){
+      var edges=[];
+      D.relations.forEach(function(r){
+        var col=ecol(r.type);
+        if(r.type==='many2many'&&r.through&&nIdx[r.through]!=null){
+          var sn=nodes[nIdx[r.source]],pn=nodes[nIdx[r.through]],tn=nodes[nIdx[r.target]];
+          if(sn&&pn)edges.push({a:sn,b:pn,col:col,dashed:true,label:r.foreignKey||'',manyA:false,manyB:true,off:0});
+          if(tn&&pn)edges.push({a:tn,b:pn,col:col,dashed:true,label:r.otherKey||'',manyA:false,manyB:true,off:0});
+        }else{
+          var sn=nodes[nIdx[r.source]],tn=nodes[nIdx[r.target]];
+          if(sn&&tn&&sn!==tn){
+            var manyA=r.carInverse?r.carInverse.endsWith('n'):r.type!=='one2one';
+            var manyB=r.carDirect?r.carDirect.endsWith('n'):r.type==='many2many';
+            edges.push({a:sn,b:tn,col:col,dashed:false,label:r.label,manyA:manyA,manyB:manyB,off:0});
+          }
+        }
+      });
+      // assign perpendicular offsets to parallel edges (same node pair)
+      var cnt={},idx={};
+      edges.forEach(function(e){var k=pairKey(e.a,e.b);cnt[k]=(cnt[k]||0)+1;});
+      edges.forEach(function(e){
+        var k=pairKey(e.a,e.b),n=cnt[k];
+        var i=idx[k]=(idx[k]||0);
+        e.off=n>1?(i-(n-1)/2)*16:0;
+        idx[k]++;
+      });
+      return edges;
+    }
+
+    function drawNode(n){
+      var x=n.x,y=n.y,w=n.w,h=n.h,e=n.e;
+      var bg=e.isPivot?C.pb:C.nb,hd=e.isPivot?C.ph:C.nh;
+      ctx.save();ctx.shadowColor='rgba(0,0,0,0.45)';ctx.shadowBlur=14;ctx.shadowOffsetY=4;
+      ctx.fillStyle=bg;rr(x,y,w,h,7);ctx.fill();ctx.restore();
+      ctx.fillStyle=bg;rr(x,y,w,h,7);ctx.fill();
+      ctx.strokeStyle=n===drag?C.bs:C.bo;ctx.lineWidth=1.2;rr(x,y,w,h,7);ctx.stroke();
+      ctx.fillStyle=hd;rr(x,y,w,HH,7);ctx.fill();ctx.fillRect(x,y+HH-7,w,7);
+      ctx.strokeStyle=C.bo;ctx.lineWidth=1;
+      ctx.beginPath();ctx.moveTo(x,y+HH);ctx.lineTo(x+w,y+HH);ctx.stroke();
+      ctx.fillStyle=e.isPivot?C.mu:C.tx;
+      ctx.font='600 12px -apple-system,BlinkMacSystemFont,sans-serif';
+      ctx.textAlign='left';ctx.textBaseline='middle';
+      ctx.fillText(e.name,x+FP,y+HH/2);
+      if(e.isPivot){
+        ctx.fillStyle='#3d444d';ctx.font='9px monospace';ctx.textAlign='right';
+        ctx.fillText('pivot',x+w-FP,y+HH/2);
+      }
+      e.fields.forEach(function(f,fi){
+        var fy=y+HH+fi*FH+FH/2+3;
+        ctx.fillStyle=C.mu;ctx.font='10px monospace';ctx.textAlign='right';ctx.textBaseline='middle';
+        ctx.fillText(f.type,x+w-FP-(f.required&&!f.pk?14:0),fy);
+        if(f.pk||f.fk){
+          var tag=f.pk?'PK':'FK',tc=f.pk?C.pk:C.fk;
+          ctx.fillStyle=tc+'22';ctx.strokeStyle=tc+'66';ctx.lineWidth=1;
+          rr(x+FP,fy-6,12,12,2);ctx.fill();ctx.stroke();
+          ctx.fillStyle=tc;ctx.font='7px monospace';ctx.textAlign='center';
+          ctx.fillText(tag,x+FP+6,fy+0.5);
+        }
+        ctx.fillStyle=f.pk?C.pk:f.fk?C.fk:C.tx;
+        ctx.font=(f.required&&!f.pk?'600 ':'')+'11px monospace';
+        ctx.textAlign='left';ctx.textBaseline='middle';
+        ctx.fillText(f.name,x+FP+(f.pk||f.fk?16:0),fy);
+        if(f.required&&!f.pk){
+          ctx.fillStyle='#f85149';ctx.beginPath();
+          ctx.arc(x+w-FP-6,fy,2.5,0,Math.PI*2);ctx.fill();
+        }
+      });
+      ctx.textBaseline='alphabetic';
+    }
+
+    function drawLegend(){
+      var cvW=cv.width/dpr,cvH=cv.height/dpr;
+      var y0=cvH-LGH,y1=cvH-LGH+18,y2=cvH-LGH+38;
+
+      ctx.fillStyle='#161b22';
+      ctx.fillRect(0,y0,cvW,LGH);
+      ctx.strokeStyle='#30363d';ctx.lineWidth=1;
+      ctx.beginPath();ctx.moveTo(0,y0);ctx.lineTo(cvW,y0);ctx.stroke();
+
+      // Row 1: relation line types
+      var types=[
+        {c:C.m2o,l:'many2one',d:false},
+        {c:C.o2o,l:'one2one',d:false},
+        {c:C.m2m,l:'many2many',d:true}
+      ];
+      ctx.textAlign='left';ctx.textBaseline='middle';ctx.font='10px monospace';
+      var x=14;
+      types.forEach(function(it){
+        ctx.strokeStyle=it.c;ctx.lineWidth=1.5;ctx.setLineDash(it.d?[4,3]:[]);
+        ctx.beginPath();ctx.moveTo(x,y1);ctx.lineTo(x+14,y1);ctx.stroke();
+        ctx.setLineDash([]);
+        ctx.fillStyle=C.mu;
+        ctx.fillText(it.l,x+18,y1);
+        x+=18+ctx.measureText(it.l).width+22;
+      });
+
+      // Row 2: cardinality symbols
+      function badge2(cx,cy,many,col){
+        ctx.fillStyle=col;ctx.strokeStyle=col;ctx.lineWidth=1;
+        ctx.beginPath();ctx.arc(cx,cy,6,0,Math.PI*2);ctx.fill();
+        ctx.save();ctx.translate(cx,cy);
+        ctx.strokeStyle=C.bg;ctx.lineWidth=1.2;ctx.lineCap='round';
+        ctx.beginPath();
+        if(many){
+          ctx.moveTo(-4,-3);ctx.lineTo(4,0);ctx.moveTo(-4,3);ctx.lineTo(4,0);
+          ctx.moveTo(-4,0);ctx.lineTo(4,0);ctx.moveTo(-4,-3);ctx.lineTo(-4,3);
+        }else{
+          ctx.moveTo(-2,-3);ctx.lineTo(-2,3);ctx.moveTo(2,-3);ctx.lineTo(2,3);
+        }
+        ctx.stroke();ctx.restore();
+      }
+
+      ctx.font='10px monospace';ctx.textAlign='left';ctx.textBaseline='middle';
+      x=14;
+      var pairs=[
+        {a:false,b:true,col:C.m2o,l:'many2one (N:1)'},
+        {a:false,b:false,col:C.o2o,l:'one2one (1:1)'},
+        {a:false,b:true,col:C.m2m,l:'pivot edge (1:N)'}
+      ];
+      pairs.forEach(function(p){
+        ctx.strokeStyle=p.col+'55';ctx.lineWidth=1.2;ctx.setLineDash(p.col===C.m2m?[4,3]:[]);
+        ctx.beginPath();ctx.moveTo(x+8,y2);ctx.lineTo(x+56,y2);ctx.stroke();
+        ctx.setLineDash([]);
+        badge2(x+8,y2,p.a,p.col);
+        badge2(x+56,y2,p.b,p.col);
+        ctx.fillStyle=C.mu;ctx.font='10px monospace';ctx.textAlign='left';ctx.textBaseline='middle';
+        ctx.fillText(p.l,x+66,y2);
+        x+=66+ctx.measureText(p.l).width+24;
+      });
+
+      ctx.fillStyle='#3d444d';ctx.font='10px monospace';ctx.textAlign='right';ctx.textBaseline='middle';
+      ctx.fillText('drag  \xB7  scroll to zoom  \xB7  dbl-click to reset',cvW-14,y2);
+      ctx.textBaseline='alphabetic';
+    }
+
+    function draw(){
+      var W=cv.width/dpr,H=cv.height/dpr;
+      ctx.setTransform(dpr,0,0,dpr,0,0);
+      ctx.clearRect(0,0,W,H);
+      ctx.fillStyle=C.bg;ctx.fillRect(0,0,W,H);
+      ctx.save();ctx.translate(pan.x,pan.y);ctx.scale(zm,zm);
+      badges=[];
+      var edges=collectEdges();
+      edges.forEach(function(e){drawEdgeLine(e.a,e.b,e.col,e.dashed,e.label,e.manyA,e.manyB,e.off);});
+      nodes.forEach(function(n){drawNode(n);});
+      badges.forEach(function(b){drawBadge(b);});
+      ctx.restore();
+      drawLegend();
+    }
+
+    // \u2500\u2500 Interaction \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    var drag=null,dox=0,doy=0,isPan=false,ps={x:0,y:0};
+
+    function toW(mx,my){return{x:(mx-pan.x)/zm,y:(my-pan.y)/zm};}
+    function hitTest(wx,wy){
+      for(var i=nodes.length-1;i>=0;i--){var n=nodes[i];if(wx>=n.x&&wx<=n.x+n.w&&wy>=n.y&&wy<=n.y+n.h)return n;}
+      return null;
+    }
+
+    cv.addEventListener('mousedown',function(ev){
+      var r=cv.getBoundingClientRect(),mx=ev.clientX-r.left,my=ev.clientY-r.top;
+      var w=toW(mx,my),h=hitTest(w.x,w.y);
+      if(h){drag=h;dox=w.x-h.x;doy=w.y-h.y;}else{isPan=true;ps={x:mx-pan.x,y:my-pan.y};}
+      cv.style.cursor='grabbing';
+    });
+    window.addEventListener('mousemove',function(ev){
+      if(!drag&&!isPan)return;
+      var r=cv.getBoundingClientRect(),mx=ev.clientX-r.left,my=ev.clientY-r.top;
+      if(drag){var w=toW(mx,my);drag.x=w.x-dox;drag.y=w.y-doy;}
+      else{pan.x=mx-ps.x;pan.y=my-ps.y;}
+      draw();
+    });
+    window.addEventListener('mouseup',function(){drag=null;isPan=false;cv.style.cursor='grab';});
+    cv.addEventListener('wheel',function(ev){
+      ev.preventDefault();
+      var r=cv.getBoundingClientRect(),mx=ev.clientX-r.left,my=ev.clientY-r.top;
+      var d=ev.deltaY<0?1.1:0.91,nz=Math.max(0.25,Math.min(3,zm*d));
+      pan.x=mx-(mx-pan.x)*(nz/zm);pan.y=my-(my-pan.y)*(nz/zm);zm=nz;draw();
+    },{passive:false});
+    cv.addEventListener('dblclick',function(){
+      nodes.forEach(function(n,i){n.x=origPos[i].x;n.y=origPos[i].y;});
+      var r=cv.getBoundingClientRect();fitView(r.width,r.height);draw();
+    });
+    window.addEventListener('resize',function(){
+      resize();var r=cv.getBoundingClientRect();
+      computeLayout(r.width,r.height);savePos();fitView(r.width,r.height);draw();
+    });
+
+    document.getElementById('er-dl').addEventListener('click',function(){
+      var SCALE=3;
+      var cw=cv.width/dpr,ch=cv.height/dpr;
+      var oc=document.createElement('canvas');
+      oc.width=Math.round(cw*SCALE);oc.height=Math.round(ch*SCALE);
+      var sav={cv:cv,ctx:ctx,dpr:dpr};
+      cv=oc;ctx=oc.getContext('2d');dpr=SCALE;
+      draw();
+      cv=sav.cv;ctx=sav.ctx;dpr=sav.dpr;
+      var a=document.createElement('a');
+      a.download='er-diagram.png';a.href=oc.toDataURL('image/png');a.click();
+    });
+
+    // \u2500\u2500 Init \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    requestAnimationFrame(function(){
+      resize();
+      var r=cv.getBoundingClientRect();
+      computeLayout(r.width,r.height);
+      var h=requiredH();
+      resize(h);r=cv.getBoundingClientRect();
+      computeLayout(r.width,r.height);
+      savePos();fitView(r.width,r.height);draw();
+    });
+    })();
+      `}</script>`
+  );
+}
+
 // src/router/templates/about.template.ts
 var _dir = dirname2(fileURLToPath(import.meta.url));
 var LOGO_SRC = (() => {
   try {
-    const buf = readFileSync2(join(_dir, "../../assets/logo-color.png"));
-    return `data:image/png;base64,${buf.toString("base64")}`;
+    const buf = readFileSync2(join(_dir, "../../assets/yrest-lockup.svg"));
+    return `data:image/svg+xml;base64,${buf.toString("base64")}`;
   } catch {
     return "";
   }
@@ -999,6 +1694,7 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
   const customRoutes = storage.getRoutes();
   const base = options.base;
   const host = `http://${options.host}:${options.port}`;
+  const swaggerUrl = `https://petstore.swagger.io/?url=${encodeURIComponent(`${host}/_openapi.json`)}`;
   const modes = [];
   if (options.watch) modes.push(badge("watch", "#38bdf8", "#38bdf818"));
   if (options.readonly) modes.push(badge("readonly", "#94a3b8", "#94a3b818"));
@@ -1009,9 +1705,12 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
   if (handlers.size > 0) modes.push(badge(`handlers \xB7 ${handlers.size}`, "#f0883e", "#f0883e18"));
   if (options.idStrategy !== "increment")
     modes.push(badge(`id \xB7 ${options.idStrategy}`, "#a371f7", "#a371f718"));
+  const erDiagram = erDiagramSection(generateERData(storage));
   const accordions = collections.map((col, i) => resourceAccordion(col, base, i === 0)).join("");
   const paginationDesc = options.pageable.enabled ? `Pageable mode active \u2014 default limit <code>${options.pageable.limit}</code>. Response wrapped in <code>{ data, pagination }</code>.` : `Returns the requested slice. <code>X-Total-Count</code> header reflects the total before pagination.`;
-  return `<!DOCTYPE html>
+  return (
+    /*html*/
+    `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
@@ -1038,20 +1737,30 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
       width: 100%;
       background: linear-gradient(135deg, #0d1117 0%, #161b22 40%, #1a2332 100%);
       border-bottom: 1px solid var(--border);
-      padding: 48px 32px 40px;
+      padding: 20px 32px 16px;
     }
-    .banner-inner { max-width: 1100px; margin: 0 auto; }
-    .banner h1 { font-size: clamp(36px, 6vw, 60px); font-weight: 800; letter-spacing: -2px; line-height: 1; }
+    .banner-inner { margin: 0 auto; display:flex; align-items:center; justify-content:space-between; gap:16px; flex-wrap:wrap; }
+    .banner-left { flex:1; min-width:0; }
+    .banner h1 { font-size: clamp(24px, 4vw, 40px); font-weight: 800; letter-spacing: -1.5px; line-height: 1; }
     .banner h1 .y { color: var(--text); }
     .banner h1 .rest { color: var(--accent); }
-    .banner p { color: var(--text-muted); margin-top: 10px; font-size: 15px; }
-    .banner-meta { display: flex; gap: 24px; margin-top: 20px; flex-wrap: wrap; }
-    .banner-meta span { color: var(--text-muted); font-size: 13px; }
+    .banner p { color: var(--text-muted); margin-top: 6px; font-size: 14px; }
+    .banner-meta { display: flex; gap: 20px; margin-top: 10px; flex-wrap: wrap; }
+    .banner-meta span { color: var(--text-muted); font-size: 12px; }
     .banner-meta span strong { color: var(--text); font-family: monospace; }
+    .api-links { display:flex; gap:8px; flex-wrap:wrap; align-items:center; }
+    .btn-api { display:inline-block; padding:5px 12px; border-radius:6px; border:1px solid var(--border); color:var(--text-muted); text-decoration:none; font-size:12px; font-weight:500; background:var(--bg-card); white-space:nowrap; transition:border-color .15s,color .15s; }
+    .btn-api:hover { border-color:var(--border-hi); color:var(--text); }
+    .btn-swagger { border-color:var(--accent); color:var(--accent); }
+    .btn-swagger:hover { background:#58a6ff18; }
 
     /* \u2500\u2500 Layout \u2500\u2500 */
-    .wrap { max-width: 1100px; margin: 0 auto; padding: 32px 24px 48px; }
+    .wrap { padding: 24px 32px 48px; }
     h2 { font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: .08em; color: var(--text-muted); margin: 32px 0 12px; }
+    .about-grid { display:grid; grid-template-columns:5fr 7fr; gap:28px; align-items:start; }
+    @media(max-width:960px) { .about-grid { grid-template-columns:1fr; } }
+    .col-left, .col-right { min-width:0; }
+    .col-left > h2:first-child, .col-right > h2:first-child { margin-top:0; }
 
     /* \u2500\u2500 Cards \u2500\u2500 */
     .card { background: var(--bg-card); border: 1px solid var(--border); border-radius: var(--radius); padding: 20px 24px; }
@@ -1067,10 +1776,8 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
     .modes { display: flex; gap: 8px; flex-wrap: wrap; min-height: 28px; align-items: center; }
     .badge { display: inline-block; padding: 3px 10px; border-radius: 20px; font-size: 12px; font-weight: 600; white-space: nowrap; }
 
-    /* \u2500\u2500 Endpoints grid (2 cols on wide, 1 col on narrow) \u2500\u2500 */
-    .endpoints-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 10px; }
-    @media (max-width: 860px) { .endpoints-grid { grid-template-columns: 1fr; } }
-    .nested-card { grid-column: 1 / -1; }
+    /* \u2500\u2500 Endpoints list \u2500\u2500 */
+    .endpoints-grid { display: flex; flex-direction: column; gap: 10px; }
 
     /* \u2500\u2500 Accordion (details/summary) \u2500\u2500 */
     .resource-card {
@@ -1135,64 +1842,80 @@ function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map(
 
   <div class="banner">
     <div class="banner-inner">
-      ${LOGO_SRC ? `<img src="${LOGO_SRC}" alt="yRest" height="68" style="display:block;margin-bottom:0px" />` : `<h1><span class="y">y</span><span class="rest">Rest</span></h1>`}
-      <p>Zero-config REST API mock server</p>
-      <div class="banner-meta">
-        <span>URL <strong>${host}</strong></span>
-        <span>Base <strong>${base || "/"}</strong></span>
-        <span>File <strong>${options.file}</strong></span>
-        <span>Collections <strong>${collections.length}</strong></span>
+      <div class="banner-left">
+        ${LOGO_SRC ? `<img src="${LOGO_SRC}" alt="yRest" height="36" style="display:block;margin-bottom:4px" />` : `<h1><span class="y">y</span><span class="rest">Rest</span></h1>`}
+        <p>Zero-config REST API mock server</p>
+        <div class="banner-meta">
+          <span>URL <strong>${host}</strong></span>
+          <span>Base <strong>${base || "/"}</strong></span>
+          <span>File <strong>${options.file}</strong></span>
+          <span>Collections <strong>${collections.length}</strong></span>
+        </div>
+      </div>
+      <div class="api-links">
+        <a href="/_openapi" target="_blank" class="btn-api">OpenAPI YAML</a>
+        <a href="/_openapi.json" target="_blank" class="btn-api">OpenAPI JSON</a>
+        <a href="${swaggerUrl}" target="_blank" class="btn-api btn-swagger">Swagger UI \u2197</a>
       </div>
     </div>
   </div>
 
   <div class="wrap">
+    <div class="about-grid">
+
+      <div class="col-left">
+        <h2>Active Modes</h2>
+        <div class="card">
+          <div class="modes">${modes.length ? modes.join(" ") : `<span style="color:var(--text-muted);font-size:13px">none</span>`}</div>
+          ${options.watch ? `<div class="warn">\u26A0 <strong>Watch mode:</strong> data changes in existing collections reload automatically. Adding or removing entire collections requires a server restart.</div>` : ""}
+        </div>
+
+        <h2>Endpoints</h2>
+        <div class="endpoints-grid">
+          ${accordions}
+          ${nestedRoutesAccordion(relations, base)}
+          ${options.snapshot ? snapshotAccordion() : ""}
+          ${customRoutesAccordion(customRoutes, base, handlers)}
+          ${handlersAccordion(handlers, customRoutes, base)}
+        </div>
+
+        <h2>Query Parameters</h2>
+        <div class="card">
+          <table class="param-table">
+            <thead><tr><th>Param</th><th>Example</th><th>Description</th></tr></thead>
+            <tbody>
+              <tr><td><code>?field=value</code></td><td><code>?name=Ana&amp;role=admin</code></td><td>Filter by any field. Multiple params are ANDed.</td></tr>
+              <tr><td><code>?field_gte / _lte</code></td><td><code>?price_gte=10&amp;price_lte=50</code></td><td>Numeric or lexicographic range. Works with any comparable field.</td></tr>
+              <tr><td><code>?field_ne</code></td><td><code>?status_ne=inactive</code></td><td>Exclude items where the field equals the value.</td></tr>
+              <tr><td><code>?field_like</code></td><td><code>?name_like=ana</code></td><td>Case-insensitive substring match.</td></tr>
+              <tr><td><code>?field_start</code></td><td><code>?name_start=A</code></td><td>Case-insensitive prefix match.</td></tr>
+              <tr><td><code>?field_regex</code></td><td><code>?email_regex=gmail</code></td><td>Case-insensitive regular expression match.</td></tr>
+              <tr><td><code>?_q</code></td><td><code>?_q=ana</code></td><td>Full-text search across all scalar fields (case-insensitive substring).</td></tr>
+              <tr><td><code>?_sort &amp; ?_order</code></td><td><code>?_sort=name&amp;_order=desc</code></td><td>Sort by field. <code>_order</code>: <code>asc</code> (default) or <code>desc</code>.</td></tr>
+              <tr><td><code>?_page &amp; ?_limit</code></td><td><code>?_page=2&amp;_limit=10</code></td><td>${paginationDesc}</td></tr>
+              <tr><td><code>?_expand</code></td><td><code>?_expand=user</code></td><td>Embed a related parent object inline. Requires <code>_rel</code> in the YAML file.</td></tr>
+              <tr><td><code>?_embed</code></td><td><code>?_embed=posts</code></td><td>Embed child collections into each parent item. Requires <code>_rel</code> in the YAML file.</td></tr>
+              <tr><td><code>?_fields</code></td><td><code>?_fields=id,name</code></td><td>Return only the specified fields. Applied last \u2014 can include embedded/expanded keys.</td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
 
-    <h2>Active Modes</h2>
-    <div class="card">
-      <div class="modes">${modes.length ? modes.join(" ") : `<span style="color:var(--text-muted);font-size:13px">none</span>`}</div>
-      ${options.watch ? `<div class="warn">\u26A0 <strong>Watch mode:</strong> data changes in existing collections reload automatically. Adding or removing entire collections requires a server restart.</div>` : ""}
-    </div>
-
-    <h2>Endpoints</h2>
-    <div class="endpoints-grid">
-      ${accordions}
-      ${nestedRoutesAccordion(relations, base)}
-      ${options.snapshot ? snapshotAccordion() : ""}
-      ${customRoutesAccordion(customRoutes, base, handlers)}
-      ${handlersAccordion(handlers, customRoutes, base)}
-    </div>
+      <div class="col-right">
+        ${erDiagram}
+        ${collections.length ? `<h2>Examples</h2><div class="card">${examplesBlock(collections, relations, base, host, options, customRoutes[0])}</div>` : ""}
+      </div>
 
-    <h2>Query Parameters</h2>
-    <div class="card">
-      <table class="param-table">
-        <thead><tr><th>Param</th><th>Example</th><th>Description</th></tr></thead>
-        <tbody>
-          <tr><td><code>?field=value</code></td><td><code>?name=Ana&amp;role=admin</code></td><td>Filter by any field. Multiple params are ANDed.</td></tr>
-          <tr><td><code>?field_gte / _lte</code></td><td><code>?price_gte=10&amp;price_lte=50</code></td><td>Numeric or lexicographic range. Works with any comparable field.</td></tr>
-          <tr><td><code>?field_ne</code></td><td><code>?status_ne=inactive</code></td><td>Exclude items where the field equals the value.</td></tr>
-          <tr><td><code>?field_like</code></td><td><code>?name_like=ana</code></td><td>Case-insensitive substring match.</td></tr>
-          <tr><td><code>?field_start</code></td><td><code>?name_start=A</code></td><td>Case-insensitive prefix match.</td></tr>
-          <tr><td><code>?field_regex</code></td><td><code>?email_regex=gmail</code></td><td>Case-insensitive regular expression match.</td></tr>
-          <tr><td><code>?_q</code></td><td><code>?_q=ana</code></td><td>Full-text search across all scalar fields (case-insensitive substring).</td></tr>
-          <tr><td><code>?_sort &amp; ?_order</code></td><td><code>?_sort=name&amp;_order=desc</code></td><td>Sort by field. <code>_order</code>: <code>asc</code> (default) or <code>desc</code>.</td></tr>
-          <tr><td><code>?_page &amp; ?_limit</code></td><td><code>?_page=2&amp;_limit=10</code></td><td>${paginationDesc}</td></tr>
-          <tr><td><code>?_expand</code></td><td><code>?_expand=user</code></td><td>Embed a related parent object inline. Requires <code>_rel</code> in the YAML file.</td></tr>
-          <tr><td><code>?_embed</code></td><td><code>?_embed=posts</code></td><td>Embed child collections into each parent item. Requires <code>_rel</code> in the YAML file.</td></tr>
-          <tr><td><code>?_fields</code></td><td><code>?_fields=id,name</code></td><td>Return only the specified fields. Applied last \u2014 can include embedded/expanded keys.</td></tr>
-        </tbody>
-      </table>
     </div>
 
-    ${collections.length ? `<h2>Examples</h2><div class="card">${examplesBlock(collections, relations, base, host, options, customRoutes[0])}</div>` : ""}
-
     <footer>
       Powered by <a href="https://github.com/aggiovato/yRest" target="_blank">@yrest/cli</a> &nbsp;\xB7&nbsp; <a href="/_about">/_about</a>
     </footer>
 
   </div>
 </body>
-</html>`;
+</html>`
+  );
 }
 
 // src/router/routes/about.routes.ts
@@ -1656,7 +2379,7 @@ var CustomRouteCommand = class {
         url,
         handler: async (req, reply) => {
           if (route.delay && route.delay > 0) {
-            await new Promise((resolve5) => setTimeout(resolve5, route.delay));
+            await new Promise((resolve6) => setTimeout(resolve6, route.delay));
           }
           if (route.error) {
             const body2 = route.errorBody ?? { error: `Forced error ${route.error}` };
@@ -1780,12 +2503,23 @@ var NestedRouteCommand = class {
   relations;
   base;
   register(server) {
+    const registered = /* @__PURE__ */ new Set();
     for (const [source, fields] of Object.entries(this.relations)) {
       for (const [key, def] of Object.entries(fields)) {
         if (def.type === "many2many") {
-          this.registerMany2Many(server, source, key, def);
+          const fwd = `${this.base}/${source}/:id/${key}`;
+          const inv = `${this.base}/${def.target}/:id/${source}`;
+          if (!registered.has(fwd) && !registered.has(inv)) {
+            registered.add(fwd);
+            registered.add(inv);
+            this.registerMany2Many(server, source, key, def);
+          }
         } else {
-          this.registerFkRelation(server, source, key, def.target, def.type);
+          const collPath = `${this.base}/${def.target}/:id/${source}`;
+          if (!registered.has(collPath)) {
+            registered.add(collPath);
+            this.registerFkRelation(server, source, key, def.target, def.type);
+          }
         }
       }
     }
@@ -1844,6 +2578,371 @@ var NestedRouteCommand = class {
   }
 };
 
+// src/openapi/inferSchema.ts
+function buildCollectionSchema(items, fieldDefs = {}) {
+  const sample = items.slice(0, 10);
+  const inferredTypes = /* @__PURE__ */ new Map();
+  for (const item of sample) {
+    for (const [key, value] of Object.entries(item)) {
+      if (!inferredTypes.has(key)) {
+        inferredTypes.set(key, jsToOpenApiType(value));
+      }
+    }
+  }
+  const allFields = /* @__PURE__ */ new Set([...inferredTypes.keys(), ...Object.keys(fieldDefs)]);
+  const properties = {};
+  const required = [];
+  for (const field of allFields) {
+    const def = fieldDefs[field];
+    const inferred = inferredTypes.get(field) ?? "string";
+    const prop = {
+      type: def?.type ?? inferred
+    };
+    if (def?.format) prop.format = def.format;
+    if (def?.description) prop.description = def.description;
+    if (def?.enum) prop.enum = def.enum;
+    if (def?.default !== void 0) prop.default = def.default;
+    properties[field] = prop;
+    if (def?.required === true) required.push(field);
+  }
+  const schema = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+function jsToOpenApiType(value) {
+  if (value === null || value === void 0) return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "object";
+  return "string";
+}
+
+// src/openapi/buildPaths.ts
+var COLLECTION_QUERY_PARAMS = [
+  { name: "_page", in: "query", schema: { type: "integer" }, description: "Page number (1-based)" },
+  { name: "_limit", in: "query", schema: { type: "integer" }, description: "Items per page" },
+  { name: "_sort", in: "query", schema: { type: "string" }, description: "Field name to sort by" },
+  {
+    name: "_order",
+    in: "query",
+    schema: { type: "string", enum: ["asc", "desc"] },
+    description: "Sort direction"
+  },
+  {
+    name: "_q",
+    in: "query",
+    schema: { type: "string" },
+    description: "Full-text search across all scalar fields (case-insensitive)"
+  },
+  {
+    name: "_expand",
+    in: "query",
+    schema: { type: "string" },
+    description: "Embed related parent object inline (e.g. ?_expand=user)"
+  },
+  {
+    name: "_embed",
+    in: "query",
+    schema: { type: "string" },
+    description: "Embed child collection into each item (e.g. ?_embed=posts)"
+  },
+  {
+    name: "_fields",
+    in: "query",
+    schema: { type: "string" },
+    description: "Comma-separated field projection (e.g. ?_fields=id,name)"
+  }
+];
+var ID_PATH_PARAM = {
+  name: "id",
+  in: "path",
+  required: true,
+  schema: { type: "string" },
+  description: "Item id"
+};
+function toOpenApiPath(fastifyPath) {
+  return fastifyPath.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "{$1}");
+}
+function extractPathParams(fastifyPath) {
+  const matches = fastifyPath.match(/:([a-zA-Z_][a-zA-Z0-9_]*)/g) ?? [];
+  return matches.map((m) => ({
+    name: m.slice(1),
+    in: "path",
+    required: true,
+    schema: { type: "string" }
+  }));
+}
+function singular(name) {
+  return name.endsWith("s") ? name.slice(0, -1) : name;
+}
+function schemaRef(name) {
+  return { $ref: `#/components/schemas/${name}` };
+}
+function jsonContent(schema) {
+  return { "application/json": { schema } };
+}
+function ok(schema, description = "OK") {
+  return { description, content: jsonContent(schema) };
+}
+function buildCrudPaths(collection, base, schemaName) {
+  const ref = schemaRef(schemaName);
+  const tag = collection;
+  const sing = singular(collection);
+  const collPath = `${base}/${collection}`;
+  const itemPath = `${base}/${collection}/{id}`;
+  return {
+    [collPath]: {
+      get: {
+        summary: `List ${collection}`,
+        tags: [tag],
+        parameters: COLLECTION_QUERY_PARAMS,
+        responses: {
+          "200": {
+            description: "OK",
+            content: jsonContent({ type: "array", items: ref }),
+            headers: {
+              "X-Total-Count": {
+                description: "Total items (when using ?_page / ?_limit)",
+                schema: { type: "integer" }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        summary: `Create ${sing}`,
+        tags: [tag],
+        requestBody: { required: true, content: jsonContent(ref) },
+        responses: { "201": ok(ref, "Created") }
+      }
+    },
+    [itemPath]: {
+      get: {
+        summary: `Get ${sing}`,
+        tags: [tag],
+        parameters: [
+          ID_PATH_PARAM,
+          ...COLLECTION_QUERY_PARAMS.filter(
+            (p) => ["_expand", "_embed", "_fields"].includes(p.name)
+          )
+        ],
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      put: {
+        summary: `Replace ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        requestBody: { required: true, content: jsonContent(ref) },
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      patch: {
+        summary: `Update ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        requestBody: { required: false, content: jsonContent(ref) },
+        responses: { "200": ok(ref), "404": { description: "Not found" } }
+      },
+      delete: {
+        summary: `Delete ${sing}`,
+        tags: [tag],
+        parameters: [ID_PATH_PARAM],
+        responses: { "200": ok(ref, "Deleted item returned"), "404": { description: "Not found" } }
+      }
+    }
+  };
+}
+function buildRelationPaths(relations, base) {
+  const paths = {};
+  for (const [source, fields] of Object.entries(relations)) {
+    for (const [key, def] of Object.entries(fields)) {
+      if (def.type === "many2many") {
+        const forwardPath = `${base}/${source}/{id}/${key}`;
+        const inversePath = `${base}/${def.target}/{id}/${source}`;
+        paths[forwardPath] = {
+          get: {
+            summary: `List ${def.target} linked to ${singular(source)} via ${def.through}`,
+            tags: [source],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": {
+                description: "OK",
+                content: jsonContent({ type: "array", items: { type: "object" } })
+              },
+              "404": { description: `${singular(source)} not found` }
+            }
+          }
+        };
+        paths[inversePath] = {
+          get: {
+            summary: `List ${source} linked to ${singular(def.target)} via ${def.through} (inverse)`,
+            tags: [def.target],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": {
+                description: "OK",
+                content: jsonContent({ type: "array", items: { type: "object" } })
+              },
+              "404": { description: `${singular(def.target)} not found` }
+            }
+          }
+        };
+      } else {
+        const parentSing = singular(def.target);
+        const collPath = `${base}/${def.target}/{id}/${source}`;
+        const isOne2One = def.type === "one2one";
+        const responseSchema = isOne2One ? { type: "object" } : { type: "array", items: { type: "object" } };
+        paths[collPath] = {
+          get: {
+            summary: isOne2One ? `Get ${singular(source)} belonging to ${parentSing}` : `List ${source} belonging to ${parentSing}`,
+            tags: [def.target],
+            parameters: [ID_PATH_PARAM],
+            responses: {
+              "200": { description: "OK", content: jsonContent(responseSchema) },
+              "404": { description: `${parentSing} not found` }
+            }
+          }
+        };
+        if (!isOne2One) {
+          const itemPath = `${base}/${def.target}/{id}/${source}/{childId}`;
+          paths[itemPath] = {
+            get: {
+              summary: `Get single ${singular(source)} scoped to ${parentSing}`,
+              tags: [def.target],
+              parameters: [
+                ID_PATH_PARAM,
+                { name: "childId", in: "path", required: true, schema: { type: "string" } }
+              ],
+              responses: {
+                "200": { description: "OK", content: jsonContent({ type: "object" }) },
+                "404": { description: "Not found" }
+              }
+            }
+          };
+        }
+      }
+    }
+  }
+  return paths;
+}
+function buildCustomRoutePaths(routes, base) {
+  const paths = {};
+  for (const route of routes) {
+    const openApiPath = toOpenApiPath(`${base}${route.path}`);
+    const method = route.method.toLowerCase();
+    const pathParams = extractPathParams(route.path);
+    const responses = {};
+    if (route.error) {
+      responses[String(route.error)] = { description: `Forced error ${route.error}` };
+    } else {
+      const statuses = /* @__PURE__ */ new Set();
+      for (const s of route.scenarios ?? []) statuses.add(s.response.status ?? 200);
+      if (route.otherwise) statuses.add(route.otherwise.status ?? 200);
+      if (route.response) statuses.add(route.response.status ?? 200);
+      if (statuses.size === 0) statuses.add(200);
+      for (const status of statuses) {
+        const bodySource = (route.scenarios ?? []).find((s) => (s.response.status ?? 200) === status)?.response.body ?? (route.otherwise?.status ?? 200) === status ? route.otherwise?.body : route.response?.body;
+        responses[String(status)] = {
+          description: status < 400 ? "OK" : "Error",
+          ...bodySource != null ? { content: jsonContent(inferResponseSchema(bodySource)) } : {}
+        };
+      }
+    }
+    const desc = route.handler ? `Handler: ${route.handler}()` : route.scenarios?.length ? `Conditional scenarios (${route.scenarios.length})` : "Custom static route";
+    const operation = {
+      summary: `${route.method.toUpperCase()} ${route.path}`,
+      description: desc,
+      tags: ["custom"],
+      ...pathParams.length > 0 ? { parameters: pathParams } : {},
+      responses
+    };
+    if (!paths[openApiPath]) paths[openApiPath] = {};
+    paths[openApiPath][method] = operation;
+  }
+  return paths;
+}
+function inferResponseSchema(body) {
+  if (body === null || body === void 0) return {};
+  if (typeof body !== "object" || Array.isArray(body)) return { type: "object" };
+  const properties = {};
+  for (const [key, value] of Object.entries(body)) {
+    properties[key] = { type: jsToOpenApiType2(value) };
+  }
+  return { type: "object", properties };
+}
+function jsToOpenApiType2(value) {
+  if (value === null || value === void 0) return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "object";
+  return "string";
+}
+
+// src/openapi/generateOpenApi.ts
+function generateOpenApi(storage, options, title = "yRest API") {
+  const collections = Object.keys(storage.getData());
+  const relations = storage.getRelations();
+  const schemaBlock = storage.getSchema();
+  const customRoutes = storage.getRoutes();
+  const base = options.base ?? "";
+  const schemas = {};
+  for (const collection of collections) {
+    const items = storage.getCollection(collection) ?? [];
+    const fieldDefs = schemaBlock[collection] ?? {};
+    const schemaName = toSchemaName(collection);
+    schemas[schemaName] = buildCollectionSchema(items, fieldDefs);
+  }
+  const paths = {};
+  for (const collection of collections) {
+    const schemaName = toSchemaName(collection);
+    Object.assign(paths, buildCrudPaths(collection, base, schemaName));
+  }
+  Object.assign(paths, buildRelationPaths(relations, base));
+  Object.assign(paths, buildCustomRoutePaths(customRoutes, base));
+  return {
+    openapi: "3.0.3",
+    info: {
+      title,
+      version: "1.0.0",
+      description: "Generated by yRest from db.yml"
+    },
+    servers: [
+      {
+        url: `http://${options.host}:${options.port}${base}`,
+        description: "yRest mock server"
+      }
+    ],
+    paths,
+    components: { schemas }
+  };
+}
+function toSchemaName(collection) {
+  const withoutS = collection.endsWith("s") ? collection.slice(0, -1) : collection;
+  return withoutS.charAt(0).toUpperCase() + withoutS.slice(1);
+}
+
+// src/router/routes/openapi.routes.ts
+import { stringify as stringify2 } from "yaml";
+var OpenApiRouteCommand = class {
+  constructor(storage, options) {
+    this.storage = storage;
+    this.options = options;
+  }
+  storage;
+  options;
+  register(server) {
+    server.get("/_openapi", (_req, reply) => {
+      const doc = generateOpenApi(this.storage, this.options);
+      reply.header("Content-Type", "text/yaml; charset=utf-8");
+      return reply.send(stringify2(doc, { lineWidth: 0, aliasDuplicateObjects: false }));
+    });
+    server.get("/_openapi.json", (_req, reply) => {
+      return reply.send(generateOpenApi(this.storage, this.options));
+    });
+  }
+};
+
 // src/router/routes/snapshot.routes.ts
 var SnapshotRouteCommand = class {
   constructor(storage) {
@@ -1924,6 +3023,7 @@ async function createServer(storage, options, handlers = /* @__PURE__ */ new Map
   }
   const commands = [
     new AboutRouteCommand(storage, options, handlers),
+    new OpenApiRouteCommand(storage, options),
     ...options.snapshot ? [new SnapshotRouteCommand(storage)] : [],
     new CustomRouteCommand(storage, options.base, handlers),
     ...buildResourceRouteCommands(storage, options)
@@ -2168,7 +3268,7 @@ function registerServe(program2) {
 // src/cli/commands/handler.ts
 import { existsSync as existsSync4, readFileSync as readFileSync4, appendFileSync, writeFileSync as writeFileSync3 } from "fs";
 import { join as join3, resolve as resolve4, basename } from "path";
-import { parse as parse3, stringify as stringify2 } from "yaml";
+import { parse as parse3, stringify as stringify3 } from "yaml";
 var HANDLERS_FILE_HEADER = `// yrest handlers \u2014 loaded via "handlers:" in yrest.config.yml
 // Handler signature: (req: HandlerRequest) => HandlerResponse | Promise<HandlerResponse>
 // See https://github.com/aggiovato/yaml-rest for full documentation
@@ -2230,7 +3330,7 @@ function registerHandler(program2) {
       const alreadyRegistered = routes.some((r) => r["handler"] === name);
       if (!alreadyRegistered) {
         routes.push({ method: flags.method.toUpperCase(), path: flags.path, handler: name });
-        writeFileSync3(dbPath, stringify2(raw), "utf8");
+        writeFileSync3(dbPath, stringify3(raw), "utf8");
         console.log(`  Added _routes entry to ${basename(dbPath)}`);
       } else {
         console.log(`  Handler "${name}" already in _routes \u2014 skipped`);
@@ -2253,6 +3353,33 @@ function registerHandler(program2) {
   });
 }
 
+// src/cli/commands/openapi.ts
+import { writeFileSync as writeFileSync4 } from "fs";
+import { resolve as resolve5 } from "path";
+import { stringify as stringify4 } from "yaml";
+function registerOpenApi(program2) {
+  program2.command("openapi <file>").description("Generate an OpenAPI 3.0 spec from a db.yml file").option("-o, --output <file>", "Output file (default: openapi.yaml / openapi.json)").option("--format <fmt>", "Output format: yaml (default) or json", "yaml").option("--stdout", "Print to stdout instead of writing a file").option("--base <base>", "Base path prefix applied to all routes", "").option("--port <port>", "Server port shown in the servers block", "3070").option("--host <host>", "Server host shown in the servers block", "localhost").option("--title <title>", "API title for the info block", "yRest API").action((file, opts) => {
+    const storage = createYrestStorage(resolve5(file));
+    const options = yrestOptionsSchema.parse({
+      file,
+      base: opts["base"] || void 0,
+      port: Number(opts["port"]) || 3070,
+      host: opts["host"] || "localhost"
+    });
+    const doc = generateOpenApi(storage, options, opts["title"]);
+    const isJson = opts["format"] === "json";
+    const output = isJson ? JSON.stringify(doc, null, 2) : stringify4(doc, { lineWidth: 0, aliasDuplicateObjects: false });
+    if (opts["stdout"]) {
+      process.stdout.write(output);
+      return;
+    }
+    const defaultFile = isJson ? "openapi.json" : "openapi.yaml";
+    const outFile = resolve5(opts["output"] ?? defaultFile);
+    writeFileSync4(outFile, output, "utf8");
+    console.log(`\u2713  OpenAPI spec written to ${outFile}`);
+  });
+}
+
 // src/cli/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../../package.json");
@@ -2260,4 +3387,5 @@ program.name("yrest").description("Zero-config REST API mock server powered by a
 registerInit(program);
 registerServe(program);
 registerHandler(program);
+registerOpenApi(program);
 program.parse();