openplanr 2.4.0 → 2.6.0

package/lib/host-packages/cursor/openplanr/rules/planr-design-review/scripts/runtime/packages/design/templates/studio/enhancements.js

@@ -736,7 +736,7 @@
       await loadPair();
     } catch (error) { status.textContent = error.message; content.append(button('Retry comparison', () => compareRevisions(beforeId, afterId))); }
   }
-  async function handoff() {
+  async function reviewHandoff() {
     const { content, status } = modal('Review handoff', 'design-handoff'); status.textContent = 'Loading review decisions…'; let response;
     const render = () => {
       content.replaceChildren(); const draft = response.draft;
@@ -766,7 +766,11 @@
       catch (error) { status.textContent = error.message; for (const [value,disabled] of previousDisabled) if (value.isConnected) value.disabled = disabled; }
     };
     try { response = await request('loadHandoff', 'handoffUrl'); if (response.metadata) metadata = response.metadata; render(); status.textContent = ''; }
-    catch (error) { status.textContent = error.message; content.append(button('Retry', handoff)); }
+    catch (error) { status.textContent = error.message; content.append(button('Retry', reviewHandoff)); }
+  }
+  function handoff() {
+    if (window.__openPlanrDesignHandoffCenter?.open) return window.__openPlanrDesignHandoffCenter.open();
+    return reviewHandoff();
   }
   async function refreshExperience() {
     const previousContext = JSON.stringify(experience?.reviewContext || payload.reviewContext);
@@ -797,6 +801,19 @@
     on(document, 'openplanr:design-experience-changed', () => { void refreshExperience(); });
     const dispose = () => { disposed = true; activeDialog?.dismiss(); for (const remove of destroyers.splice(0)) remove(); clearTimeout(toastTimer); };
     on(window, 'pagehide', dispose); on(root, 'planr:design-destroy', dispose);
+    window.__openPlanrDesignHandoffBridge = Object.freeze({
+      owner,
+      revision,
+      announce,
+      openReviewHandoff: reviewHandoff,
+      loadReadiness: () => request('loadReadiness', 'readinessUrl'),
+      loadReviewHandoff: () => request('loadHandoff', 'handoffUrl'),
+      updateReviewHandoff: input => request('updateHandoff', 'handoffUrl', { ...input, revision: revision() }),
+      loadImplementationHandoff: () => request('loadImplementationHandoff', 'implementationHandoffUrl'),
+      updateImplementationHandoff: input => request('updateImplementationHandoff', 'implementationHandoffUrl', input),
+      continueToActiveHost: typeof options().continueToPlan === 'function' ? handoff => options().continueToPlan(handoff) : null,
+      context: () => ({ designId: design.id, title: design.title, revision: revision(), host: options().activeHost || options().host || '' }),
+    });
     window.__openPlanrDesignExperience = Object.freeze({ about, profile:editProfile, setTheme, history, compare: compareRevisions, handoff, refresh: refreshExperience, getState: () => ({ railTab, inspectorEnabled, profile:{...profile}, theme:themePreference, metadata: structuredClone(metadata) }) });
   }
   const started = Date.now();

package/lib/host-packages/cursor/openplanr/rules/planr-design-review/scripts/runtime/packages/design/templates/studio/handoff-center.css

@@ -0,0 +1,81 @@
+.design-handoff-center {
+  position:absolute; z-index:42; inset:var(--planr-toolbar-height) 0 0 auto;
+  display:grid; grid-template-rows:auto auto minmax(0,1fr) auto;
+  box-sizing:border-box; width:var(--planr-review-rail-width); max-width:calc(100% - 16px);
+  border-left:1px solid var(--planr-color-rule); background:var(--planr-color-chrome);
+  color:var(--planr-color-text); box-shadow:-12px 0 32px #0004;
+  font:400 var(--design-type-body,14px)/1.5 var(--planr-font-body);
+}
+.design-handoff-center > header { display:flex; align-items:center; justify-content:space-between; gap:12px; min-height:64px; padding:12px 14px; border-bottom:1px solid var(--planr-color-rule); }
+.design-handoff-center h2,.design-handoff-center h3,.design-handoff-center h4 { margin:0; font-family:var(--planr-font-display); }
+.design-handoff-center h2 { font-size:18px; }
+.design-handoff-center h3 { font-size:20px; letter-spacing:-.02em; }
+.design-handoff-center h4 { font-size:14px; }
+.design-handoff-center p { margin:0; overflow-wrap:anywhere; }
+.design-handoff-eyebrow { display:block; color:var(--planr-color-primary); font-size:10px; font-weight:650; letter-spacing:.1em; text-transform:uppercase; }
+.design-handoff-center button,.design-handoff-center input,.design-handoff-center textarea { box-sizing:border-box; font:inherit; }
+.design-handoff-center button { min-height:36px; border:1px solid var(--planr-color-rule); border-radius:6px; padding:8px 10px; color:var(--planr-color-text); background:var(--planr-color-panel); cursor:pointer; }
+.design-handoff-center button:disabled { cursor:wait; opacity:.55; }
+.design-handoff-center button:focus-visible,.design-handoff-center input:focus-visible,.design-handoff-center textarea:focus-visible,.design-handoff-center summary:focus-visible { outline:2px solid var(--planr-color-primary); outline-offset:2px; }
+.design-handoff-center .design-primary { width:100%; min-height:44px; color:var(--planr-color-background); background:var(--planr-color-primary); border-color:transparent; font-weight:650; }
+.design-handoff-center .design-danger { width:100%; color:var(--planr-color-danger); }
+.design-handoff-close { width:44px; height:44px; padding:0!important; background:transparent!important; font-size:22px!important; }
+.design-handoff-progress { display:grid; grid-template-columns:repeat(5,minmax(0,1fr)); gap:2px; padding:8px; border-bottom:1px solid var(--planr-color-rule); overflow-x:auto; }
+.design-handoff-step { display:grid; justify-items:center; gap:3px; min-width:52px; min-height:58px!important; padding:6px 3px!important; border-color:transparent!important; background:transparent!important; color:var(--planr-color-text-muted)!important; font-size:9px!important; line-height:1.2!important; text-align:center; }
+.design-handoff-step > span:first-child { font:650 11px/1 var(--planr-font-body); }
+.design-handoff-step[aria-current="step"] { color:var(--planr-color-text)!important; background:var(--planr-color-raised)!important; border-color:var(--planr-color-rule)!important; }
+.design-handoff-badge { display:inline-flex; align-items:center; gap:4px; width:max-content; max-width:100%; border:1px solid var(--planr-color-rule); border-radius:999px; padding:2px 7px; color:var(--planr-color-text-muted); font-size:10px; font-weight:650; line-height:1.4; }
+.design-handoff-badge::before { content:""; flex:none; width:6px; height:6px; border-radius:50%; background:currentColor; }
+.design-handoff-badge[data-status="ready"],.design-handoff-badge[data-status="pass"],.design-handoff-badge[data-status="approved"] { color:var(--planr-color-primary); }
+.design-handoff-badge[data-status="blocked"],.design-handoff-badge[data-status="revoked"] { color:var(--planr-color-danger); }
+.design-handoff-badge[data-status="attention"],.design-handoff-badge[data-status="stale"],.design-handoff-badge[data-status="superseded"] { color:#d89a39; }
+.design-handoff-step .design-handoff-badge { max-width:44px; overflow:hidden; padding:0; border:0; color:inherit; text-indent:-999px; }
+.design-handoff-step .design-handoff-badge::before { width:7px; height:7px; }
+.design-handoff-content { min-width:0; overflow:auto; overscroll-behavior:contain; padding:18px 14px 28px; }
+.design-handoff-step-header { display:grid; gap:6px; margin-bottom:18px; }
+.design-handoff-step-header p,.design-handoff-content .design-muted { color:var(--planr-color-text-muted); font-size:12px; }
+.design-handoff-summary { display:grid; gap:10px; margin-bottom:16px; padding:12px; border:1px solid var(--planr-color-rule); border-radius:8px; background:var(--planr-color-raised); }
+.design-handoff-summary strong { font-size:13px; line-height:1.45; }
+.design-handoff-empty { display:grid; gap:7px; margin:12px 0 18px; padding:18px 14px; border:1px dashed var(--planr-color-rule); border-radius:8px; }
+.design-handoff-empty p { color:var(--planr-color-text-muted); font-size:12px; }
+.design-handoff-checks,.design-handoff-requirement-list { display:grid; gap:8px; margin:0 0 18px; padding:0; list-style:none; }
+.design-handoff-checks li,.design-handoff-requirement-list li { display:grid; gap:8px; padding:10px; border:1px solid var(--planr-color-rule); border-radius:7px; }
+.design-handoff-checks li > div { display:flex; align-items:flex-start; justify-content:space-between; gap:8px; }
+.design-handoff-checks strong,.design-handoff-requirement-list strong { font-size:12px; line-height:1.45; }
+.design-handoff-link { min-height:32px!important; padding:4px 0!important; border:0!important; background:transparent!important; color:var(--planr-color-primary)!important; text-align:left; }
+.design-handoff-review-groups { display:grid; gap:10px; margin-bottom:18px; }
+.design-handoff-review-group { display:grid; gap:7px; }
+.design-handoff-review-group article { display:grid; gap:4px; padding:9px 10px; border-left:2px solid var(--planr-color-rule); background:var(--planr-color-panel); font-size:12px; }
+.design-handoff-refinement { color:var(--planr-color-text-muted); }
+.design-handoff-package-editor,.design-handoff-requirements,.design-handoff-package-editor fieldset { display:grid; gap:12px; min-width:0; }
+.design-handoff-package-editor > label,.design-handoff-package-editor fieldset label,.design-handoff-content > label { display:grid; gap:6px; margin-bottom:14px; color:var(--planr-color-text-muted); font-size:12px; }
+.design-handoff-package-editor input,.design-handoff-package-editor textarea,.design-handoff-content > label input,.design-handoff-plan-result textarea { width:100%; min-height:44px; border:1px solid var(--planr-color-rule); border-radius:6px; padding:9px 10px; color:var(--planr-color-text); background:var(--planr-color-panel); }
+.design-handoff-package-editor textarea { min-height:82px; resize:vertical; }
+.design-handoff-package-editor fieldset { margin:0; border:1px solid var(--planr-color-rule); border-radius:7px; padding:10px; }
+.design-handoff-package-editor legend { padding:0 5px; color:var(--planr-color-text); font-size:11px; text-transform:capitalize; }
+.design-handoff-content details { margin:14px 0; border-top:1px solid var(--planr-color-rule); padding-top:12px; }
+.design-handoff-content summary { min-height:36px; cursor:pointer; color:var(--planr-color-text-muted); font-size:12px; }
+.design-handoff-approval-card { display:grid; gap:9px; margin-bottom:18px; padding:16px; border:1px solid var(--planr-color-rule); border-radius:8px; background:var(--planr-color-raised); }
+.design-handoff-plan-result { display:grid; gap:10px; margin-top:14px; }
+.design-handoff-plan-result code { display:block; overflow:auto; border:1px solid var(--planr-color-rule); border-radius:6px; padding:10px; background:var(--planr-color-background); font-size:11px; white-space:pre; }
+.design-handoff-copy { width:100%; }
+.design-handoff-center > footer { display:flex; align-items:center; justify-content:space-between; gap:10px; min-height:50px; padding:8px 12px; border-top:1px solid var(--planr-color-rule); background:var(--planr-color-chrome); }
+.design-handoff-center > footer p { flex:1; color:var(--planr-color-text-muted); font-size:10px; }
+.design-handoff-center > footer p[data-error="true"] { color:var(--planr-color-danger); }
+.design-handoff-center > footer button { flex:none; }
+.planr-shell[data-design-handoff-open="true"] .planr-review-rail { visibility:hidden; pointer-events:none; }
+@media (max-width:960px) {
+  .design-handoff-center { position:absolute; width:min(380px,calc(100% - 16px)); }
+}
+@media (max-width:680px) {
+  .design-handoff-center { inset:var(--planr-toolbar-height) 0 0; width:100%; max-width:none; border-left:0; }
+  .design-handoff-center button,.design-handoff-center input,.design-handoff-center textarea,.design-handoff-center summary { min-height:44px; }
+  .design-handoff-center input,.design-handoff-center textarea { font-size:16px; }
+  .design-handoff-progress { position:sticky; z-index:2; top:0; background:var(--planr-color-chrome); }
+  .design-handoff-content { padding-inline:16px; }
+}
+@media (prefers-reduced-motion:reduce) { .design-handoff-center * { scroll-behavior:auto!important; transition:none!important; animation:none!important; } }
+@media (forced-colors:active) {
+  .design-handoff-center,.design-handoff-summary,.design-handoff-empty,.design-handoff-checks li,.design-handoff-requirement-list li { border-color:CanvasText; }
+  .design-handoff-badge::before { forced-color-adjust:none; background:currentColor; }
+}

package/lib/host-packages/cursor/openplanr/rules/planr-design-review/scripts/runtime/packages/design/templates/studio/handoff-center.js

@@ -0,0 +1,400 @@
+/* Five-step Design Handoff Center. Domain decisions stay in server projections. */
+(() => {
+  'use strict';
+  if (document.currentScript && !document.currentScript.isConnected) return;
+
+  const q = (selector, parent = document) => parent.querySelector(selector);
+  const node = (tag, text = '', attrs = {}) => {
+    const value = document.createElement(tag);
+    if (text) value.textContent = text;
+    for (const [key, entry] of Object.entries(attrs)) if (entry !== undefined && entry !== null && entry !== false) value.setAttribute(key, entry);
+    return value;
+  };
+  const action = (label, run, attrs = {}) => {
+    const value = node('button', label, { type: 'button', ...attrs });
+    value.addEventListener('click', run);
+    return value;
+  };
+  const plainPackage = value => ({
+    id: value.id,
+    title: value.title,
+    sources: structuredClone(value.sources || []),
+    requirements: (value.requirements || []).map(({ id: _id, ...requirement }) => structuredClone(requirement)),
+  });
+  const requestId = prefix => `${prefix}-${globalThis.crypto?.randomUUID?.() || `${Date.now()}-${Math.random().toString(16).slice(2)}`}`;
+  const labels = { ready: 'Ready', pass: 'Complete', attention: 'Needs attention', blocked: 'Blocked', stale: 'Out of date', absent: 'Not available', approved: 'Approved', draft: 'Draft', superseded: 'Superseded', revoked: 'Revoked' };
+  const steps = [
+    ['readiness', 'Readiness'],
+    ['review', 'Review resolution'],
+    ['package', 'Implementation package'],
+    ['approval', 'Owner approval'],
+    ['plan', 'Continue to Plan'],
+  ];
+
+  let bridge, root, panel, opener, activeStep = 'readiness', serial = 0;
+  const state = { readiness: null, review: null, implementation: null, errors: {} };
+
+  const readiness = () => state.readiness?.readiness || state.readiness;
+  const approvedReview = () => Boolean(state.review?.current && state.review?.draft?.status === 'approved');
+  const packageDraft = () => state.implementation?.draft || null;
+  const currentPackage = () => state.implementation?.current || null;
+  const approvedPackage = () => currentPackage()?.status === 'approved';
+  const statusFor = id => {
+    if (state.errors[id === 'readiness' ? 'readiness' : id === 'review' ? 'review' : 'implementation']) return 'attention';
+    if (id === 'readiness') return readiness()?.status || 'absent';
+    if (id === 'review') return approvedReview() ? 'pass' : state.review?.draft ? (state.review.current ? 'attention' : 'stale') : 'blocked';
+    if (id === 'package') return packageDraft() ? 'pass' : readiness()?.status === 'ready' ? 'attention' : 'blocked';
+    if (id === 'approval') return approvedPackage() ? 'pass' : currentPackage()?.status || (packageDraft() ? 'attention' : 'blocked');
+    return approvedPackage() ? 'ready' : 'blocked';
+  };
+  const badge = value => node('span', labels[value] || value, { class: 'design-handoff-badge', 'data-status': value });
+  const paragraph = (text, className = '') => node('p', text, className ? { class: className } : {});
+  const empty = (title, detail) => {
+    const value = node('div', '', { class: 'design-handoff-empty' });
+    value.append(node('strong', title), paragraph(detail));
+    return value;
+  };
+  const sectionTitle = (eyebrow, title, detail) => {
+    const block = node('header', '', { class: 'design-handoff-step-header' });
+    block.append(node('span', eyebrow, { class: 'design-handoff-eyebrow' }), node('h3', title), paragraph(detail));
+    return block;
+  };
+  const setStatus = (message, error = false) => {
+    const live = q('[data-design-handoff-status]', panel);
+    if (!live) return;
+    live.textContent = message;
+    live.dataset.error = String(error);
+  };
+  const setBusy = busy => {
+    panel?.toggleAttribute('aria-busy', busy);
+    panel && q('[data-design-handoff-refresh]', panel)?.toggleAttribute('disabled', busy);
+  };
+  const perform = async (message, work, success) => {
+    setBusy(true); setStatus(message);
+    try {
+      await work();
+      await refresh();
+      setStatus(success);
+    } catch (error) {
+      setStatus(error?.message || 'The handoff action could not be completed. Refresh and try again.', true);
+    } finally { setBusy(false); }
+  };
+
+  function renderProgress() {
+    const progress = q('[data-design-handoff-progress]', panel);
+    progress.replaceChildren();
+    for (const [index, [id, label]] of steps.entries()) {
+      const status = statusFor(id);
+      const button = action(label, () => { activeStep = id; render(); q(`[data-handoff-step="${id}"]`, panel)?.focus(); }, {
+        class: 'design-handoff-step',
+        'data-handoff-step': id,
+        'data-status': status,
+        'aria-current': activeStep === id ? 'step' : undefined,
+        'aria-label': `${index + 1}. ${label}: ${labels[status] || status}`,
+      });
+      button.prepend(node('span', String(index + 1).padStart(2, '0'), { 'aria-hidden': 'true' }));
+      button.append(badge(status));
+      progress.append(button);
+    }
+  }
+
+  function recoveryAction(check) {
+    const label = check.recoveryAction?.label || 'Return to the design';
+    return action(label, () => {
+      if (['resolve-review-decisions', 'resolve-review-blockers', 'approve-review-handoff'].includes(check.recoveryAction?.id)) {
+        activeStep = 'review'; render();
+      } else {
+        close(); bridge.announce(`${check.message} ${label}.`);
+      }
+    }, { class: 'design-handoff-link' });
+  }
+
+  function renderReadiness(content) {
+    const value = readiness();
+    content.append(sectionTitle('Step 1 of 5', 'Readiness', 'Confirm the current design, verification and review evidence before preparing implementation work.'));
+    if (state.errors.readiness) {
+      content.append(empty('Readiness is temporarily unavailable', state.errors.readiness));
+      content.append(action('Retry readiness', refresh, { class: 'design-primary' }));
+      return;
+    }
+    if (!value || value.status === 'absent') {
+      content.append(empty('No readiness projection yet', value?.message || 'Complete a local design render to compute handoff readiness.'));
+      content.append(action(value?.nextAction?.label || 'Return to the design', close, { class: 'design-primary' }));
+      return;
+    }
+    const summary = node('div', '', { class: 'design-handoff-summary' });
+    summary.append(badge(value.status), node('strong', value.status === 'ready' ? 'This design can move into implementation packaging.' : `${value.blockers?.length || 0} blocking checks remain.`));
+    content.append(summary);
+    const list = node('ol', '', { class: 'design-handoff-checks' });
+    for (const check of value.checks || []) {
+      const item = node('li', '', { 'data-status': check.status });
+      const body = node('div'); body.append(node('strong', check.message), badge(check.status));
+      item.append(body);
+      if (check.status !== 'pass') item.append(recoveryAction(check));
+      list.append(item);
+    }
+    content.append(list);
+    if (value.status === 'ready') content.append(action('Review resolved feedback', () => { activeStep = 'review'; render(); }, { class: 'design-primary' }));
+    else if (value.nextActions?.[0]) content.append(recoveryAction({ message: 'Readiness needs attention.', recoveryAction: value.nextActions[0] }));
+  }
+
+  function reviewGroup(title, items) {
+    const section = node('section', '', { class: 'design-handoff-review-group' });
+    section.append(node('h4', `${title} · ${items?.length || 0}`));
+    if (!items?.length) section.append(paragraph('None recorded.', 'design-muted'));
+    for (const item of items || []) {
+      const card = node('article');
+      card.append(paragraph(item.text || item.statement || 'Review decision'));
+      if (item.refinement) card.append(paragraph(item.refinement, 'design-handoff-refinement'));
+      section.append(card);
+    }
+    return section;
+  }
+
+  function renderReview(content) {
+    content.append(sectionTitle('Step 2 of 5', 'Review resolution', 'Turn current feedback into explicit accepted, open, deferred and declined decisions.'));
+    if (state.errors.review) {
+      content.append(empty('Review decisions could not be loaded', state.errors.review));
+      content.append(action('Retry review decisions', refresh, { class: 'design-primary' }));
+      return;
+    }
+    const response = state.review, draft = response?.draft;
+    if (!draft) {
+      content.append(empty('No review handoff has been prepared', 'Generate a proposal from the current comments. You will review every decision before approval.'));
+      content.append(action('Generate review handoff', () => perform('Generating review decisions…', async () => {
+        state.review = await bridge.updateReviewHandoff({ action: 'draft', version: 0 });
+      }, 'Review decisions generated.'), { class: 'design-primary' }));
+      return;
+    }
+    const status = response.current ? draft.status : 'stale';
+    const summary = node('div', '', { class: 'design-handoff-summary' });
+    summary.append(badge(status), node('strong', draft.content?.summary || (response.current ? 'Review decisions match this design.' : 'The design or feedback changed after this handoff was prepared.')));
+    content.append(summary);
+    const decisions = node('div', '', { class: 'design-handoff-review-groups' });
+    decisions.append(
+      reviewGroup('Accepted changes', draft.content?.agreedChanges),
+      reviewGroup('Open questions', draft.content?.openQuestions),
+      reviewGroup('Deferred', draft.content?.deferred),
+      reviewGroup('Declined', draft.content?.rejected),
+    );
+    content.append(decisions);
+    const label = approvedReview() ? 'Continue to implementation package' : response.current ? 'Review and approve decisions' : 'Regenerate current decisions';
+    content.append(action(label, () => {
+      if (approvedReview()) { activeStep = 'package'; render(); }
+      else bridge.openReviewHandoff();
+    }, { class: 'design-primary' }));
+  }
+
+  function packageEditor(source, { regenerate = false } = {}) {
+    const form = node('form', '', { class: 'design-handoff-package-editor' });
+    const editable = plainPackage(source);
+    const title = node('input', '', { type: 'text', required: '', maxlength: '256', 'aria-label': 'Implementation package title' });
+    title.value = editable.title;
+    const titleLabel = node('label', 'Package title'); titleLabel.append(title); form.append(titleLabel);
+    const requirements = node('div', '', { class: 'design-handoff-requirements' });
+    const editors = editable.requirements.map((requirement, index) => {
+      const card = node('fieldset'); card.append(node('legend', `${requirement.kind.replaceAll('-', ' ')} requirement ${index + 1}`));
+      const statement = node('textarea', '', { required: '', maxlength: '16384', 'aria-label': `Requirement ${index + 1} statement` }); statement.value = requirement.statement;
+      const verification = node('textarea', '', { required: '', maxlength: '16384', 'aria-label': `Requirement ${index + 1} verification` }); verification.value = requirement.verification.join('\n');
+      const statementLabel = node('label', 'Requirement'); statementLabel.append(statement);
+      const verificationLabel = node('label', 'Verification, one expectation per line'); verificationLabel.append(verification);
+      card.append(statementLabel, verificationLabel); requirements.append(card);
+      return { requirement, statement, verification };
+    });
+    form.append(requirements);
+    const save = node('button', regenerate ? 'Create next package version' : 'Save implementation package', { type: 'submit', class: 'design-primary' });
+    form.append(save);
+    form.addEventListener('submit', event => {
+      event.preventDefault();
+      if (!form.reportValidity()) return;
+      editable.title = title.value.trim();
+      editable.requirements = editors.map(({ requirement, statement, verification }) => ({
+        ...requirement,
+        statement: statement.value.trim(),
+        verification: verification.value.split('\n').map(value => value.trim()).filter(Boolean),
+      }));
+      const input = regenerate
+        ? { action: 'regenerate', requestId: requestId('regenerate'), package: editable }
+        : { action: 'draft', package: editable };
+      void perform(regenerate ? 'Creating a new package version…' : 'Saving the implementation package…', async () => {
+        await bridge.updateImplementationHandoff(input);
+      }, regenerate ? 'A new package version is ready for approval.' : 'Implementation package saved.');
+    });
+    return form;
+  }
+
+  function renderPackage(content) {
+    content.append(sectionTitle('Step 3 of 5', 'Implementation package', 'Review traceable requirements and observable verification expectations. Integrity values stay in the contract and are hidden here.'));
+    if (state.errors.implementation) {
+      content.append(empty('Implementation package could not be loaded', state.errors.implementation));
+      content.append(action('Retry implementation package', refresh, { class: 'design-primary' }));
+      return;
+    }
+    const response = state.implementation, draft = response?.draft;
+    if (!approvedReview() || readiness()?.status !== 'ready') {
+      content.append(empty('Readiness must be complete first', 'Approve current review decisions and resolve every blocking readiness check before composing the implementation package.'));
+      content.append(action('Return to readiness', () => { activeStep = 'readiness'; render(); }, { class: 'design-primary' }));
+      return;
+    }
+    if (!draft) {
+      const proposal = response?.proposal;
+      if (!proposal) {
+        content.append(empty('No package proposal is available', 'Refresh the current design render, then return here to prepare the implementation scope.'));
+        content.append(action('Refresh package proposal', refresh, { class: 'design-primary' }));
+        return;
+      }
+      content.append(paragraph(`${proposal.sources.length} approved sources · ${proposal.requirements.length} proposed requirements`, 'design-muted'));
+      content.append(packageEditor(proposal));
+      return;
+    }
+    const summary = node('div', '', { class: 'design-handoff-summary' });
+    summary.append(badge(draft.status), node('strong', `${draft.title} · version ${draft.version}`));
+    content.append(summary, paragraph(`${draft.sources.length} sources · ${draft.requirements.length} requirements`, 'design-muted'));
+    const list = node('ol', '', { class: 'design-handoff-requirement-list' });
+    for (const requirement of draft.requirements) {
+      const item = node('li');
+      item.append(node('strong', requirement.statement), paragraph(requirement.verification.join(' · '), 'design-muted'));
+      list.append(item);
+    }
+    content.append(list);
+    if (approvedPackage()) {
+      const edit = node('details'); edit.append(node('summary', 'Prepare a revised package version'), packageEditor(draft, { regenerate: true })); content.append(edit);
+    }
+    content.append(action('Review owner approval', () => { activeStep = 'approval'; render(); }, { class: 'design-primary' }));
+  }
+
+  function renderApproval(content) {
+    content.append(sectionTitle('Step 4 of 5', 'Owner approval', 'Approval records the exact package version and permits a later, separate Plan invocation.'));
+    if (state.errors.implementation) {
+      content.append(empty('Approval state could not be loaded', state.errors.implementation));
+      content.append(action('Retry approval state', refresh, { class: 'design-primary' }));
+      return;
+    }
+    const response = state.implementation, draft = response?.draft, current = response?.current, preview = response?.approvalPreview;
+    if (!draft) {
+      content.append(empty('No package is ready for approval', 'Complete the implementation package before requesting owner approval.'));
+      content.append(action('Prepare implementation package', () => { activeStep = 'package'; render(); }, { class: 'design-primary' }));
+      return;
+    }
+    if (approvedPackage()) {
+      const approved = response.history?.find(item => item.id === current.id && item.version === current.version);
+      content.append(node('div', '', { class: 'design-handoff-approval-card' }));
+      const card = content.lastElementChild;
+      card.append(badge('approved'), node('h4', approved?.title || draft.title), paragraph(`Version ${current.version} was approved${approved?.approval?.actorId ? ` by ${approved.approval.actorId}` : ''}${approved?.approval?.approvedAt ? ` on ${new Date(approved.approval.approvedAt).toLocaleString()}` : ''}.`));
+      content.append(action('Continue to Plan', () => { activeStep = 'plan'; render(); }, { class: 'design-primary' }));
+      const details = node('details'); details.append(node('summary', 'Revoke this approval'));
+      const reason = node('textarea', '', { 'aria-label': 'Revocation reason', maxlength: '16384', placeholder: 'Why is this package no longer approved?' });
+      details.append(reason, action('Revoke approval', () => {
+        if (!reason.value.trim()) { reason.setCustomValidity('Enter a revocation reason.'); reason.reportValidity(); return; }
+        reason.setCustomValidity('');
+        void perform('Revoking approval…', async () => bridge.updateImplementationHandoff({ action: 'revoke', requestId: requestId('revoke'), expectedVersion: current.version, expectedContentDigest: current.contentDigest, reason: reason.value.trim() }), 'Approval revoked.');
+      }, { class: 'design-danger' }));
+      content.append(details);
+      return;
+    }
+    if (!preview?.available) {
+      content.append(empty(current?.status === 'revoked' ? 'The current approval was revoked' : 'This package cannot be approved yet', 'Refresh the package against the current ready design, then review approval again.'));
+      content.append(action('Review implementation package', () => { activeStep = 'package'; render(); }, { class: 'design-primary' }));
+      return;
+    }
+    const card = node('div', '', { class: 'design-handoff-approval-card' });
+    card.append(node('h4', preview.summary.title), paragraph(`Version ${preview.summary.packageVersion} · ${preview.summary.requirementCount} requirements · direction ${preview.summary.selectedVariant}`), paragraph(preview.summary.description, 'design-muted'));
+    content.append(card, action('Approve exact package', () => perform('Recording owner approval…', async () => {
+      await bridge.updateImplementationHandoff({ action: 'approve', requestId: requestId('approve'), ...preview.approvalRequest });
+    }, 'Implementation package approved.'), { class: 'design-primary' }));
+  }
+
+  async function copyText(value, output) {
+    try { await navigator.clipboard.writeText(value); output.textContent = 'Invocation copied. Paste it into your active coding agent when you are ready.'; }
+    catch {
+      const field = node('textarea', '', { readonly: '', 'aria-label': 'Plan invocation' }); field.value = value; output.before(field); field.focus(); field.select(); output.textContent = 'Copy the selected invocation.';
+    }
+  }
+
+  function renderPlan(content) {
+    content.append(sectionTitle('Step 5 of 5', 'Continue to Plan', 'Prepare an explicit host handoff. Plan remains a separate action; Ship is never started here.'));
+    if (!approvedPackage()) {
+      content.append(empty('An approved current package is required', currentPackage()?.status === 'revoked' ? 'This package was revoked. Prepare and approve a current version before planning.' : 'Complete owner approval before preparing the Plan invocation.'));
+      content.append(action('Review owner approval', () => { activeStep = 'approval'; render(); }, { class: 'design-primary' }));
+      return;
+    }
+    const context = bridge.context();
+    const subject = node('input', '', { type: 'text', required: '', maxlength: '256', value: context.designId, 'aria-label': 'Plan subject' });
+    const label = node('label', 'Plan subject'); label.append(subject); content.append(label);
+    const result = node('div', '', { class: 'design-handoff-plan-result', 'aria-live': 'polite' });
+    content.append(action('Prepare Plan handoff', async () => {
+      setBusy(true); setStatus('Preparing the Plan handoff…');
+      try {
+        const response = await bridge.updateImplementationHandoff({ action: 'continue-to-plan', subject: subject.value.trim() });
+        const handoff = response.handoff;
+        if (typeof bridge.continueToActiveHost === 'function') {
+          await bridge.continueToActiveHost(handoff);
+          result.textContent = 'The approved package was handed to the active host. Invoke Plan there to continue.';
+        } else {
+          const host = String(context.host || '').toLowerCase();
+          const key = host.includes('claude') ? 'claudeCode' : host.includes('codex') ? 'codex' : host.includes('cursor') ? 'cursor' : 'fallback';
+          const invocation = handoff.invocations[key] || handoff.invocations.fallback;
+          result.replaceChildren(node('code', invocation));
+          result.append(action('Copy invocation', () => void copyText(invocation, result), { class: 'design-handoff-copy' }));
+        }
+        setStatus('Plan handoff prepared. No planning files, agents, Git state or Ship run were changed.');
+      } catch (error) { setStatus(error?.message || 'The Plan handoff could not be prepared.', true); }
+      finally { setBusy(false); }
+    }, { class: 'design-primary' }), result);
+  }
+
+  function render() {
+    if (!panel) return;
+    renderProgress();
+    const content = q('[data-design-handoff-content]', panel); content.replaceChildren();
+    ({ readiness: renderReadiness, review: renderReview, package: renderPackage, approval: renderApproval, plan: renderPlan })[activeStep](content);
+  }
+
+  async function refresh() {
+    const attempt = ++serial;
+    setBusy(true); setStatus('Refreshing handoff state…');
+    const results = await Promise.allSettled([bridge.loadReadiness(), bridge.loadReviewHandoff(), bridge.loadImplementationHandoff()]);
+    if (attempt !== serial || !panel) return;
+    for (const [index, key] of ['readiness', 'review', 'implementation'].entries()) {
+      const result = results[index];
+      if (result.status === 'fulfilled') { state[key] = result.value; delete state.errors[key]; }
+      else state.errors[key] = result.reason?.message || 'This state is temporarily unavailable.';
+    }
+    setBusy(false); setStatus(Object.keys(state.errors).length ? 'Some handoff state is unavailable. The current design remains usable.' : 'Handoff state is current.', Boolean(Object.keys(state.errors).length));
+    render();
+  }
+
+  function close() {
+    if (!panel) return;
+    const returnTo = opener; panel.remove(); panel = null; delete root.dataset.designHandoffOpen;
+    returnTo?.isConnected && returnTo.focus({ preventScroll: true });
+  }
+
+  function open(step = activeStep) {
+    if (!bridge.owner()) return bridge.announce('Only a design owner can prepare an implementation handoff.', true);
+    activeStep = steps.some(([id]) => id === step) ? step : 'readiness';
+    if (panel) { render(); q(`[data-handoff-step="${activeStep}"]`, panel)?.focus(); return; }
+    opener = document.activeElement; root.dataset.designHandoffOpen = 'true';
+    panel = node('aside', '', { class: 'design-handoff-center', role: 'dialog', 'aria-modal': 'false', 'aria-labelledby': 'design-handoff-center-title' });
+    const header = node('header');
+    const heading = node('div'); heading.append(node('span', 'Owner workspace', { class: 'design-handoff-eyebrow' }), node('h2', 'Handoff Center', { id: 'design-handoff-center-title' }));
+    header.append(heading, action('×', close, { 'aria-label': 'Close Handoff Center', class: 'design-handoff-close' }));
+    const progress = node('nav', '', { class: 'design-handoff-progress', 'data-design-handoff-progress': '', 'aria-label': 'Design handoff progress' });
+    const content = node('section', '', { class: 'design-handoff-content', 'data-design-handoff-content': '', tabindex: '-1' });
+    const footer = node('footer'); footer.append(node('p', '', { 'data-design-handoff-status': '', role: 'status', 'aria-live': 'polite' }), action('Refresh', refresh, { 'data-design-handoff-refresh': '' }));
+    panel.append(header, progress, content, footer); root.append(panel);
+    panel.addEventListener('keydown', event => { if (event.key === 'Escape') { event.preventDefault(); close(); } });
+    render(); q(`[data-handoff-step="${activeStep}"]`, panel)?.focus({ preventScroll: true }); void refresh();
+  }
+
+  function mount() {
+    bridge = window.__openPlanrDesignHandoffBridge;
+    root = q('.planr-shell');
+    if (!bridge || !root) return false;
+    window.__openPlanrDesignHandoffCenter = Object.freeze({ open, close, refresh, getState: () => ({ open: Boolean(panel), step: activeStep, statuses: Object.fromEntries(steps.map(([id]) => [id, statusFor(id)])) }) });
+    return true;
+  }
+  const started = Date.now();
+  function boot() { if (!mount() && Date.now() - started < 15000) setTimeout(boot, 30); }
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot, { once: true }); else boot();
+})();

package/lib/host-packages/cursor/openplanr/rules/planr-design-review/scripts/runtime/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openplanr/protocol",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Canonical OpenPlanr schemas, registries, typed errors, and portable contract validation",
   "license": "MIT",
@@ -47,6 +47,10 @@
       "types": "./src/design-publication-contracts.d.mts",
       "import": "./src/design-publication-contracts.mjs"
     },
+    "./design-handoff-contracts": {
+      "types": "./src/design-handoff-contracts.d.mts",
+      "import": "./src/design-handoff-contracts.mjs"
+    },
     "./registries": {
       "types": "./src/registries.d.mts",
       "import": "./src/registries.mjs"