@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

package/src/dashboard/app/components/DetailPanel.jsx

@@ -1,11 +1,47 @@
-export default function DetailPanel({ open, title, onClose, children }) {
-  return (
-    <div className={`fixed top-0 right-0 h-full w-96 bg-gray-900 border-l border-gray-700 shadow-2xl transform transition-transform duration-200 ease-in-out z-50 ${open ? 'translate-x-0' : 'translate-x-full'}`}>
-      <div className="flex items-center justify-between p-4 border-b border-gray-700">
-        <h2 className="text-white font-semibold text-lg truncate">{title}</h2>
-        <button onClick={onClose} className="text-gray-400 hover:text-white text-xl leading-none">×</button>
-      </div>
-      <div className="p-4 overflow-y-auto h-[calc(100%-57px)]">{children}</div>
-    </div>
-  );
-}
+import { useEffect } from 'react';
+import { X } from '@phosphor-icons/react';
+
+/**
+ * The reading drawer of the knowledge pages. Wide enough for rendered markdown,
+ * closes on Escape, and sits over the graph without a backdrop so the graph
+ * stays visible beside it.
+ */
+export default function DetailPanel({ open, title, subtitle, onClose, children }) {
+  useEffect(() => {
+    if (!open) return undefined;
+    const onKey = (e) => { if (e.key === 'Escape') onClose?.(); };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [open, onClose]);
+
+  return (
+    <aside
+      aria-hidden={!open}
+      aria-label={title}
+      className={[
+        'fluid fixed inset-y-0 right-0 z-40 flex w-full max-w-[44rem] flex-col p-3 transition-transform',
+        open ? 'translate-x-0' : 'pointer-events-none translate-x-full',
+      ].join(' ')}
+    >
+      <div className="bezel flex min-h-0 flex-1 flex-col bg-[var(--color-ink)]/80 backdrop-blur-xl">
+        <div className="bezel-core flex min-h-0 flex-1 flex-col">
+          <header className="flex items-start justify-between gap-4 border-b border-[var(--color-hair)] px-6 py-4">
+            <div className="min-w-0">
+              <h2 className="truncate text-lg font-semibold tracking-tight">{title}</h2>
+              {subtitle && <p className="mt-0.5 truncate text-sm text-[var(--color-dim)]">{subtitle}</p>}
+            </div>
+            <button
+              type="button"
+              onClick={onClose}
+              aria-label="Fechar painel"
+              className="fluid flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-white/[0.05] text-[var(--color-dim)] transition-colors hover:bg-white/[0.1] hover:text-[var(--color-fg)]"
+            >
+              <X weight="light" size={16} />
+            </button>
+          </header>
+          <div className="min-h-0 flex-1 overflow-y-auto px-6 py-5">{children}</div>
+        </div>
+      </div>
+    </aside>
+  );
+}

package/src/dashboard/app/components/EntityLink.jsx

@@ -0,0 +1,55 @@
+import { Link, useSearchParams } from 'react-router-dom';
+import { useCallback } from 'react';
+
+/**
+ * Where each kind of thing lives in the app. The ONE map of entity → URL, so a
+ * persona, standard or skill reads as a link everywhere it is mentioned.
+ * A feature belongs to a project: its links come from `featureHref` (lib/project.js).
+ */
+export function entityHref(kind, id) {
+  const q = (page) => `/${page}?sel=${encodeURIComponent(id)}`;
+  switch (kind) {
+    case 'persona': return q('agents');
+    case 'skill': return q('skills');
+    case 'standard': return q('standards');
+    case 'rule': return q('rules');
+    case 'hook': return q('hooks');
+    case 'phase': return q('phases');
+    case 'guide': return `/guide/${encodeURIComponent(id)}`;
+    case 'rubric': return q('rubrics');
+    default: return '#';
+  }
+}
+
+/** `standards/backend/dotnet/testing.md` (as tasks.json cites it) → the registry `path`. */
+export function standardKey(ref) {
+  return String(ref).replace(/^\.?\/?(\.morph\/framework\/)?standards\//, '');
+}
+
+const TONE = 'text-[var(--color-phase-proposal)] hover:underline underline-offset-2';
+
+export default function EntityLink({ kind, id, children, className = '', chip = false, plain = false, title }) {
+  const cls = chip
+    ? `inline-flex items-center rounded-full px-2 py-0.5 font-mono text-[11px] text-[var(--color-dim)] shadow-[inset_0_0_0_1px_var(--color-hair)] transition-colors hover:text-[var(--color-fg)] hover:shadow-[inset_0_0_0_1px_var(--color-hair-strong)] ${className}`
+    : plain ? className : `${TONE} ${className}`;
+  return <Link to={entityHref(kind, id)} className={cls} title={title}>{children ?? id}</Link>;
+}
+
+/**
+ * The selected item of a knowledge page, kept in `?sel=` so a panel can be
+ * linked, bookmarked and reached from anywhere with EntityLink.
+ *
+ * @returns {[string|null, (id: string|null) => void]}
+ */
+export function useSelection() {
+  const [params, setParams] = useSearchParams();
+  const sel = params.get('sel');
+  const setSel = useCallback((id) => {
+    setParams((p) => {
+      const n = new URLSearchParams(p);
+      if (id) n.set('sel', id); else n.delete('sel');
+      return n;
+    }, { replace: false });
+  }, [setParams]);
+  return [sel, setSel];
+}

package/src/dashboard/app/components/ErrorBoundary.jsx

@@ -0,0 +1,54 @@
+import { Component } from 'react';
+
+/**
+ * Catches a page that throws while rendering and shows the error in place of
+ * the page, so the rest of the layout (the sidebar) keeps working.
+ *
+ * Without it one broken page unmounts the whole tree: 8.38.0 opened on
+ * /agents, which threw a ReferenceError, and the dashboard was a black screen.
+ *
+ * Mount it with `key={location.pathname}`: a boundary that already caught an
+ * error stays in fallback until it remounts, and the key remounts it when the
+ * sidebar navigates to another page.
+ */
+export default class ErrorBoundary extends Component {
+  constructor(props) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+
+  componentDidCatch(error, info) {
+    console.error(`[dashboard] ${this.props.page || 'page'} failed to render:`, error, info?.componentStack);
+  }
+
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+    return (
+      <div role="alert" className="p-6 max-w-3xl">
+        <h2 className="text-red-400 text-sm font-semibold uppercase tracking-wide mb-2">
+          This page failed to render
+        </h2>
+        <p className="text-gray-300 text-sm mb-3">
+          <span className="font-mono text-gray-400">{this.props.page}</span> threw while rendering.
+          The other pages still work — pick one in the sidebar.
+        </p>
+        <pre className="p-3 bg-gray-900 border border-red-900 rounded text-xs text-red-300 whitespace-pre-wrap font-mono overflow-x-auto">
+          {error.name}: {error.message}
+        </pre>
+        {error.stack && (
+          <details className="mt-2">
+            <summary className="text-gray-500 text-xs cursor-pointer">Stack trace</summary>
+            <pre className="mt-1 p-3 bg-gray-950 border border-gray-800 rounded text-[10px] text-gray-500 whitespace-pre-wrap font-mono overflow-x-auto">
+              {error.stack}
+            </pre>
+          </details>
+        )}
+      </div>
+    );
+  }
+}

package/src/dashboard/app/components/FlowGraph.jsx

@@ -1,17 +1,19 @@
-import { ReactFlow, Controls, MiniMap, Background } from '@xyflow/react';
-
-export default function FlowGraph({ nodes, edges, nodeTypes, onNodeClick, fitView = true, className = '' }) {
-  return (
-    <div className={`w-full h-full ${className}`} style={{ minHeight: '500px' }}>
-      <ReactFlow
-        nodes={nodes} edges={edges} nodeTypes={nodeTypes} onNodeClick={onNodeClick}
-        fitView={fitView} proOptions={{ hideAttribution: true }}
-        defaultEdgeOptions={{ type: 'smoothstep', animated: false, style: { stroke: '#475569', strokeWidth: 1.5 } }}
-      >
-        <Background color="#1e293b" gap={20} />
-        <Controls position="bottom-right" />
-        <MiniMap nodeColor={(node) => node.data?.color || '#475569'} maskColor="rgba(0, 0, 0, 0.7)" position="bottom-left" />
-      </ReactFlow>
-    </div>
-  );
-}
+import { ReactFlow, Controls, MiniMap, Background } from '@xyflow/react';
+
+// The React Flow attribution stays: hiding it is licensed to Pro subscribers only.
+export default function FlowGraph({ nodes, edges, nodeTypes, onNodeClick, fitView = true, className = '' }) {
+  return (
+    <div className={`w-full h-full ${className}`} style={{ minHeight: '500px' }}>
+      <ReactFlow
+        nodes={nodes} edges={edges} nodeTypes={nodeTypes} onNodeClick={onNodeClick}
+        fitView={fitView} fitViewOptions={{ padding: 0.15, maxZoom: 1.1 }} minZoom={0.2}
+       
+        defaultEdgeOptions={{ type: 'smoothstep', animated: false, style: { stroke: '#3a4250', strokeWidth: 1.5 } }}
+      >
+        <Background color="rgb(255 255 255 / 0.05)" gap={22} />
+        <Controls position="bottom-right" />
+        <MiniMap nodeColor={(node) => node.data?.color || '#4a5260'} maskColor="rgba(5, 5, 5, 0.72)" position="bottom-left" pannable zoomable />
+      </ReactFlow>
+    </div>
+  );
+}

package/src/dashboard/app/components/KnowledgeMarkdown.jsx

@@ -0,0 +1,53 @@
+import morphData from 'virtual:morph-data';
+import Markdown from './Markdown.jsx';
+import EntityLink, { standardKey } from './EntityLink.jsx';
+
+/**
+ * Names of things that have a page. Built once from the knowledge module.
+ */
+const skillIds = new Set((morphData.skills || []).map((s) => s.id));
+const personaIds = new Set((morphData.agents?.list || []).map((a) => a.id));
+const standardByKey = new Map();
+for (const s of morphData.standards?.list || []) {
+  standardByKey.set(s.id, s.id);
+  standardByKey.set(s.path, s.id);
+}
+
+/**
+ * What an inline code span names, if it names something with a page:
+ * `morph-plan` or `/morph-plan` → skill, `morph-dotnet-senior` → persona,
+ * a standard id or path → standard.
+ *
+ * @returns {{ kind: string, id: string } | null}
+ */
+export function resolveMention(text) {
+  const t = String(text).trim();
+  const bare = t.replace(/^\//, '');
+  if (skillIds.has(bare)) return { kind: 'skill', id: bare };
+  const persona = /^morph-(.+)$/.exec(bare);
+  if (persona && personaIds.has(persona[1])) return { kind: 'persona', id: persona[1] };
+  const std = standardByKey.get(standardKey(t));
+  if (std) return { kind: 'standard', id: std };
+  return null;
+}
+
+function InlineCode({ className, children, node, ...rest }) {
+  const text = Array.isArray(children) ? children.join('') : String(children ?? '');
+  const block = Boolean(className) || text.includes('\n');
+  if (!block) {
+    const hit = resolveMention(text);
+    if (hit) {
+      return (
+        <EntityLink kind={hit.kind} id={hit.id} className="no-underline">
+          <code>{text}</code>
+        </EntityLink>
+      );
+    }
+  }
+  return <code className={className} {...rest}>{children}</code>;
+}
+
+/** Markdown for framework and feature text: code spans that name a skill, persona or standard become links. */
+export default function KnowledgeMarkdown({ components, ...props }) {
+  return <Markdown {...props} components={{ code: InlineCode, ...components }} />;
+}

package/src/dashboard/app/components/Markdown.jsx

@@ -0,0 +1,47 @@
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import rehypeSlug from 'rehype-slug';
+import { splitFrontmatter } from '../lib/format.js';
+
+const REMARK = [remarkGfm];
+const REHYPE = [rehypeSlug];
+
+/** Frontmatter keys worth showing, in the order a reader wants them. */
+const META_ORDER = ['name', 'description', 'when-to-invoke', 'user-invokable', 'stacks', 'version', 'cliVersion'];
+
+function MetaBlock({ meta }) {
+  const keys = Object.keys(meta).sort((a, b) => {
+    const ia = META_ORDER.indexOf(a); const ib = META_ORDER.indexOf(b);
+    return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);
+  });
+  return (
+    <dl className="mb-6 grid grid-cols-[max-content_1fr] gap-x-4 gap-y-1.5 rounded-xl bg-white/[0.03] px-4 py-3 text-sm shadow-[inset_0_0_0_1px_var(--color-hair)]">
+      {keys.map((k) => (
+        <div key={k} className="contents">
+          <dt className="font-mono text-xs leading-6 text-[var(--color-faint)]">{k}</dt>
+          <dd className="leading-6 text-[var(--color-dim)]">{meta[k] || '—'}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
+
+/**
+ * Rendered markdown for every long text in the app: feature artifacts, skills,
+ * standards, the charter. Frontmatter is lifted into a metadata block instead
+ * of being printed as text.
+ *
+ * @param {{ text: string, components?: object, className?: string, size?: 'md'|'sm' }} props
+ *   `sm` is for side panels, where the reading column is narrower.
+ */
+export default function Markdown({ text, components, className = '', size = 'md' }) {
+  const { meta, body } = splitFrontmatter(text || '');
+  return (
+    <article className={`prose-morph ${size === 'sm' ? 'prose-morph-sm' : ''} ${className}`}>
+      {meta && Object.keys(meta).length > 0 && <MetaBlock meta={meta} />}
+      <ReactMarkdown remarkPlugins={REMARK} rehypePlugins={REHYPE} components={components}>
+        {body}
+      </ReactMarkdown>
+    </article>
+  );
+}

package/src/dashboard/app/components/PhaseRail.jsx

@@ -0,0 +1,111 @@
+import { PHASES, PHASE_INDEX, GATE_LABEL, phaseMeta } from '../lib/phases.js';
+
+/**
+ * The phase rail: one segment per phase, a notch after each phase that ends in
+ * an approval gate. The same motif is used in the feature list (sm) and in the
+ * feature header (lg), so a feature's progress always reads the same way.
+ *
+ * Segment state is derived, never stored:
+ *   done     — before the current phase, or the whole feature is completed
+ *   current  — the derived phase of an active feature
+ *   skipped  — an optional phase (uiux) the feature went past without its gate
+ *   todo     — after the current phase
+ */
+export function segmentStates(feature) {
+  const idx = PHASE_INDEX[feature.phase] ?? 0;
+  const finished = feature.status === 'completed';
+  const gate = (id) => feature.gates?.find((g) => g.gate === id);
+  return PHASES.map((p, i) => {
+    let state = 'todo';
+    if (p.optional && !gate(p.id)?.approved && (i < idx || finished)) state = 'skipped';
+    else if (finished || i < idx) state = 'done';
+    else if (i === idx) state = 'current';
+    return { ...p, state, gate: gate(p.id) || null };
+  });
+}
+
+function notchState(g, segState) {
+  if (!g || g.skipped || segState === 'skipped') return null;
+  if (g.approved) return 'approved';
+  if (g.paused) return 'paused';
+  return 'pending';
+}
+
+const NOTCH_CLASS = {
+  approved: 'bg-[var(--color-ok)] shadow-[0_0_0_3px_rgb(158_206_106_/_0.15)]',
+  paused: 'bg-transparent ring-2 ring-[var(--color-warn)] animate-pulse',
+  pending: 'bg-transparent ring-1 ring-[var(--color-hair-strong)]',
+};
+
+function gateTitle(g) {
+  const label = GATE_LABEL[g.gate] || g.gate;
+  if (g.approved) return `${label}: aprovado${g.approvedBy ? ` por ${g.approvedBy}` : ''}`;
+  if (g.paused) return `${label}: pausado${g.reason ? `, ${g.reason}` : ''}`;
+  return `${label}: pendente`;
+}
+
+export default function PhaseRail({ feature, size = 'sm' }) {
+  const segments = segmentStates(feature);
+  const lg = size === 'lg';
+  const current = phaseMeta(feature.phase);
+  const summary = feature.status === 'completed'
+    ? 'Concluída'
+    : `Fase atual: ${current.label}${feature.inEvaluation ? ' (avaliação em andamento)' : ''}`;
+
+  return (
+    <div className={lg ? 'w-full' : 'w-full min-w-[9rem]'} role="img" aria-label={summary}>
+      <div className="flex items-center">
+        {segments.map((s, i) => {
+          const notch = notchState(s.gate, s.state);
+          return (
+            <div key={s.id} className="flex items-center flex-1 min-w-0" title={s.label}>
+              <div
+                className={[
+                  'relative flex-1 overflow-hidden rounded-full',
+                  lg ? 'h-2.5' : 'h-1.5',
+                  s.state === 'skipped' ? 'border border-dashed border-[var(--color-hair-strong)] bg-transparent' : '',
+                  s.state === 'todo' ? 'bg-white/[0.07]' : '',
+                ].join(' ')}
+                style={s.state === 'done' || s.state === 'current' ? { background: s.color, opacity: s.state === 'done' ? 0.78 : 1 } : undefined}
+              >
+                {s.state === 'current' && feature.status !== 'completed' && (
+                  <span className="rail-sheen absolute inset-0" aria-hidden="true" />
+                )}
+              </div>
+              {notch && (
+                <span
+                  title={gateTitle(s.gate)}
+                  className={['shrink-0 rounded-full', lg ? 'mx-1.5 h-3 w-3' : 'mx-1 h-2 w-2', NOTCH_CLASS[notch]].join(' ')}
+                />
+              )}
+              {!notch && i < segments.length - 1 && <span className={lg ? 'w-3' : 'w-2'} />}
+            </div>
+          );
+        })}
+      </div>
+      {lg && (
+        <div className="mt-2.5 flex">
+          {segments.map((s) => (
+            <div key={s.id} className="flex-1 min-w-0 pr-3">
+              <p
+                className={[
+                  'truncate text-xs',
+                  s.state === 'current' ? 'font-medium text-[var(--color-fg)]' : 'text-[var(--color-dim)]',
+                  s.state === 'skipped' ? 'line-through decoration-[var(--color-faint)]' : '',
+                ].join(' ')}
+              >
+                {s.label}
+              </p>
+              {s.state === 'skipped' && <p className="truncate text-[11px] text-[var(--color-faint)]">fase não usada</p>}
+              {s.state !== 'skipped' && s.gate && !s.gate.skipped && (
+                <p className="truncate text-[11px] text-[var(--color-faint)]">
+                  {s.gate.approved ? `aprovado${s.gate.approvedBy ? `, ${s.gate.approvedBy}` : ''}` : s.gate.paused ? 'gate pausado' : 'gate pendente'}
+                </p>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/dashboard/app/components/SearchFilter.jsx

@@ -1,22 +1,40 @@
-import { useState } from 'react';
-
-export default function SearchFilter({ placeholder = 'Search...', filters = [], onSearchChange, onFilterChange }) {
-  const [search, setSearch] = useState('');
-  function handleSearchChange(e) {
-    setSearch(e.target.value);
-    onSearchChange?.(e.target.value);
-  }
-  return (
-    <div className="flex items-center gap-3 p-3 bg-gray-900 border-b border-gray-800">
-      <input type="text" value={search} onChange={handleSearchChange} placeholder={placeholder}
-        className="flex-1 bg-gray-800 border border-gray-700 rounded-md px-3 py-1.5 text-sm text-gray-100 placeholder-gray-500 focus:outline-none focus:border-blue-500" />
-      {filters.map(({ name, label, options, value }) => (
-        <select key={name} value={value} onChange={(e) => onFilterChange?.(name, e.target.value)}
-          className="bg-gray-800 border border-gray-700 rounded-md px-2 py-1.5 text-sm text-gray-300 focus:outline-none focus:border-blue-500">
-          <option value="">{label}: All</option>
-          {options.map((opt) => (<option key={opt} value={opt}>{opt}</option>))}
-        </select>
-      ))}
-    </div>
-  );
-}
+import { useState } from 'react';
+import { MagnifyingGlass } from '@phosphor-icons/react';
+
+/**
+ * The toolbar of the knowledge pages: a search box and a few selects. The
+ * `value` of each filter is controlled by the page; the search text is local.
+ */
+export default function SearchFilter({ placeholder = 'Buscar', filters = [], onSearchChange, onFilterChange, children }) {
+  const [search, setSearch] = useState('');
+  function handleSearchChange(e) {
+    setSearch(e.target.value);
+    onSearchChange?.(e.target.value);
+  }
+  return (
+    <div className="relative z-10 flex flex-wrap items-center gap-2 border-b border-[var(--color-hair)] bg-[var(--color-ink)]/70 px-4 py-3 backdrop-blur md:px-6">
+      <label className="relative min-w-[12rem] flex-1">
+        <span className="sr-only">{placeholder}</span>
+        <MagnifyingGlass weight="light" size={16} className="pointer-events-none absolute left-3.5 top-1/2 -translate-y-1/2 text-[var(--color-faint)]" />
+        <input
+          type="text" value={search} onChange={handleSearchChange} placeholder={placeholder}
+          onKeyDown={(e) => { if (e.key === 'Escape') handleSearchChange({ target: { value: '' } }); }}
+          className="fluid w-full rounded-full bg-white/[0.04] py-2 pl-10 pr-4 text-sm text-[var(--color-fg)] shadow-[inset_0_0_0_1px_var(--color-hair)] outline-none transition-shadow placeholder:text-[var(--color-faint)] focus:shadow-[inset_0_0_0_1px_var(--color-hair-strong)]"
+        />
+      </label>
+      {filters.map(({ name, label, options, value }) => (
+        <label key={name} className="text-sm">
+          <span className="sr-only">{label}</span>
+          <select
+            value={value} onChange={(e) => onFilterChange?.(name, e.target.value)}
+            className="fluid rounded-full bg-white/[0.04] px-3 py-2 text-sm text-[var(--color-fg)] shadow-[inset_0_0_0_1px_var(--color-hair)] outline-none"
+          >
+            <option value="">{label}: todos</option>
+            {options.map((opt) => (<option key={opt} value={opt}>{opt}</option>))}
+          </select>
+        </label>
+      ))}
+      {children}
+    </div>
+  );
+}