sad-mcp 2.1.1 → 2.2.1

package/dist/usecase/index (DESKTOP-GQHOSST's conflicted copy 2026-04-19).d.ts

@@ -0,0 +1,15 @@
+export interface ValidationIssue {
+    path: string;
+    code: string;
+    message: string;
+}
+export type ValidateResult = {
+    ok: true;
+    warnings: ValidationIssue[];
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+    warnings: ValidationIssue[];
+};
+export declare function formatIssues(issues: ValidationIssue[]): string;
+export declare function parseAndValidate(jsonText: string): ValidateResult;

package/dist/usecase/index (DESKTOP-GQHOSST's conflicted copy 2026-04-19).js

@@ -0,0 +1,218 @@
+// Validator for use-case diagramModel JSON (kind: 'use-case').
+// Called by uml_usecase_validate_model MCP tool in tools.ts.
+// Returns all errors and warnings at once so an LLM can self-correct in one pass.
+export function formatIssues(issues) {
+    if (issues.length === 0)
+        return "(none)";
+    return issues.map(i => `- [${i.code}] ${i.path}: ${i.message}`).join("\n");
+}
+// ── Helpers ───────────────────────────────────────────────────────────────
+function hasHebrew(s) {
+    return /[\u0590-\u05FF\uFB1D-\uFB4F]/.test(s);
+}
+const SEND_ONLY_PREFIXES = [
+    /^שליחת /i, /^הודעה ל/i, /^הודעת /i, /^משלוח /i,
+    /^Send /i, /^Print /i, /^Notify /i,
+];
+const PHYSICAL_VERB_PREFIXES = [
+    /^ביצוע /i, /^הכנת /i, /^ספירת /i, /^מסירת /i,
+    /^תשלום ב/i, /^Perform /i, /^Execute /i,
+];
+const UNSAFE_WF = [
+    /<script\b/i, /\son\w+\s*=/i, /<iframe\b/i,
+    /src\s*=\s*["']https?:/i, /href\s*=\s*["']https?:/i,
+    /@import\b/i, /<style\b/i,
+];
+function wireframeSafe(html) {
+    return !UNSAFE_WF.some(rx => rx.test(html));
+}
+// ── Main validator ────────────────────────────────────────────────────────
+export function parseAndValidate(jsonText) {
+    let raw;
+    try {
+        raw = JSON.parse(jsonText);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, warnings: [], issues: [{ path: "(root)", code: "invalid-json", message: `JSON parse failed: ${msg}` }] };
+    }
+    const errors = [];
+    const warnings = [];
+    const err = (path, code, message) => errors.push({ path, code, message });
+    const warn = (path, code, message) => warnings.push({ path, code, message });
+    const m = raw;
+    if (!m || typeof m !== "object") {
+        err("(root)", "not-object", "model must be an object");
+        return { ok: false, issues: errors, warnings };
+    }
+    if (m["kind"] !== "use-case")
+        err("kind", "wrong-kind", `expected "use-case", got "${m["kind"]}"`);
+    const parts = Array.isArray(m["parts"]) ? m["parts"] : [];
+    if (!Array.isArray(m["parts"]) || parts.length === 0)
+        err("parts", "missing-parts", "parts array is required and must be non-empty");
+    // Narrative field checks at model level
+    for (const [key, val] of [["assumptions", m["assumptions"]], ["openQuestions", m["openQuestions"]]]) {
+        if (Array.isArray(val)) {
+            val.forEach((item, i) => {
+                if (typeof item === "string" && item.length > 0 && !hasHebrew(item)) {
+                    err(`${key}[${i}]`, "narrative-non-hebrew", `${key}[${i}] contains no Hebrew characters`);
+                }
+            });
+        }
+    }
+    for (const [pi, part] of parts.entries()) {
+        const pp = `parts[${pi}]`;
+        const elements = Array.isArray(part["elements"]) ? part["elements"] : [];
+        const relationships = Array.isArray(part["relationships"]) ? part["relationships"] : [];
+        const actorIds = new Set();
+        const ucIds = new Set();
+        // Index actors and UCs
+        for (const el of elements) {
+            if (el["kind"] === "actor" && typeof el["id"] === "string")
+                actorIds.add(el["id"]);
+            if (el["kind"] === "useCase" && typeof el["id"] === "string")
+                ucIds.add(el["id"]);
+        }
+        // Build relationship indexes
+        const includesByTarget = new Map(); // targetUcId → [baseUcId...]
+        const assocsByUc = new Map(); // ucId → [actorId...]
+        const includeSet = new Set(); // "from:to"
+        let totalIncludeExtend = 0;
+        for (const rel of relationships) {
+            if (rel["kind"] === "include") {
+                const from = String(rel["from"] ?? ""), to = String(rel["to"] ?? "");
+                const list = includesByTarget.get(to) ?? [];
+                list.push(from);
+                includesByTarget.set(to, list);
+                includeSet.add(`${from}:${to}`);
+                totalIncludeExtend++;
+            }
+            if (rel["kind"] === "extend")
+                totalIncludeExtend++;
+            if (rel["kind"] === "actorAssoc") {
+                const ucId = String(rel["ucId"] ?? ""), actorId = String(rel["actorId"] ?? "");
+                const list = assocsByUc.get(ucId) ?? [];
+                list.push(actorId);
+                assocsByUc.set(ucId, list);
+            }
+        }
+        if (totalIncludeExtend > 2)
+            warn(`${pp}.relationships`, "too-many-include-extend", `${totalIncludeExtend} include+extend relationships found — more than 2 is almost always wrong`);
+        // Check «include» targets
+        for (const [targetId, bases] of includesByTarget) {
+            if (bases.length < 2) {
+                err(`${pp}.relationships[include→${targetId}]`, "single-incoming-include", `UC "${targetId}" has exactly one incoming «include» (from "${bases[0]}") — fold it into the parent instead`);
+            }
+            if (assocsByUc.has(targetId)) {
+                err(`${pp}.relationships[include→${targetId}]`, "include-target-has-assoc", `UC "${targetId}" is an «include» target but also has direct actor associations — it cannot be both`);
+            }
+        }
+        // Check UC elements
+        for (const el of elements) {
+            if (el["kind"] !== "useCase")
+                continue;
+            const id = String(el["id"] ?? "");
+            const name = String(el["name"] ?? "");
+            const ePath = `${pp}.elements[id=${id}]`;
+            // Send-only check
+            if (SEND_ONLY_PREFIXES.some(rx => rx.test(name))) {
+                err(ePath, "send-only-uc", `UC "${id}" name "${name}" appears to be send-only — fold the send step into the UC that decided to send`);
+            }
+            // Physical verb check
+            if (PHYSICAL_VERB_PREFIXES.some(rx => rx.test(name))) {
+                warn(ePath, "physical-verb", `UC "${id}" name "${name}" uses a physical verb — wrap with a system verb (רישום, הזנה, עדכון, סימון…)`);
+            }
+            // Primary actor
+            const primaryActor = el["primaryActor"];
+            if (!primaryActor) {
+                err(ePath, "missing-primary-actor", `UC "${id}" has no primaryActor`);
+            }
+            else {
+                if (!actorIds.has(primaryActor)) {
+                    err(ePath, "unknown-primary-actor", `UC "${id}" primaryActor "${primaryActor}" is not in actors list`);
+                }
+                // Check that an actorAssoc with role=initiator exists for this actor↔UC pair
+                const initiatorAssoc = relationships.find(r => r["kind"] === "actorAssoc" && r["ucId"] === id && r["actorId"] === primaryActor && r["role"] === "initiator");
+                if (!initiatorAssoc) {
+                    err(ePath, "primary-not-initiator", `UC "${id}" primaryActor "${primaryActor}" has no actorAssoc with role="initiator"`);
+                }
+            }
+            // Narrative fields — must contain Hebrew
+            for (const [key, val] of [["description", el["description"]]]) {
+                if (typeof val === "string" && val.length > 0 && !hasHebrew(val)) {
+                    err(`${ePath}.${key}`, "narrative-non-hebrew", `${key} contains no Hebrew characters`);
+                }
+            }
+            for (const [key, arr] of [["preconditions", el["preconditions"]], ["postconditions", el["postconditions"]]]) {
+                if (!Array.isArray(arr) || arr.length === 0) {
+                    warn(`${ePath}.${key}`, `missing-${key}`, `UC "${id}" has no ${key}`);
+                }
+                else {
+                    arr.forEach((item, i) => {
+                        if (typeof item === "string" && item.length > 0 && !hasHebrew(item)) {
+                            err(`${ePath}.${key}[${i}]`, "narrative-non-hebrew", `${key}[${i}] contains no Hebrew characters`);
+                        }
+                    });
+                }
+            }
+            // User stories
+            const userStories = Array.isArray(el["userStories"]) ? el["userStories"] : [];
+            if (userStories.length < 2) {
+                warn(`${ePath}.userStories`, "few-user-stories", `UC "${id}" has ${userStories.length} user stor${userStories.length === 1 ? "y" : "ies"} — cover every distinct stakeholder goal`);
+            }
+            // Scenarios / flow steps
+            const scenarios = Array.isArray(el["scenarios"]) ? el["scenarios"] : [];
+            if (scenarios.length === 0) {
+                err(`${ePath}.scenarios`, "missing-scenarios", `UC "${id}" has no scenarios`);
+            }
+            for (const [si, sce] of scenarios.entries()) {
+                const sPath = `${ePath}.scenarios[${si}]`;
+                const flow = Array.isArray(sce["flow"]) ? sce["flow"] : [];
+                if (flow.length === 0) {
+                    err(`${sPath}.flow`, "empty-flow", `scenario "${sce["id"]}" in UC "${id}" has no flow steps`);
+                }
+                const flowLen = flow.length;
+                for (const [fi, step] of flow.entries()) {
+                    const stepPath = `${sPath}.flow[${fi}]`;
+                    if (step["kind"] === "actor" && typeof step["actor"] === "string" && !actorIds.has(step["actor"])) {
+                        err(stepPath, "unknown-actor-ref", `flow step references unknown actor id "${step["actor"]}"`);
+                    }
+                    if (step["kind"] === "include") {
+                        const targetUc = String(step["uc"] ?? "");
+                        if (!ucIds.has(targetUc)) {
+                            err(stepPath, "unknown-uc-ref", `«include» step references unknown UC id "${targetUc}"`);
+                        }
+                        else if (!includeSet.has(`${id}:${targetUc}`)) {
+                            err(stepPath, "include-step-no-relationship", `«include» step references "${targetUc}" but no include relationship exists from "${id}" to "${targetUc}"`);
+                        }
+                    }
+                    if (typeof step["text"] === "string" && step["text"].length > 0 && !hasHebrew(step["text"])) {
+                        err(stepPath, "narrative-non-hebrew", "flow step text contains no Hebrew characters");
+                    }
+                }
+                const extensions = Array.isArray(sce["extensions"]) ? sce["extensions"] : [];
+                for (const [ei, ext] of extensions.entries()) {
+                    const extPath = `${sPath}.extensions[${ei}]`;
+                    if (typeof ext["at"] === "number" && (ext["at"] < 1 || ext["at"] > flowLen)) {
+                        err(extPath, "invalid-extension-at", `extension "at" value ${ext["at"]} is out of range (flow has ${flowLen} steps)`);
+                    }
+                    if (typeof ext["text"] === "string" && ext["text"].length > 0 && !hasHebrew(ext["text"])) {
+                        err(extPath, "narrative-non-hebrew", "extension text contains no Hebrew characters");
+                    }
+                }
+            }
+            // Wireframe safety (only when present and non-empty)
+            if (typeof el["wireframe"] === "string" && el["wireframe"].length > 0) {
+                if (!wireframeSafe(el["wireframe"])) {
+                    err(`${ePath}.wireframe`, "unsafe-wireframe", `wireframe for UC "${id}" contains forbidden patterns (script/on*/iframe/external URL/@import/style)`);
+                }
+                if (!hasHebrew(el["wireframe"])) {
+                    err(`${ePath}.wireframe`, "wireframe-non-hebrew", `wireframe for UC "${id}" contains no Hebrew characters`);
+                }
+            }
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, issues: errors, warnings };
+    return { ok: true, warnings };
+}

package/dist/usecase/index.d (DESKTOP-GQHOSST's conflicted copy 2026-04-19).ts

@@ -0,0 +1,15 @@
+export interface ValidationIssue {
+    path: string;
+    code: string;
+    message: string;
+}
+export type ValidateResult = {
+    ok: true;
+    warnings: ValidationIssue[];
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+    warnings: ValidationIssue[];
+};
+export declare function formatIssues(issues: ValidationIssue[]): string;
+export declare function parseAndValidate(jsonText: string): ValidateResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sad-mcp",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "MCP server for Software Analysis and Design course materials at BGU",
   "type": "module",
   "bin": {

package/skills/uml-use-case-diagram/SKILL.md

@@ -272,8 +272,14 @@ const diagramLayout = {
 
 ### fixLayout implementation
 
+`fixLayout`, its constants, and all other runtime functions are provided by
+`https://themathbible.com/sad-mcp/uc-diagram-common.js` — **do not inline them**.
+The HTML `<script>` block must contain only the diagram-specific data objects
+(`diagramLayouts`, `actorDescriptions`, `assocDescriptions`, `useCaseDocs`, `diagramModel`).
+
+The function signature and constants for reference (implementation is external):
+
 ```javascript
-// Named constants — tune these, do not hardcode magic numbers elsewhere.
 const HEADER_H  = 44;   // boundary header height
 const UC_PAD    = 30;   // min gap from boundary edge to nearest UC edge
 const UC_GAP    = 14;   // min gap between UC ellipses in the same column
@@ -439,13 +445,6 @@ function fixLayout(layout) {
 </div>
 ```
 
-```css
-.fix-btn { padding: 8px 20px; border: 1px solid #3b82f6; background: #eff6ff;
-  color: #1e40af; font-size: 12px; font-weight: 600; cursor: pointer;
-  border-radius: 6px; font-family: 'Noto Sans Hebrew', sans-serif; }
-.fix-btn:hover { background: #dbeafe; }
-```
-
 ---
 
 ## 7. Splitting Into Multiple Diagrams
@@ -495,7 +494,11 @@ function showDesc(id, type, event) {
 }
 ```
 
-### 8b. Small popup for actors and associations
+All popup and modal functions (`showDesc`, `showPopup`, `hideDesc`, `openUcModal`,
+`closeUcModal`, `pulseActor`, `wireframeSafe`) are provided by
+`uc-diagram-common.js` — **do not inline them**.
+
+### 8b. Data objects for popups (inline in the HTML `<script>` block)
 
 ```javascript
 const actorDescriptions = {
@@ -503,48 +506,16 @@ const actorDescriptions = {
   // ... one entry per actor
 };
 const assocDescriptions = {
-  // keyed by connection id; name = actor-name ↔ UC-name (auto-composed is fine)
+  // keyed by connection id; name = actor-name ↔ UC-name
   'a1': { name: 'לקוח ↔ פתיחת הזמנה', desc: 'הלקוח יוזם את פתיחת ההזמנה. תפקיד: Initiator.' },
   // ... one entry per association line you want described
 };
-
-function showPopup(id, type, event) {
-  hideDesc();
-  const data = type === 'actor' ? actorDescriptions[id]
-             : type === 'assoc' ? assocDescriptions[id]
-             : null;
-  if (!data) return;
-  const panel = document.createElement('div');
-  panel.id = 'desc-panel';
-  panel.innerHTML = `
-    <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:6px;">
-      <strong style="font-size:12px;color:#1e40af;direction:rtl;">${data.name}</strong>
-      <span onclick="hideDesc()" style="cursor:pointer;color:#94a3b8;font-size:18px;line-height:1;margin-right:6px;">×</span>
-    </div>
-    <div style="font-size:11px;color:#334155;line-height:1.6;direction:rtl;">${data.desc}</div>`;
-  Object.assign(panel.style, {
-    position:'fixed', background:'#fff', border:'1.5px solid #2980b9',
-    borderRadius:'8px', padding:'12px 16px', maxWidth:'300px',
-    boxShadow:'0 4px 14px rgba(0,0,0,.15)', zIndex:'1000',
-    left: event.clientX + 'px', top: event.clientY + 'px'
-  });
-  document.body.appendChild(panel);
-  const r = panel.getBoundingClientRect();
-  if (r.right  > window.innerWidth)  panel.style.left = (window.innerWidth  - r.width  - 10) + 'px';
-  if (r.bottom > window.innerHeight) panel.style.top  = (event.clientY - r.height - 10) + 'px';
-  event.stopPropagation();
-}
-function hideDesc() { document.getElementById('desc-panel')?.remove(); }
-document.addEventListener('click', e => {
-  if (!e.target.closest('[data-uc-id]') &&
-      !e.target.closest('[data-actor-id]') &&
-      !e.target.closest('[data-conn-id]')) hideDesc();
-});
 ```
 
-### 8a. Full-screen modal for UCs
+### 8a. useCaseDocs data object (inline in the HTML `<script>` block)
 
-Every UC ellipse's click routes to `openUcModal(id)`, which reads `useCaseDocs[id]` (populated from the §4.4 documentation blocks) and renders a full-screen modal with the complete UC spec. The modal has sections for: header (id + name + primary actor link), description, scenarios (numbered flow with typed steps + extensions), a row with preconditions / postconditions / user stories, and an optional wireframe.
+`openUcModal(id)` reads `useCaseDocs[id]` and renders a full-screen modal with
+the complete UC spec. Populate one entry per UC:
 
 ```javascript
 const useCaseDocs = {
@@ -559,10 +530,10 @@ const useCaseDocs = {
     scenarios: [
       { id: 'sc-happy', name: 'מסלול מרכזי',
         flow: [
-          { kind: 'actor',   actor: 'customer',      text: 'בוחר פריט מהקטלוג' },
-          { kind: 'system',                          text: 'מוסיף את הפריט לעגלה' },
-          { kind: 'include', uc:    'uc-authenticate', text: '' },
-          { kind: 'actor',   actor: 'customer',      text: 'מאשר את ההזמנה' }
+          { kind: 'actor',   actor: 'customer',        text: 'בוחר פריט מהקטלוג' },
+          { kind: 'system',                            text: 'מוסיף את הפריט לעגלה' },
+          { kind: 'include', uc: 'uc-authenticate',    text: '' },
+          { kind: 'actor',   actor: 'customer',        text: 'מאשר את ההזמנה' }
         ],
         extensions: [
           { at: 1, text: 'אם הפריט אזל במלאי — מציג הודעה וחוזר לשלב 1.' }
@@ -576,130 +547,6 @@ const useCaseDocs = {
   }
   // ... one entry per UC
 };
-
-function openUcModal(id) {
-  const doc = useCaseDocs[id];
-  if (!doc) return;
-  const actorName = aid => (actorDescriptions[aid]?.name) || aid;
-  const ucName    = uid => (useCaseDocs[uid]?.name) || uid;
-  const modal = document.getElementById('uc-modal');
-  modal.querySelector('.uc-id').textContent       = doc.id;
-  modal.querySelector('.uc-name').textContent     = doc.name;
-  const paLink = modal.querySelector('.uc-primary-link');
-  paLink.textContent  = actorName(doc.primaryActor);
-  paLink.dataset.actorId = doc.primaryActor;
-  paLink.onclick = () => { closeUcModal(); pulseActor(doc.primaryActor); };
-
-  modal.querySelector('.uc-description').textContent = doc.description || '';
-
-  // Scenarios
-  const sc = modal.querySelector('.uc-scenarios');
-  sc.innerHTML = '';
-  (doc.scenarios || []).forEach(sce => {
-    const h = document.createElement('h3'); h.textContent = sce.name || sce.id; sc.appendChild(h);
-    const ol = document.createElement('ol');
-    (sce.flow || []).forEach((step, i) => {
-      const li = document.createElement('li');
-      if (step.kind === 'actor') {
-        const strong = document.createElement('strong');
-        strong.className = 'step-actor';
-        strong.dataset.actorId = step.actor;
-        strong.textContent = actorName(step.actor);
-        strong.onclick = () => { closeUcModal(); pulseActor(step.actor); };
-        li.appendChild(strong);
-        li.appendChild(document.createTextNode(': ' + (step.text || '')));
-      } else if (step.kind === 'system') {
-        const em = document.createElement('em');
-        em.className = 'step-system'; em.textContent = 'המערכת';
-        li.appendChild(em);
-        li.appendChild(document.createTextNode(': ' + (step.text || '')));
-      } else if (step.kind === 'include') {
-        const span = document.createElement('span');
-        span.className = 'step-include'; span.textContent = '«include» ';
-        const a = document.createElement('a');
-        a.className = 'step-uc-ref'; a.textContent = ucName(step.uc);
-        a.onclick = () => openUcModal(step.uc);
-        li.appendChild(span); li.appendChild(a);
-        if (step.text) li.appendChild(document.createTextNode(' — ' + step.text));
-      } else if (step.kind === 'extension') {
-        li.className = 'ext-inline';
-        li.textContent = (step.at ? step.at + 'a. ' : '') + (step.text || '');
-      }
-      ol.appendChild(li);
-      // Inline extensions defined in sce.extensions anchored to this step number:
-      (sce.extensions || []).filter(e => e.at === i + 1).forEach((ext, j) => {
-        const sub = document.createElement('li');
-        sub.className = 'ext-sub';
-        const letter = String.fromCharCode(97 + j);  // a, b, c, ...
-        sub.textContent = (i + 1) + letter + '. ' + ext.text;
-        ol.appendChild(sub);
-      });
-    });
-    sc.appendChild(ol);
-  });
-
-  const fillList = (selector, items) => {
-    const el = modal.querySelector(selector);
-    el.innerHTML = '';
-    (items || []).forEach(s => { const li = document.createElement('li'); li.textContent = s; el.appendChild(li); });
-  };
-  fillList('.uc-pre ul',    doc.preconditions);
-  fillList('.uc-post ul',   doc.postconditions);
-  const usList = modal.querySelector('.uc-stories ul');
-  usList.innerHTML = '';
-  (doc.userStories || []).forEach(us => {
-    const li = document.createElement('li');
-    li.textContent = `As a ${us.role}, I want ${us.want}, so that ${us.so}`;
-    usList.appendChild(li);
-  });
-
-  // Wireframe — safety-checked before insertion
-  const wf = modal.querySelector('.uc-wireframe');
-  wf.innerHTML = '';
-  if (doc.wireframe && wireframeSafe(doc.wireframe)) {
-    wf.innerHTML = doc.wireframe;
-    wf.hidden = false;
-  } else {
-    wf.hidden = true;
-    if (doc.wireframe) console.warn(`Wireframe for ${id} failed safety check.`);
-  }
-
-  modal.hidden = false;
-  document.body.classList.add('uc-modal-open');
-}
-
-function closeUcModal() {
-  const modal = document.getElementById('uc-modal');
-  modal.hidden = true;
-  document.body.classList.remove('uc-modal-open');
-}
-
-// Esc closes the modal.
-document.addEventListener('keydown', e => {
-  if (e.key === 'Escape') closeUcModal();
-});
-
-// Highlight an actor on the diagram for ~2s.
-function pulseActor(actorId) {
-  const g = document.getElementById('actor-group-' + actorId);
-  if (!g) return;
-  g.classList.add('actor-pulse');
-  setTimeout(() => g.classList.remove('actor-pulse'), 2000);
-}
-
-// Wireframe sanity check — see §WF. Rejects scripts, event handlers, external URLs.
-function wireframeSafe(html) {
-  const forbidden = [
-    /<script\b/i,
-    /\son\w+\s*=/i,
-    /<iframe\b/i,
-    /src\s*=\s*["']https?:/i,
-    /href\s*=\s*["']https?:/i,
-    /@import\b/i,
-    /<style\b/i
-  ];
-  return !forbidden.some(rx => rx.test(html));
-}
 ```
 
 UC group: `<g id="uc-uc1" data-uc-id="uc1" onclick="showDesc('uc1','uc',event)" style="cursor:pointer">`
@@ -742,46 +589,10 @@ Associations without a meaningful description (e.g., auto-generated from trivial
 
 ### Timing labels on cron/time-actor associations (required)
 
-When a connection carries a `timing` field (every connection from a system-time actor MUST have one — see §2), inject the label at the line midpoint **after** `fixLayout` has written the endpoints. The helper below is idempotent: it removes any existing `.timing-label` group before re-rendering, so calling it again after another `fixLayout` pass is safe.
-
-```javascript
-function renderTimingLabels(layout) {
-  const svg = document.getElementById(layout.svgId);
-  if (!svg) return;
-  svg.querySelectorAll('.timing-label').forEach(el => el.remove());
-  const NS = 'http://www.w3.org/2000/svg';
-  (layout.connections || []).forEach(conn => {
-    if (!conn.timing) return;
-    const line = svg.querySelector(
-      `[data-conn-from="${conn.from}"][data-conn-to="${conn.to}"]`);
-    if (!line) return;
-    const x1 = +line.getAttribute('x1'), y1 = +line.getAttribute('y1');
-    const x2 = +line.getAttribute('x2'), y2 = +line.getAttribute('y2');
-    const mx = (x1 + x2) / 2, my = (y1 + y2) / 2;
-    const w = 10 + conn.timing.length * 7, h = 16;
-    const g = document.createElementNS(NS, 'g');
-    g.setAttribute('class', 'timing-label');
-    const rect = document.createElementNS(NS, 'rect');
-    rect.setAttribute('x', mx - w / 2); rect.setAttribute('y', my - h / 2);
-    rect.setAttribute('width', w);      rect.setAttribute('height', h);
-    rect.setAttribute('fill', 'white'); rect.setAttribute('stroke', '#334155');
-    rect.setAttribute('stroke-width', '0.8'); rect.setAttribute('rx', '3');
-    const text = document.createElementNS(NS, 'text');
-    text.setAttribute('x', mx); text.setAttribute('y', my + 4);
-    text.setAttribute('font-size', '10'); text.setAttribute('text-anchor', 'middle');
-    text.setAttribute('fill', '#334155');
-    text.setAttribute('font-family', "'Noto Sans Hebrew', sans-serif");
-    text.setAttribute('direction', 'rtl');
-    text.textContent = conn.timing;
-    g.appendChild(rect); g.appendChild(text);
-    svg.appendChild(g);
-  });
-}
-```
-
-Call `renderTimingLabels(layout)` at the end of every `fixLayout` invocation, **and** on `DOMContentLoaded` (after the initial `fixLayout`). Add it inside `showDiagram(index)` too so the label tracks the active tab.
+`renderTimingLabels(layout)` is provided by `uc-diagram-common.js` — do not inline it.
+It is called automatically at the end of every `fixLayout` invocation.
 
-The `connections` entry for a timed link looks like:
+Every connection from a system-time actor MUST carry a `timing` field:
 
 ```javascript
 { from: 'cron', to: 'uc-daily-reconcile', type: 'association', timing: 'פעם ביום' }
@@ -789,15 +600,15 @@ The `connections` entry for a timed link looks like:
 
 ---
 
-## §WF. Wireframe Authoring (Mandatory for Human-Initiated UCs)
+## §WF. Wireframe Authoring (Opt-In)
 
-**A wireframe is required for every UC whose `primaryActor.actorType === 'human'`.** The user sees a screen; a use case without a visual mock of that screen is incomplete documentation. The validator (§12) errors on any human-initiated UC missing a wireframe.
+**Wireframes are generated only when the user explicitly requests them** (e.g., "add wireframes", "include UI mocks"). Do not generate wireframes unless asked — they significantly increase generation time.
 
-Wireframe is **optional** (and usually omitted) only for:
+When wireframes are requested, generate them only for UCs whose `primaryActor.actorType === 'human'`. Skip wireframes for:
 - UCs whose primary actor is a system or cron (`actorType: 'system'`) — no human sees a screen.
 - Pure include-target UCs (sub-behaviors with no actor association).
 
-For every other UC, emit a wireframe as an inline HTML fragment and attach it to `useCaseDocs[ucId].wireframe`. The modal renderer (§8a) injects the fragment after passing a safety check (see `wireframeSafe()` in §8a).
+When generated, emit a wireframe as an inline HTML fragment and attach it to `useCaseDocs[ucId].wireframe`. The modal renderer (§8a) injects the fragment after passing a safety check (see `wireframeSafe()` in §8a).
 
 Claude authors the wireframe using its own UI-generation judgment — there is no DSL. But the skill enforces a consistent look and safe sandbox via a scoped CSS theme and a set of forbidden patterns.
 
@@ -915,107 +726,9 @@ Assumptions li:     #334155, 12px, line-height 1.6, list-style disc inside
 Fonts:              'Noto Sans Hebrew' + 'IBM Plex Mono' from Google Fonts
 ```
 
-The assumptions panel CSS must be included in the HTML `<style>` block:
-
-```css
-.assumptions-panel { display: flex; gap: 24px; max-width: 1000px;
-  margin: 20px auto; padding: 16px 20px; background: #fff;
-  border: 1px solid #cbd5e1; border-radius: 8px; direction: rtl; }
-.assumptions-col { flex: 1; min-width: 0; }
-.assumptions-col h3 { margin: 0 0 6px; font-size: 13px; font-weight: 600;
-  color: #1e40af; }
-.assumptions-col ul { margin: 0; padding-right: 18px; }
-.assumptions-col li { color: #334155; font-size: 12px; line-height: 1.6; }
-```
-
-### v2 — UC modal styling
-
-```css
-/* Lock body scroll while the modal is open */
-body.uc-modal-open { overflow: hidden; }
-
-.uc-modal { position: fixed; inset: 0; z-index: 2000; display: flex;
-  align-items: flex-start; justify-content: center; padding: 40px 20px;
-  overflow-y: auto; direction: rtl;
-  font-family: 'Noto Sans Hebrew', sans-serif; }
-.uc-modal-backdrop { position: absolute; inset: 0; background: rgba(15, 23, 42, 0.55); }
-.uc-modal-body { position: relative; z-index: 1; width: 100%; max-width: 960px;
-  background: #fff; border-radius: 12px; box-shadow: 0 10px 40px rgba(0,0,0,.25);
-  padding: 28px 32px 32px; color: #1e293b; }
-.uc-modal-close { position: absolute; top: 10px; left: 14px; background: none;
-  border: none; font-size: 24px; color: #64748b; cursor: pointer; }
-.uc-modal-body header { border-bottom: 1px solid #e2e8f0; padding-bottom: 12px;
-  margin-bottom: 18px; }
-.uc-modal-body .uc-id { display: inline-block; font-family: 'IBM Plex Mono',monospace;
-  font-size: 11px; color: #64748b; background: #f1f5f9; padding: 2px 8px;
-  border-radius: 4px; margin-bottom: 6px; }
-.uc-modal-body .uc-name { margin: 0 0 4px; font-size: 20px; color: #1e40af; font-weight: 700; }
-.uc-modal-body .uc-primary { font-size: 13px; color: #334155; }
-.uc-modal-body .uc-primary-label { color: #64748b; margin-left: 6px; }
-.uc-modal-body .uc-primary-link { color: #1e40af; cursor: pointer; font-weight: 600;
-  text-decoration: underline dotted; }
-.uc-description { margin-bottom: 20px; font-size: 14px; line-height: 1.7; color: #334155; }
-
-.uc-scenarios h3 { font-size: 14px; color: #1e40af; margin: 18px 0 6px;
-  border-right: 3px solid #3b82f6; padding-right: 10px; }
-.uc-scenarios ol { margin: 0 0 14px; padding-right: 22px; }
-.uc-scenarios ol li { color: #1e293b; font-size: 13px; line-height: 1.9; }
-.step-actor { color: #1e40af; font-weight: 600; cursor: pointer; text-decoration: underline dotted; }
-.step-system { color: #475569; font-style: italic; }
-.step-include { color: #7c3aed; font-family: 'IBM Plex Mono', monospace; font-size: 11px; }
-.step-uc-ref { color: #7c3aed; cursor: pointer; text-decoration: underline; }
-.ext-inline, .ext-sub { list-style: none; color: #64748b; font-size: 12px;
-  padding-right: 24px; line-height: 1.7; }
-
-.uc-prepostuser { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 18px;
-  margin: 18px 0 20px; }
-.uc-prepostuser > div { background: #f8fafc; border: 1px solid #e2e8f0;
-  border-radius: 8px; padding: 12px 14px; }
-.uc-prepostuser h4 { margin: 0 0 6px; font-size: 12px; color: #1e40af; font-weight: 600; }
-.uc-prepostuser ul { margin: 0; padding-right: 18px; font-size: 12px;
-  color: #334155; line-height: 1.7; }
-
-.uc-wireframe { border-top: 1px dashed #cbd5e1; padding-top: 16px; margin-top: 6px; }
-.uc-wireframe:empty, .uc-wireframe[hidden] { display: none; }
-
-/* Actor pulse animation used by pulseActor() */
-.actor-pulse { animation: actor-pulse 0.6s ease-in-out 3; }
-@keyframes actor-pulse {
-  0%, 100% { filter: none; }
-  50%      { filter: drop-shadow(0 0 8px #3b82f6); }
-}
-```
+All styles are in `https://themathbible.com/sad-mcp/uc-diagram-common.css` — **do not add a `<style>` block**. Do not inline any CSS.
 
-### v2 — Wireframe scoped theme
-
-```css
-.wf-screen { background: #f8fafc; border: 1px solid #cbd5e1; border-radius: 8px;
-  padding: 18px 20px; font-family: 'Noto Sans Hebrew', sans-serif;
-  color: #1e293b; direction: rtl; max-width: 760px; margin: 0 auto; }
-.wf-heading { margin: 0 0 14px; font-size: 15px; color: #1e40af; font-weight: 700;
-  border-bottom: 1px solid #e2e8f0; padding-bottom: 6px; }
-.wf-section { margin: 14px 0; }
-.wf-row { display: flex; gap: 10px; align-items: center; margin: 6px 0; }
-.wf-label { font-size: 12px; color: #475569; min-width: 120px; }
-.wf-input, .wf-textarea, .wf-select { flex: 1; background: #fff;
-  border: 1px solid #cbd5e1; border-radius: 4px; padding: 6px 8px;
-  font-size: 12px; color: #334155; }
-.wf-textarea { min-height: 60px; }
-.wf-table { width: 100%; border-collapse: collapse; margin: 10px 0; font-size: 12px; }
-.wf-table th, .wf-table td { border: 1px solid #cbd5e1; padding: 6px 8px;
-  text-align: right; }
-.wf-table th { background: #e2e8f0; color: #1e40af; font-weight: 600; }
-.wf-actions { display: flex; gap: 8px; margin-top: 12px; justify-content: flex-start; }
-.wf-button { background: #fff; border: 1px solid #64748b; border-radius: 4px;
-  padding: 6px 14px; font-size: 12px; color: #334155; cursor: default; }
-.wf-primary { background: #1e40af; color: #fff; border-color: #1e40af; }
-.wf-image-box { border: 1px dashed #94a3b8; background: #f1f5f9; color: #64748b;
-  text-align: center; padding: 24px; border-radius: 4px; font-size: 12px;
-  margin: 10px 0; }
-.wf-hint { font-size: 11px; color: #64748b; font-style: italic; margin: 6px 0; }
-.wf-badge { display: inline-block; background: #e0f2fe; color: #0369a1;
-  padding: 2px 8px; border-radius: 999px; font-size: 10px; font-weight: 600; }
-```
+Available wireframe classes (for §WF): `wf-screen`, `wf-heading`, `wf-row`, `wf-label`, `wf-input`, `wf-textarea`, `wf-select`, `wf-button`, `wf-primary`, `wf-actions`, `wf-table`, `wf-image-box`, `wf-hint`, `wf-section`, `wf-badge`.
 
 ---
 
@@ -1028,7 +741,7 @@ body.uc-modal-open { overflow: hidden; }
   <meta charset="UTF-8">
   <title>[System] — Use Case Diagram</title>
   <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+Hebrew:wght@400;600&family=IBM+Plex+Mono:wght@400;700&display=swap" rel="stylesheet">
-  <style>/* tab bar, fix-btn, body layout */</style>
+  <link href="https://themathbible.com/sad-mcp/uc-diagram-common.css" rel="stylesheet">
 </head>
 <body>
   <!-- Tab bar (only when split) -->
@@ -1040,7 +753,7 @@ body.uc-modal-open { overflow: hidden; }
   <!-- Split rationale (only when split) -->
   <div class="split-rationale">Split by UC count: N UCs &gt; 8 threshold</div>
 
-  <!-- Fix Layout button (above each diagram) -->
+  <!-- Fix Layout button -->
   <div style="text-align:center;margin:8px 0;">
     <button onclick="fixLayout(currentLayout())" class="fix-btn">Fix Layout</button>
   </div>
@@ -1056,104 +769,44 @@ body.uc-modal-open { overflow: hidden; }
     <svg id="diagram-svg-1" viewBox="0 0 1100 900" xmlns="http://www.w3.org/2000/svg">...</svg>
   </div>
 
-  <!-- Assumptions / open-questions panel (render only if at least one non-empty) -->
+  <!-- Assumptions / open-questions panel -->
   <div id="assumptions-panel" class="assumptions-panel" hidden>
     <div class="assumptions-col" id="assumptions-col">
-      <h3>הנחות</h3>
-      <ul id="assumptions-list"></ul>
+      <h3>הנחות</h3><ul id="assumptions-list"></ul>
     </div>
     <div class="assumptions-col" id="open-questions-col">
-      <h3>שאלות פתוחות</h3>
-      <ul id="open-questions-list"></ul>
+      <h3>שאלות פתוחות</h3><ul id="open-questions-list"></ul>
     </div>
   </div>
 
-  <!-- v2 — UC modal (populated by openUcModal; hidden by default) -->
+  <!-- UC modal (body is populated by openUcModal in common.js; starts empty) -->
   <div id="uc-modal" class="uc-modal" hidden role="dialog" aria-modal="true">
     <div class="uc-modal-backdrop" onclick="closeUcModal()"></div>
-    <div class="uc-modal-body">
-      <button class="uc-modal-close" onclick="closeUcModal()" aria-label="Close">×</button>
-      <header>
-        <span class="uc-id"></span>
-        <h2 class="uc-name"></h2>
-        <div class="uc-primary">
-          <span class="uc-primary-label">שחקן ראשי:</span>
-          <a class="uc-primary-link"></a>
-        </div>
-      </header>
-      <section class="uc-description"></section>
-      <section class="uc-scenarios"></section>
-      <section class="uc-prepostuser">
-        <div class="uc-pre"><h4>תנאים מוקדמים</h4><ul></ul></div>
-        <div class="uc-post"><h4>תנאים סופיים</h4><ul></ul></div>
-        <div class="uc-stories"><h4>סיפורי משתמש</h4><ul></ul></div>
-      </section>
-      <section class="uc-wireframe" hidden></section>
-    </div>
+    <div class="uc-modal-body"></div>
   </div>
 
   <!-- VP export button -->
   <button class="vp-export-btn" onclick="exportXMI()">Download .xmi (Visual Paradigm)</button>
 
+  <!-- DIAGRAM DATA ONLY — all functions are in uc-diagram-common.js.
+       Use var (NOT const/let) so these become window properties accessible from the external script.
+       Do NOT add activeTab, currentLayout, showDiagram, exportXMI, xmlEscape, downloadFile,
+       or any DOMContentLoaded handler here — they all live in uc-diagram-common.js.
+       Adding let/const variables with the same names as any variable in the external script
+       causes a SyntaxError that silently kills the entire external script. -->
   <script>
-    const diagramLayouts = [ /* one layout object per tab, per §6 */ ];
-    const actorDescriptions   = { /* §8b */ };
-    const assocDescriptions   = { /* §8b */ };
-    const useCaseDocs         = { /* §8a — full v2 per-UC documentation */ };
-    const diagramModel        = { /* model-shape.md, kind: 'use-case' */ };
-
-    let activeTab = 0;
-    function currentLayout() { return diagramLayouts[activeTab]; }
-    function showDiagram(index) {
-      activeTab = index;
-      document.querySelectorAll('.diagram-part').forEach((p, i) => p.hidden = i !== index);
-      document.querySelectorAll('.tab').forEach((t, i) => t.classList.toggle('active', i === index));
-      fixLayout(diagramLayouts[index]);  // idempotent
-    }
-
-    function fixLayout(layout)        { /* §6 */ }
-    function showDesc(id, type, event){ /* §8: routes to openUcModal for UCs, showPopup otherwise */ }
-    function showPopup(id, type, event){ /* §8b */ }
-    function hideDesc()               { /* §8b */ }
-    function openUcModal(id)          { /* §8a */ }
-    function closeUcModal()           { /* §8a */ }
-    function pulseActor(actorId)      { /* §8a */ }
-    function wireframeSafe(html)      { /* §8a / §WF */ }
-    function xmiBody(elements, rels)  { /* export-buttons.md — v2 emits preconditions/postconditions/ownedBehavior */ }
-    function exportXMI()              { /* export-buttons.md */ }
-
-    function renderAssumptions() {
-      const a = (diagramModel && diagramModel.assumptions)   || [];
-      const q = (diagramModel && diagramModel.openQuestions) || [];
-      const panel = document.getElementById('assumptions-panel');
-      if (!panel) return;
-      if (!a.length && !q.length) { panel.hidden = true; return; }
-      panel.hidden = false;
-      const ul = id => document.getElementById(id);
-      const fill = (listEl, items) => {
-        listEl.innerHTML = '';
-        items.forEach(s => {
-          const li = document.createElement('li');
-          li.textContent = s;
-          listEl.appendChild(li);
-        });
-      };
-      fill(ul('assumptions-list'),    a);
-      fill(ul('open-questions-list'), q);
-      document.getElementById('assumptions-col').hidden    = !a.length;
-      document.getElementById('open-questions-col').hidden = !q.length;
-    }
-
-    document.addEventListener('DOMContentLoaded', () => {
-      diagramLayouts.forEach(l => fixLayout(l));
-      renderAssumptions();
-    });
+    var diagramLayouts      = [ /* one layout object per tab, per §6 */ ];
+    var actorDescriptions   = { /* §8b — one entry per actor */ };
+    var assocDescriptions   = { /* §8b — one entry per association line */ };
+    var useCaseDocs         = { /* §8a — full per-UC documentation */ };
+    var diagramModel        = { /* model-shape.md, kind: 'use-case' */ };
   </script>
+  <script src="https://themathbible.com/sad-mcp/uc-diagram-common.js"></script>
 </body>
 </html>
 ```
 
-**Single-tab diagrams still define the full script.** Always emit `diagramLayouts` (one-element array), `activeTab`, `currentLayout()`, **and `showDiagram(index)`**. Only the HTML-level tab bar and the second `.diagram-part` are conditional on splitting. Omitting `showDiagram` is a silent bug: a future edit that adds tabs will have dead onclick handlers with no console error pointing at the cause.
+**Single-tab diagrams still define the full script.** Always emit all five `var` data globals; the tab bar HTML and second `.diagram-part` are the only things conditional on splitting. `showDiagram`, `currentLayout`, `activeTab`, `fixLayout`, `exportXMI` and all other functions live exclusively in `uc-diagram-common.js` — never re-declare them inline.
 
 ---
 
@@ -1177,7 +830,7 @@ The validator runs locally (no API cost) and catches what the §4 and CR gates c
 - Extensions referencing invalid step numbers → ERROR
 - Narrative text missing Hebrew characters (description, preconditions, postconditions, flow/extension text, user stories, assumptions, openQuestions) → ERROR
 - Unsafe wireframe HTML (script / on*= / iframe / external URL / @import / inline style) → ERROR
-- Warnings: fewer than 2 user stories on a UC, no preconditions/postconditions, overall >2 include+extend relationships
+- Warnings: fewer than 2 user stories on a UC, no preconditions/postconditions, overall >2 include+extend relationships, wireframe present on a UC when none were requested
 
 If the response is `✗ Model invalid`, fix every listed error and call the validator again. **Do not write the HTML file until the validator returns `✓ Model valid`.**
 
@@ -1195,7 +848,7 @@ Briefly report: actor count, use case count, include/extend count, whether split
 - [ ] Every `primaryActor` id exists in `actors[]` AND has an association with `role: 'initiator'` on that UC (aligning §4.1 with §4.4).
 - [ ] Every flow step of `kind: 'actor'` references a real actor id; every `kind: 'include'` references a real UC id; every `extension.at` references a valid step number in its scenario's flow.
 - [ ] Clicking a UC on the diagram opens the full-screen modal (§8a); Esc / backdrop click closes it. Step actor/UC references are clickable. Actor popup + association popup (§8b) still work for non-UC clicks.
-- [ ] Every UC whose primary actor is human has a wireframe (§WF). System/cron-initiated UCs and pure include-targets may omit.
+- [ ] Wireframes generated only if the user explicitly requested them (§WF). If generated, only for human-initiated UCs; system/cron and include-targets omitted.
 - [ ] Any `wireframe` HTML passes `wireframeSafe()` (no `<script>`, no `on*=`, no `<iframe>`, no external URLs, no `@import`, no inline `<style>`); all classes are `wf-*` only; visible text is in Hebrew.
 - [ ] Every actor-UC association has a written §4.1 justification block (role, initiates? one-line "why"); every UC has ≥1 association with `initiates = yes`.
 - [ ] Every association line carries a transparent click-hitbox (stroke-width ≥12, `data-conn-id`) wired to `showDesc(id,'assoc',event)`; `assocDescriptions` entry exists for each id.