@polymorphism-tech/morph-spec 8.38.0 → 8.41.0

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>
+  );
+}

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

@@ -1,44 +1,153 @@
-import { NavLink } from 'react-router-dom';
-
-const NAV_ITEMS = [
-  { to: '/agents', label: 'Agent Map', icon: '🗺️' },
-  { to: '/phases', label: 'Phases', icon: '⚡' },
-  { to: '/hooks', label: 'Hooks', icon: '🔗' },
-  { to: '/skills', label: 'Skills', icon: '🧩' },
-  { to: '/rules', label: 'Rules', icon: '📏' },
-  { to: '/standards', label: 'Standards', icon: '📋' },
-  { to: '/state', label: 'Live State', icon: '📊' },
+import { NavLink, useLocation, useNavigate } from 'react-router-dom';
+import {
+  MagnifyingGlass, SquaresFour, Kanban, Pulse, BookOpen, FlowArrow, PuzzlePiece, UsersThree, Books, Ruler, Plug, Scales,
+} from '@phosphor-icons/react';
+import { projectHref } from '../lib/project.js';
+
+const KNOWLEDGE = [
+  { to: '/guide', label: 'Guia', icon: BookOpen },
+  { to: '/phases', label: 'Fases', icon: FlowArrow },
+  { to: '/skills', label: 'Skills', icon: PuzzlePiece },
+  { to: '/agents', label: 'Personas', icon: UsersThree },
+  { to: '/standards', label: 'Standards', icon: Books },
+  { to: '/rules', label: 'Rules', icon: Ruler },
+  { to: '/hooks', label: 'Hooks', icon: Plug },
+  { to: '/rubrics', label: 'Rubricas', icon: Scales },
 ];
 
-export default function Sidebar() {
+function Badge({ pulse }) {
+  if (!pulse) return null;
+  if (pulse.awaiting) {
+    return <span className="ml-auto rounded-full bg-[var(--color-warn)]/15 px-1.5 font-mono text-[11px] text-[var(--color-warn)]" title="features esperando você">{pulse.awaiting}</span>;
+  }
+  if (pulse.working) {
+    return <span className="ml-auto h-1.5 w-1.5 rounded-full bg-[var(--color-phase-implement)]" title="agente trabalhando agora" />;
+  }
+  return pulse.active ? <span className="ml-auto font-mono text-[11px] text-[var(--color-faint)]">{pulse.active}</span> : null;
+}
+
+const linkClass = ({ isActive }) => [
+  'fluid flex items-center gap-2.5 rounded-lg px-3 py-1.5 text-sm transition-colors',
+  isActive ? 'bg-white/[0.08] text-[var(--color-fg)] shadow-[inset_0_1px_0_rgb(255_255_255_/_0.06)]' : 'text-[var(--color-dim)] hover:bg-white/[0.04] hover:text-[var(--color-fg)]',
+].join(' ');
+
+/**
+ * Switching project keeps the page: from a feature's detail it lands on the
+ * other project's feature list, from Activity on the other project's Activity.
+ */
+function ProjectSwitcher({ portfolio, current }) {
+  const navigate = useNavigate();
+  const { pathname } = useLocation();
+  const onChange = (id) => {
+    const sub = /^\/p\/[^/]+\/activity/.test(pathname) ? 'activity' : 'features';
+    navigate(projectHref(id, sub));
+  };
+  return (
+    <label className="mx-1 mb-1 block">
+      <span className="sr-only">Trocar de projeto</span>
+      <select
+        value={current || ''}
+        onChange={(e) => onChange(e.target.value)}
+        className="fluid w-full truncate rounded-lg bg-white/[0.04] px-2.5 py-1.5 text-sm font-medium text-[var(--color-fg)] shadow-[inset_0_0_0_1px_var(--color-hair)] outline-none"
+      >
+        {portfolio.projects.map((p) => <option key={p.id} value={p.id}>{p.name}</option>)}
+      </select>
+    </label>
+  );
+}
+
+export default function Sidebar({ portfolio, current, pulse, onSearch }) {
+  const projects = portfolio?.projects || [];
+  const currentName = projects.find((p) => p.id === current)?.name;
   return (
-    <nav className="w-52 flex-shrink-0 bg-gray-900 border-r border-gray-800 flex flex-col">
-      <div className="px-4 py-4 border-b border-gray-800">
-        <h1 className="text-sm font-semibold text-gray-300 tracking-wide uppercase">
-          morph-spec
-        </h1>
-        <p className="text-xs text-gray-500 mt-0.5">Dashboard</p>
+    <nav aria-label="Navegação principal" className="relative z-10 hidden w-56 shrink-0 flex-col p-3 md:flex">
+      <div className="bezel flex flex-1 flex-col">
+        <div className="bezel-core flex flex-1 flex-col overflow-y-auto px-2 py-4">
+          <p className="px-3 pb-4 text-[15px] font-semibold tracking-tight">morph<span className="text-[var(--color-faint)]">-spec</span></p>
+          <button
+            type="button"
+            onClick={onSearch}
+            className="fluid mx-1 mb-5 flex items-center gap-2 rounded-lg px-2.5 py-1.5 text-sm text-[var(--color-faint)] shadow-[inset_0_0_0_1px_var(--color-hair)] transition-colors hover:text-[var(--color-dim)]"
+          >
+            <MagnifyingGlass weight="light" size={15} /> Buscar
+            <kbd className="ml-auto font-mono text-[11px]">Ctrl K</kbd>
+          </button>
+
+          <ul className="mb-4">
+            <li>
+              <NavLink to="/" end className={linkClass}>
+                <SquaresFour weight="light" size={17} aria-hidden="true" /> Portfólio
+                {pulse?.awaiting > 0 && <Badge pulse={{ awaiting: pulse.awaiting }} />}
+              </NavLink>
+            </li>
+          </ul>
+
+          {current && (
+            <div className="mb-5">
+              <p className="px-3 pb-1.5 text-xs text-[var(--color-faint)]">Projeto</p>
+              {projects.length > 1
+                ? <ProjectSwitcher portfolio={portfolio} current={current} />
+                : <p className="truncate px-3 pb-1 text-sm font-medium">{currentName}</p>}
+              <ul>
+                <li>
+                  <NavLink to={projectHref(current)} className={linkClass}>
+                    <Kanban weight="light" size={17} aria-hidden="true" /> Features
+                    <Badge pulse={pulse?.byProject?.[current]} />
+                  </NavLink>
+                </li>
+                <li>
+                  <NavLink to={projectHref(current, 'activity')} className={linkClass}>
+                    <Pulse weight="light" size={17} aria-hidden="true" /> Atividade
+                  </NavLink>
+                </li>
+              </ul>
+            </div>
+          )}
+
+          <div className="mb-5">
+            <p className="px-3 pb-1.5 text-xs text-[var(--color-faint)]">Como funciona</p>
+            <ul>
+              {KNOWLEDGE.map(({ to, label, icon: Icon }) => (
+                <li key={to}>
+                  <NavLink to={to} className={linkClass}>
+                    <Icon weight="light" size={17} aria-hidden="true" />
+                    {label}
+                  </NavLink>
+                </li>
+              ))}
+            </ul>
+          </div>
+        </div>
       </div>
-      <ul className="flex-1 py-2">
-        {NAV_ITEMS.map(({ to, label, icon }) => (
-          <li key={to}>
-            <NavLink
-              to={to}
-              className={({ isActive }) =>
-                [
-                  'flex items-center gap-2.5 px-4 py-2 text-sm transition-colors',
-                  isActive
-                    ? 'bg-blue-900/40 border-r-2 border-blue-500 text-blue-300'
-                    : 'text-gray-400 hover:bg-gray-800 hover:text-gray-200',
-                ].join(' ')
-              }
-            >
-              <span className="text-base leading-none">{icon}</span>
-              <span>{label}</span>
-            </NavLink>
-          </li>
-        ))}
-      </ul>
+    </nav>
+  );
+}
+
+/** The same destinations as a compact bar for narrow screens. */
+export function MobileNav({ current, onSearch }) {
+  const items = [
+    { to: '/', label: 'Portfólio' },
+    ...(current ? [{ to: projectHref(current), label: 'Features' }, { to: projectHref(current, 'activity'), label: 'Atividade' }] : []),
+    ...KNOWLEDGE,
+  ];
+  return (
+    <nav aria-label="Navegação" className="sticky top-0 z-20 flex gap-1 overflow-x-auto [scrollbar-width:none] border-b border-[var(--color-hair)] bg-[var(--color-ink)]/85 px-3 py-2 backdrop-blur md:hidden">
+      <button type="button" onClick={onSearch} aria-label="Buscar" className="shrink-0 rounded-full px-2.5 py-1 text-[var(--color-dim)]">
+        <MagnifyingGlass weight="light" size={16} />
+      </button>
+      {items.map(({ to, label }) => (
+        <NavLink
+          key={to}
+          to={to}
+          end={to === '/'}
+          className={({ isActive }) => [
+            'shrink-0 rounded-full px-3 py-1 text-sm',
+            isActive ? 'bg-white/[0.1] text-[var(--color-fg)]' : 'text-[var(--color-dim)]',
+          ].join(' ')}
+        >
+          {label}
+        </NavLink>
+      ))}
     </nav>
   );
 }

package/src/dashboard/app/hooks/useMorphQuery.js

@@ -0,0 +1,54 @@
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Fetch a `/api/morph/*` resource and refetch it whenever the dev server
+ * reports that the project's `.morph/` changed in the given scope.
+ *
+ * `scope` matches the server's invalidation: 'features' (feature.json,
+ * tasks.json, artifacts) or 'activity' (events.jsonl). A refetch keeps the old
+ * data on screen until the new one arrives — no flash of "loading" while an
+ * agent is working.
+ *
+ * @param {string|null} url - null skips the request
+ * @param {{ scope?: string|string[], project?: string }} [opts] - `scope`: 'features',
+ *   'activity' or 'projects'; `project`: only changes of this project refetch
+ * @returns {{ data: any, error: string|null, loading: boolean, refreshedAt: number|null, refetch: () => void }}
+ */
+export function useMorphQuery(url, { scope = 'features', project } = {}) {
+  const [state, setState] = useState({ data: null, error: null, loading: Boolean(url), refreshedAt: null });
+  const [tick, setTick] = useState(0);
+  const urlRef = useRef(url);
+
+  useEffect(() => {
+    if (urlRef.current !== url) {
+      urlRef.current = url;
+      setState({ data: null, error: null, loading: Boolean(url), refreshedAt: null });
+    }
+    if (!url) return undefined;
+    let cancelled = false;
+    fetch(url)
+      .then(async (res) => {
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok) throw new Error(body.error || `HTTP ${res.status}`);
+        return body;
+      })
+      .then((data) => { if (!cancelled) setState({ data, error: null, loading: false, refreshedAt: Date.now() }); })
+      .catch((err) => { if (!cancelled) setState((s) => ({ ...s, error: err.message, loading: false })); });
+    return () => { cancelled = true; };
+  }, [url, tick]);
+
+  const scopes = Array.isArray(scope) ? scope.join(',') : scope;
+  useEffect(() => {
+    const hot = import.meta.hot;
+    if (!hot) return undefined;
+    const wanted = scopes.split(',');
+    const onChange = (payload) => {
+      if (payload?.project && project && payload.project !== project) return;
+      if (!payload?.scope || wanted.includes(payload.scope)) setTick((t) => t + 1);
+    };
+    hot.on('morph:changed', onChange);
+    return () => hot.off?.('morph:changed', onChange);
+  }, [scopes, project]);
+
+  return { ...state, refetch: () => setTick((t) => t + 1) };
+}

package/src/dashboard/app/hooks/usePref.js

@@ -0,0 +1,38 @@
+import { useCallback, useEffect, useState } from 'react';
+
+const PREFIX = 'morph-dashboard:';
+
+function read(key, fallback) {
+  try {
+    const raw = window.localStorage.getItem(PREFIX + key);
+    return raw === null ? fallback : JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * A per-browser preference (view mode, filters). Storage can be unavailable or
+ * throw (private mode, SSR); the value then simply does not persist.
+ */
+export function usePref(key, fallback) {
+  const [value, setValue] = useState(() => (typeof window === 'undefined' ? fallback : read(key, fallback)));
+  const set = useCallback((next) => {
+    setValue((prev) => {
+      const v = typeof next === 'function' ? next(prev) : next;
+      try { window.localStorage.setItem(PREFIX + key, JSON.stringify(v)); } catch { /* not persisted */ }
+      return v;
+    });
+  }, [key]);
+  return [value, set];
+}
+
+/** Re-render every `ms` so relative times ("há 30 s") and "working now" stay true. */
+export function useNow(ms = 15_000) {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const id = setInterval(() => setNow(Date.now()), ms);
+    return () => clearInterval(id);
+  }, [ms]);
+  return now;
+}

package/src/dashboard/app/lib/format.js

@@ -0,0 +1,69 @@
+const rtf = new Intl.RelativeTimeFormat('pt-BR', { numeric: 'auto' });
+const UNITS = [
+  ['year', 365 * 24 * 3600],
+  ['month', 30 * 24 * 3600],
+  ['week', 7 * 24 * 3600],
+  ['day', 24 * 3600],
+  ['hour', 3600],
+  ['minute', 60],
+];
+
+/** "há 12 minutos" — or an em dash when there is no date. */
+export function timeAgo(iso, now = Date.now()) {
+  const t = Date.parse(iso || '');
+  if (Number.isNaN(t)) return '—';
+  const diff = (t - now) / 1000;
+  for (const [unit, secs] of UNITS) {
+    if (Math.abs(diff) >= secs) return rtf.format(Math.round(diff / secs), unit);
+  }
+  return 'agora';
+}
+
+export function dateTime(iso) {
+  const t = Date.parse(iso || '');
+  if (Number.isNaN(t)) return '—';
+  return new Date(t).toLocaleString('pt-BR', { dateStyle: 'short', timeStyle: 'short' });
+}
+
+export function clock(iso) {
+  const t = Date.parse(iso || '');
+  if (Number.isNaN(t)) return '—';
+  return new Date(t).toLocaleTimeString('pt-BR', { hour: '2-digit', minute: '2-digit' });
+}
+
+export function dayLabel(iso) {
+  const t = Date.parse(iso || '');
+  if (Number.isNaN(t)) return '—';
+  return new Date(t).toLocaleDateString('pt-BR', { weekday: 'long', day: 'numeric', month: 'long' });
+}
+
+const compact = new Intl.NumberFormat('pt-BR', { notation: 'compact', maximumFractionDigits: 1 });
+export function num(n) {
+  return typeof n === 'number' && Number.isFinite(n) ? compact.format(n) : '—';
+}
+
+export function bytes(n) {
+  if (typeof n !== 'number' || !Number.isFinite(n)) return '—';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+
+export function duration(seconds) {
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) return '—';
+  const m = Math.round(seconds / 60);
+  if (m < 60) return `${m} min`;
+  return `${Math.floor(m / 60)} h ${m % 60} min`;
+}
+
+/** Strip a leading YAML frontmatter block, returning both parts. */
+export function splitFrontmatter(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text || '');
+  if (!m) return { meta: null, body: text || '' };
+  const meta = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([\w-]+):\s*(.*)$/.exec(line);
+    if (kv) meta[kv[1]] = kv[2].replace(/^["']|["']$/g, '');
+  }
+  return { meta, body: text.slice(m[0].length) };
+}

package/src/dashboard/app/lib/phases.js

@@ -0,0 +1,56 @@
+/**
+ * Display vocabulary for the phase pipeline. The ORDER and the optional flag
+ * come from framework/phases.json (morphData.phases); this file only adds the
+ * words and the colour token each phase is shown with.
+ */
+import morphData from 'virtual:morph-data';
+
+const LABELS = {
+  proposal: 'Proposta',
+  uiux: 'UI/UX',
+  plan: 'Plano',
+  implement: 'Implementação',
+  review: 'Revisão',
+};
+
+export const PHASES = (morphData.phases?.list || []).map((p) => ({
+  id: p.id,
+  label: LABELS[p.id] || p.displayName || p.id,
+  optional: Boolean(p.optional),
+  folder: p.folder || null,
+  skill: p.skill || null,
+  color: `var(--color-phase-${p.id})`,
+}));
+
+export const PHASE_INDEX = Object.fromEntries(PHASES.map((p, i) => [p.id, i]));
+
+export function phaseMeta(id) {
+  return PHASES.find((p) => p.id === id) || { id, label: LABELS[id] || id || '—', color: 'var(--color-faint)', optional: false };
+}
+
+export const GATE_LABEL = {
+  proposal: 'Gate 1 (proposta)',
+  uiux: 'Gate UI/UX',
+  plan: 'Gate 2 (plano)',
+  review: 'Gate 3 (revisão)',
+};
+
+export const STATUS_LABEL = {
+  draft: 'Rascunho',
+  in_progress: 'Em andamento',
+  completed: 'Concluída',
+  abandoned: 'Abandonada',
+};
+
+export const WORKTYPE_LABEL = {
+  feature: 'feature',
+  bug: 'bug',
+  chore: 'chore',
+  hotfix: 'hotfix',
+};
+
+export const LOCATION_LABEL = {
+  root: 'raiz',
+  worktree: 'worktree',
+  archive: 'arquivo',
+};

package/src/dashboard/app/lib/project.js

@@ -0,0 +1,50 @@
+import { useEffect, useRef } from 'react';
+import { useLocation } from 'react-router-dom';
+import { usePref } from '../hooks/usePref.js';
+import { useMorphQuery } from '../hooks/useMorphQuery.js';
+
+/** The live API of one project. */
+export const apiBase = (id) => `/api/morph/p/${encodeURIComponent(id)}`;
+
+/** A page of one project: `/p/{id}/features`, `/p/{id}/features/{name}`, `/p/{id}/activity`. */
+export const projectHref = (id, sub = 'features') => `/p/${encodeURIComponent(id)}/${sub}`;
+
+export const featureHref = (project, name, query = '') =>
+  projectHref(project, `features/${encodeURIComponent(name)}`) + query;
+
+const PROJECTS_CHANGED = 'morph:projects-changed';
+
+/** Tell every reader of the portfolio (page, sidebar, search) to read it again. */
+export const announceProjectsChanged = () => window.dispatchEvent(new Event(PROJECTS_CHANGED));
+
+/** The portfolio: registered projects, their summaries, and the ones found next to them. */
+export function useProjects() {
+  const q = useMorphQuery('/api/morph/projects', { scope: 'projects' });
+  const refetch = useRef(q.refetch);
+  refetch.current = q.refetch;
+  useEffect(() => {
+    const on = () => refetch.current();
+    window.addEventListener(PROJECTS_CHANGED, on);
+    return () => window.removeEventListener(PROJECTS_CHANGED, on);
+  }, []);
+  return q;
+}
+
+/**
+ * The project the person is looking at: the one in the URL, else the last one
+ * they opened, else the one the dashboard was launched from. Knowledge pages
+ * have no project in the URL but the sidebar still needs one to link to.
+ *
+ * @param {{ launch?: string|null, projects?: Array<{id: string}> }|null} portfolio
+ * @returns {{ id: string|null, inUrl: boolean }}
+ */
+export function useCurrentProject(portfolio) {
+  const { pathname } = useLocation();
+  const m = /^\/p\/([^/]+)/.exec(pathname);
+  const fromUrl = m ? decodeURIComponent(m[1]) : null;
+  const [last, setLast] = usePref('project.last', null);
+  useEffect(() => { if (fromUrl && fromUrl !== last) setLast(fromUrl); }, [fromUrl, last, setLast]);
+  const known = (id) => id && (!portfolio?.projects || portfolio.projects.some((p) => p.id === id));
+  const id = fromUrl || (known(last) ? last : null) || portfolio?.launch || null;
+  return { id, inUrl: Boolean(fromUrl) };
+}