aimeat 1.2.0

package/dist/public/views/profile/foundry-dashboard/use-dashboard-core.js

@@ -0,0 +1,154 @@
+/**
+ * @file use-dashboard-core.js
+ * @description Shared data layer for all dashboard hooks — owns the project record,
+ *   component list, interview spec, selected component ID, and live statuses.
+ *   Every domain hook (useAutopilot, useTestExecution, useEditMode, usePackaging,
+ *   useLifecycle) receives this hook's return value as its `core` parameter.
+ *
+ *   This is the foundation of the hook-per-domain architecture for ProjectDashboard.
+ *   It provides:
+ *   - loadData(): central data refresh that reloads project, components, interviewSpec
+ *   - refreshStatuses(): polls live extension/cortex status
+ *   - advanceToNext(): selects the next unregistered component in phase order
+ *   - pendingEdit: raw pending edit data for useEditMode to restore from
+ *   - Auto-select: first incomplete component selected on mount
+ *   - SSE: listens for aimeat-live-update events and auto-refreshes
+ *
+ *   Architecture: ProjectDashboard shell → useDashboardCore()
+ *                   → core passed to all domain hooks as first parameter
+ *
+ * @structure
+ *   - useDashboardCore(projectId, onBack, showToast): custom hook
+ *     State: project, components, interviewSpec, selectedId, liveStatuses, pendingEdit
+ *     Functions: loadData, refreshStatuses, advanceToNext
+ *     Effects: mount load, SSE listener, auto-select, status poll
+ * @usage
+ *   import { useDashboardCore } from './foundry-dashboard/use-dashboard-core.js';
+ *   const core = useDashboardCore(projectId, onBack, showToast);
+ * @version-history
+ *   v1.0.0 — 2026-03-22 — Extracted from foundry-tab.js ProjectDashboard
+ *   v1.1.0 — 2026-03-26 — Enrich multi-pass components with initial passes on load
+ */
+import { useState, useEffect } from 'preact/hooks';
+import { t } from '/js/i18n.js';
+import {
+  getProject, loadAllComponents, saveComponent, cleanupOldEntries,
+  getInterviewSpec, getComponentStatuses, getPendingEdit,
+  createInitialPasses, MULTI_PASS_TYPES,
+} from '/js/services/foundry.js';
+
+/**
+ * @param {string} projectId
+ * @param {Function} onBack — called when project is deleted/missing
+ * @param {Function} showToast
+ */
+export function useDashboardCore(projectId, onBack, showToast) {
+  const [project, setProject] = useState(null);
+  const [components, setComponents] = useState([]);
+  const [interviewSpec, setInterviewSpec] = useState(null);
+  const [selectedId, setSelectedId] = useState(null);
+  const [liveStatuses, setLiveStatuses] = useState({});
+  const [pendingEdit, setPendingEdit] = useState(null);
+
+  // Load on mount
+  useEffect(() => { loadData(); }, [projectId]);
+
+  // SSE live updates — instant refresh when data changes
+  useEffect(() => {
+    const handler = () => loadData();
+    window.addEventListener('aimeat-live-update', handler);
+    return () => window.removeEventListener('aimeat-live-update', handler);
+  }, [projectId]);
+
+  async function loadData() {
+    const p = await getProject(projectId);
+    if (!p || !p.projectId) {
+      onBack();
+      return;
+    }
+    setProject(p);
+    // Load interview spec BEFORE components — prompts need it for locale/data source threading
+    try {
+      const spec = await getInterviewSpec(projectId);
+      setInterviewSpec(spec);
+    } catch { /* no interview spec — that's fine */ }
+    if (p?.blueprint?.components) {
+      const comps = await loadAllComponents(projectId);
+      if (comps.length > 0) {
+        // Enrich multi-pass components with initial passes if they don't have any
+        let enriched = false;
+        for (const comp of comps) {
+          if (MULTI_PASS_TYPES.includes(comp.type) && (!comp.passes || comp.passes.length === 0)) {
+            comp.passes = createInitialPasses(comp.type);
+            await saveComponent(projectId, comp);
+            enriched = true;
+          }
+        }
+        setComponents(enriched ? [...comps] : comps);
+      } else {
+        // Blueprint exists but no component records yet — initialize them
+        const initialized = [];
+        for (const c of p.blueprint.components) {
+          const comp = { id: c.id, type: c.type, label: c.label, status: 'not_started', prompt: null, result: null, validationErrors: [], registeredAs: null, history: [], _version: 0 };
+          await saveComponent(projectId, comp);
+          initialized.push(comp);
+        }
+        setComponents(initialized);
+      }
+    }
+    cleanupOldEntries(projectId).catch(() => {});
+    // Load pending edit data (useEditMode watches this to restore its state)
+    try {
+      const pending = await getPendingEdit(projectId);
+      if (pending) setPendingEdit(pending);
+    } catch { /* no pending edit */ }
+  }
+
+  // Refresh live statuses
+  async function refreshStatuses() {
+    try {
+      const s = await getComponentStatuses(projectId);
+      setLiveStatuses(s);
+    } catch { /* best effort */ }
+  }
+
+  useEffect(() => { if (project) refreshStatuses(); }, [project]);
+
+  // Advance to next unregistered component in phase order
+  function advanceToNext(currentId) {
+    const phases = project?.blueprint?.phases || [];
+    const phaseOrder = phases.flatMap(p => p.componentIds || []);
+    const idx = phaseOrder.indexOf(currentId);
+    for (let i = idx + 1; i < phaseOrder.length; i++) {
+      const comp = components.find(c => c.id === phaseOrder[i]);
+      if (comp && !comp.registeredAs) {
+        setSelectedId(phaseOrder[i]);
+        return;
+      }
+    }
+    showToast?.(t('profile.foundry.allComponentsRegistered'));
+  }
+
+  // Auto-select first incomplete component when components change
+  useEffect(() => {
+    if (!selectedId && components.length > 0) {
+      const phases = project?.blueprint?.phases || [];
+      const phaseOrder = phases.flatMap(p => p.componentIds || []);
+      if (phaseOrder.length > 0) {
+        const first = phaseOrder.find(cid => {
+          const comp = components.find(c => c.id === cid);
+          return comp && !comp.registeredAs;
+        });
+        if (first) setSelectedId(first);
+        else setSelectedId(phaseOrder[0]);
+      }
+    }
+  }, [components.length]);
+
+  return {
+    project, components, interviewSpec,
+    selectedId, setSelectedId,
+    liveStatuses, pendingEdit,
+    loadData, refreshStatuses, advanceToNext,
+  };
+}

package/dist/public/views/profile/foundry-dashboard/use-edit-mode.js

@@ -0,0 +1,294 @@
+/**
+ * @file use-edit-mode.js
+ * @description Custom hook for the edit service flow — change request → impact
+ *   analysis → targeted per-component edits. Supports both manual (copy prompt)
+ *   and AI-driven (single or batch) edit modes.
+ *
+ *   Part of the hook-per-domain architecture for ProjectDashboard. This hook owns
+ *   all edit-mode state (mode, change request, impact analysis result, parsed impact,
+ *   errors, AI running indicator) and exposes handlers for the full edit workflow.
+ *
+ *   Uses autopilotState (from useAutopilotState) for batch edit operations —
+ *   handleRunAllEditsAi uses autopilotState.start/finish/setStep/cancelledRef
+ *   to share the autopilot UI with the generation pipeline.
+ *
+ *   Restores pending edit state from useDashboardCore.pendingEdit on load.
+ *
+ *   Architecture: useDashboardCore → useEditMode ← useAutopilotState
+ *                   → EditModePanel (sub-component)
+ *
+ * @structure
+ *   - useEditMode(core, autopilotState, projectId, orSettings, session, showToast): custom hook
+ *     State: editMode, changeRequest, impactResult, impactParsed, impactErrors, aiRunning
+ *     Handlers: exitEditMode, handleCopyImpactPrompt, handleRunImpactAi, handleParseImpact,
+ *               handleRunAllEditsAi, handleCopyEditPrompt, handleRunSingleEditAi
+ * @usage
+ *   import { useEditMode } from './foundry-dashboard/use-edit-mode.js';
+ *   const edit = useEditMode(core, autopilotState, projectId, orSettings, session, showToast);
+ * @version-history
+ *   v1.0.0 — 2026-03-22 — Extracted from foundry-tab.js ProjectDashboard
+ */
+import { useState, useEffect } from 'preact/hooks';
+import { t } from '/js/i18n.js';
+import {
+  loadAllComponents, saveComponent, registerComponent, writeProjectLog,
+  savePendingEdit, clearPendingEdit,
+} from '/js/services/foundry.js';
+import { buildImpactPrompt, buildEditPrompt, buildFixPrompt } from '/js/services/foundry-prompts.js';
+import { validateComponent } from '/js/services/foundry-validate.js';
+import { runWithAi, stripCodeblock } from '../foundry-detail.js';
+
+/** History helper — creates a new component object with a history entry appended */
+function addHistory(comp, action, extra = {}) {
+  return { ...comp, history: [...(comp.history || []), { action, at: new Date().toISOString(), by: 'autopilot', ...extra }] };
+}
+
+/**
+ * @param {Object} core — useDashboardCore return value
+ * @param {Object} autopilotState — useAutopilotState return value
+ * @param {string} projectId
+ * @param {Object} orSettings — { hasApiKey, autoRetry, maxRetries }
+ * @param {Object} session
+ * @param {Function} showToast
+ */
+export function useEditMode(core, autopilotState, projectId, orSettings, session, showToast) {
+  const [editMode, setEditMode] = useState(null);
+  const [changeRequest, setChangeRequest] = useState('');
+  const [impactResult, setImpactResult] = useState('');
+  const [impactParsed, setImpactParsed] = useState(null);
+  const [impactErrors, setImpactErrors] = useState([]);
+  const [aiRunning, setAiRunning] = useState(null);
+
+  // Restore pending edit when core loads it
+  useEffect(() => {
+    if (core.pendingEdit) {
+      setChangeRequest(core.pendingEdit.changeRequest || '');
+      setImpactParsed(core.pendingEdit.impactParsed || null);
+      setImpactResult(core.pendingEdit.impactResult || '');
+      setEditMode(core.pendingEdit.impactParsed ? 'editing' : 'request');
+    }
+  }, [core.pendingEdit]);
+
+  function exitEditMode() {
+    setEditMode(null);
+    setChangeRequest('');
+    setImpactResult('');
+    setImpactParsed(null);
+    setImpactErrors([]);
+    clearPendingEdit(projectId).catch(() => {});
+  }
+
+  function handleCopyImpactPrompt() {
+    const prompt = buildImpactPrompt(changeRequest, core.project?.blueprint);
+    navigator.clipboard.writeText(prompt).catch(() => {});
+    showToast?.(t('profile.foundry.impactPromptCopied'));
+    setEditMode('impact');
+  }
+
+  async function handleRunImpactAi() {
+    if (!orSettings?.hasApiKey) return;
+    setAiRunning('impact');
+    try {
+      const prompt = buildImpactPrompt(changeRequest, core.project?.blueprint);
+      const content = await runWithAi(projectId, prompt);
+      setImpactResult(content);
+      setEditMode('impact');
+      // Auto-parse
+      let text = content.trim();
+      const jsonMatch = text.match(/```json\s*\n([\s\S]*?)```/i);
+      if (jsonMatch) text = jsonMatch[1].trim();
+      const parsed = JSON.parse(text);
+      if (parsed.analysis && Array.isArray(parsed.analysis)) {
+        setImpactParsed(parsed);
+        setImpactErrors([]);
+        setEditMode('editing');
+        savePendingEdit(projectId, { changeRequest, impactParsed: parsed, impactResult: content }).catch(() => {});
+      }
+    } catch (e) {
+      showToast?.(e.message, true);
+    }
+    setAiRunning(null);
+  }
+
+  function handleParseImpact() {
+    try {
+      let text = impactResult.trim();
+      const jsonMatch = text.match(/```json\s*\n([\s\S]*?)```/i);
+      if (jsonMatch) text = jsonMatch[1].trim();
+      const parsed = JSON.parse(text);
+      if (!parsed.analysis || !Array.isArray(parsed.analysis)) {
+        setImpactErrors([t('profile.foundry.impactArrayRequired')]);
+        return;
+      }
+      setImpactParsed(parsed);
+      setImpactErrors([]);
+      setEditMode('editing');
+      savePendingEdit(projectId, { changeRequest, impactParsed: parsed, impactResult }).catch(() => {});
+    } catch (e) {
+      setImpactErrors([t('profile.foundry.invalidJson').replace('{error}', e.message)]);
+    }
+  }
+
+  async function handleRunAllEditsAi() {
+    if (!orSettings?.hasApiKey || !impactParsed?.analysis) return;
+    autopilotState.start();
+    try {
+      const editable = impactParsed.analysis.filter(a => a.impact === 'root' || a.impact === 'update');
+      for (const item of editable) {
+        if (autopilotState.cancelledRef.current) break;
+        // Read core.components inline (not destructured) to avoid stale closure
+        const comp = core.components.find(c => c.id === item.id);
+        if (!comp) continue;
+        autopilotState.setStep(comp.label);
+        core.setSelectedId(comp.id);
+
+        const upstream = impactParsed.analysis
+          .filter(a => a.impact === 'root' && a.id !== comp.id)
+          .map(a => `- ${a.label}: ${a.suggestedChange}`)
+          .join('\n') || '';
+        const prompt = buildEditPrompt(
+          comp.type, comp.label,
+          comp.result || '(no current code)',
+          item.suggestedChange || changeRequest,
+          upstream || null,
+        );
+
+        let content;
+        try {
+          content = await runWithAi(projectId, prompt);
+        } catch (e) {
+          showToast?.(`${comp.label}: ${e.message}`, true);
+          break;
+        }
+        if (autopilotState.cancelledRef.current) break;
+        content = stripCodeblock(content);
+
+        let vr = validateComponent(comp.type, content, core.project?.blueprint);
+
+        if (!vr.valid && orSettings?.autoRetry) {
+          const max = orSettings.maxRetries || 3;
+          for (let attempt = 1; attempt <= max && !vr.valid; attempt++) {
+            if (autopilotState.cancelledRef.current) break;
+            autopilotState.setStep(
+              comp.label + ' - ' + t('profile.foundry.openrouter.retrying').replace('{current}', attempt).replace('{max}', max)
+            );
+            const fp = buildFixPrompt(prompt, content, vr.errors, comp.type);
+            try { content = await runWithAi(projectId, fp); } catch (e) { break; }
+            content = stripCodeblock(content);
+            vr = validateComponent(comp.type, content, core.project?.blueprint);
+          }
+        }
+
+        if (!vr.valid) {
+          const errored = addHistory(comp, 'validation_failed', { errors: vr.errors, by: 'autopilot' });
+          await saveComponent(projectId, { ...errored, status: 'errors', result: content, validationErrors: vr.errors });
+          await core.loadData();
+          showToast?.(t('profile.foundry.openrouter.stepFailed') + ': ' + comp.label, true);
+          break;
+        }
+
+        const updated = addHistory(comp, 'edited', { by: 'autopilot', change: item.suggestedChange });
+        await saveComponent(projectId, { ...updated, status: 'done', result: content, validationErrors: [] });
+
+        try {
+          const serviceSlug = core.components.find(c => c.type === 'csm' && c.registeredAs)?.registeredAs?.split('/')?.pop() || '';
+          if (comp.type === 'cortex') {
+            const cortexVr = validateComponent('cortex', content, core.project?.blueprint);
+            await registerComponent('cortex', cortexVr.extracted, session, serviceSlug);
+          } else {
+            await registerComponent(comp.type, vr.extracted || content, session, serviceSlug);
+          }
+          await writeProjectLog(projectId, 'component_edited', { meta: { component: comp.label, by: 'autopilot' } });
+        } catch (e) {
+          showToast?.(`${comp.label}: Registration failed: ${e.message}`, true);
+          await core.loadData();
+          break;
+        }
+        await core.loadData();
+      }
+    } catch (e) {
+      showToast?.(e.message, true);
+    }
+    autopilotState.finish();
+    showToast?.(t('profile.foundry.openrouter.stepComplete'));
+  }
+
+  function handleCopyEditPrompt(comp, suggestedChange) {
+    const upstream = impactParsed?.analysis
+      ?.filter(a => a.impact === 'root' && a.id !== comp.id)
+      ?.map(a => `- ${a.label}: ${a.suggestedChange}`)
+      ?.join('\n') || '';
+    const prompt = buildEditPrompt(
+      comp.type, comp.label,
+      comp.result || '(no current code)',
+      suggestedChange || changeRequest,
+      upstream || null,
+    );
+    navigator.clipboard.writeText(prompt).catch(() => {});
+    showToast?.(t('profile.foundry.editPromptCopied').replace('{name}', comp.label));
+  }
+
+  async function handleRunSingleEditAi(comp, suggestedChange) {
+    if (!orSettings?.hasApiKey) return;
+    setAiRunning(comp.id);
+    try {
+      const upstream = impactParsed?.analysis
+        ?.filter(a => a.impact === 'root' && a.id !== comp.id)
+        ?.map(a => `- ${a.label}: ${a.suggestedChange}`)
+        ?.join('\n') || '';
+      const prompt = buildEditPrompt(
+        comp.type, comp.label,
+        comp.result || '(no current code)',
+        suggestedChange || changeRequest,
+        upstream || null,
+      );
+      let content = await runWithAi(projectId, prompt);
+      content = stripCodeblock(content);
+      let vr = validateComponent(comp.type, content, core.project?.blueprint);
+
+      if (!vr.valid && orSettings?.autoRetry) {
+        const max = orSettings.maxRetries || 3;
+        for (let attempt = 1; attempt <= max && !vr.valid; attempt++) {
+          const fp = buildFixPrompt(prompt, content, vr.errors, comp.type);
+          try { content = await runWithAi(projectId, fp); } catch { break; }
+          content = stripCodeblock(content);
+          vr = validateComponent(comp.type, content, core.project?.blueprint);
+        }
+      }
+
+      if (!vr.valid) {
+        const errored = addHistory(comp, 'validation_failed', { errors: vr.errors, by: 'autopilot' });
+        await saveComponent(projectId, { ...errored, status: 'errors', result: content, validationErrors: vr.errors });
+        await core.loadData();
+        showToast?.(t('profile.foundry.openrouter.stepFailed') + ': ' + comp.label, true);
+        setAiRunning(null);
+        return;
+      }
+
+      const updated = addHistory(comp, 'edited', { by: 'autopilot', change: suggestedChange });
+      await saveComponent(projectId, { ...updated, status: 'done', result: content, validationErrors: [] });
+      const serviceSlug = core.components.find(c => c.type === 'csm' && c.registeredAs)?.registeredAs?.split('/')?.pop() || '';
+      if (comp.type === 'cortex') {
+        const cortexVr = validateComponent('cortex', content, core.project?.blueprint);
+        await registerComponent('cortex', cortexVr.extracted, session, serviceSlug);
+      } else {
+        await registerComponent(comp.type, vr.extracted || content, session, serviceSlug);
+      }
+      await writeProjectLog(projectId, 'component_edited', { meta: { component: comp.label, by: 'autopilot' } });
+      await core.loadData();
+      showToast?.(t('profile.foundry.openrouter.stepDone').replace('{name}', comp.label));
+    } catch (e) {
+      showToast?.(e.message, true);
+    }
+    setAiRunning(null);
+  }
+
+  return {
+    editMode, setEditMode, changeRequest, setChangeRequest,
+    impactResult, setImpactResult, impactParsed, impactErrors,
+    aiRunning,
+    exitEditMode, handleCopyImpactPrompt, handleRunImpactAi,
+    handleParseImpact, handleRunAllEditsAi, handleCopyEditPrompt,
+    handleRunSingleEditAi,
+  };
+}

package/dist/public/views/profile/foundry-dashboard/use-lifecycle.js

@@ -0,0 +1,101 @@
+/**
+ * @file use-lifecycle.js
+ * @description Custom hook for component lifecycle management — activate all,
+ *   deactivate all, and selective removal of registered components.
+ *
+ *   Part of the hook-per-domain architecture for ProjectDashboard. This hook owns
+ *   the lifecycle-specific state (loading indicator, remove panel visibility,
+ *   selection checkboxes, memory deletion toggle, settings panel toggle) and
+ *   exposes handlers for bulk lifecycle operations.
+ *
+ *   Architecture: useDashboardCore → useLifecycle → RemovePanel (sub-component)
+ *   The dashboard shell renders the lifecycle toolbar buttons using this hook's
+ *   returned state and handlers.
+ *
+ * @structure
+ *   - useLifecycle(core, projectId, showToast, session): custom hook
+ *     State: lifecycleLoading, showRemovePanel, removeSelection, removeMemory, showSettingsPanel
+ *     Handlers: handleActivateAll, handleDeactivateAll, handleRemoveConfirmed
+ * @usage
+ *   import { useLifecycle } from './foundry-dashboard/use-lifecycle.js';
+ *   const lifecycle = useLifecycle(core, projectId, showToast, session);
+ * @version-history
+ *   v1.0.0 — 2026-03-22 — Extracted from foundry-tab.js ProjectDashboard
+ */
+import { useState } from 'preact/hooks';
+import { t } from '/js/i18n.js';
+import {
+  activateAll, deactivateAll, removeComponents, writeProjectLog,
+} from '/js/services/foundry.js';
+
+/**
+ * @param {Object} core — useDashboardCore return value (loadData, refreshStatuses)
+ * @param {string} projectId
+ * @param {Function} showToast
+ * @param {Object} session
+ */
+export function useLifecycle(core, projectId, showToast, session) {
+  const [lifecycleLoading, setLifecycleLoading] = useState(null);
+  const [showRemovePanel, setShowRemovePanel] = useState(false);
+  const [removeSelection, setRemoveSelection] = useState({});
+  const [removeMemory, setRemoveMemory] = useState(false);
+  const [showSettingsPanel, setShowSettingsPanel] = useState(false);
+
+  async function handleActivateAll() {
+    setLifecycleLoading('activate');
+    try {
+      const result = await activateAll(projectId);
+      if (result.errors.length > 0) {
+        showToast?.(t('profile.foundry.activatedWithErrors').replace('{count}', result.activated.length).replace('{errors}', result.errors.length), true);
+      } else {
+        showToast?.(t('profile.foundry.activatedCount').replace('{count}', result.activated.length));
+      }
+      await writeProjectLog(projectId, 'all_activated');
+      await core.refreshStatuses();
+    } catch (e) { showToast?.(e.message, true); }
+    setLifecycleLoading(null);
+  }
+
+  async function handleDeactivateAll() {
+    setLifecycleLoading('deactivate');
+    try {
+      const result = await deactivateAll(projectId);
+      if (result.errors.length > 0) {
+        showToast?.(t('profile.foundry.deactivatedWithErrors').replace('{count}', result.deactivated.length).replace('{errors}', result.errors.length), true);
+      } else {
+        showToast?.(t('profile.foundry.deactivatedCount').replace('{count}', result.deactivated.length));
+      }
+      await writeProjectLog(projectId, 'all_deactivated');
+      await core.refreshStatuses();
+    } catch (e) { showToast?.(e.message, true); }
+    setLifecycleLoading(null);
+  }
+
+  async function handleRemoveConfirmed() {
+    const ids = Object.entries(removeSelection).filter(([, v]) => v).map(([k]) => k);
+    if (ids.length === 0) return;
+    setLifecycleLoading('remove');
+    try {
+      const result = await removeComponents(projectId, ids, removeMemory, session);
+      if (result.errors.length > 0) {
+        showToast?.(t('profile.foundry.removedWithErrors').replace('{count}', result.removed.length).replace('{errors}', result.errors.length), true);
+      } else {
+        showToast?.(t('profile.foundry.removedCount').replace('{count}', result.removed.length));
+      }
+      setShowRemovePanel(false);
+      setRemoveSelection({});
+      await core.loadData();
+      await core.refreshStatuses();
+    } catch (e) { showToast?.(e.message, true); }
+    setLifecycleLoading(null);
+  }
+
+  return {
+    lifecycleLoading,
+    showRemovePanel, setShowRemovePanel,
+    removeSelection, setRemoveSelection,
+    removeMemory, setRemoveMemory,
+    showSettingsPanel, setShowSettingsPanel,
+    handleActivateAll, handleDeactivateAll, handleRemoveConfirmed,
+  };
+}

package/dist/public/views/profile/foundry-dashboard/use-packaging.js

@@ -0,0 +1,97 @@
+/**
+ * @file use-packaging.js
+ * @description Custom hook for the Template Packaging system — manages state for
+ *   packaging a foundry project into a reusable template bundle, updating existing
+ *   packages, and detecting changes between versions.
+ *
+ *   Part of the hook-per-domain architecture for ProjectDashboard. This hook owns
+ *   all packaging-related state (dialog visibility, form fields, loading, change
+ *   detection) and exposes handlers for opening the dialog and executing packaging.
+ *   The dashboard shell passes `core` (from useDashboardCore) for access to project
+ *   and component data.
+ *
+ *   Architecture: useDashboardCore → usePackaging → PackageDialog (sub-component)
+ *
+ * @structure
+ *   - usePackaging(core, projectId, showToast): custom hook
+ *     State: showDialog, loading, changes, category, tags, visibility, changelogNote
+ *     Handlers: handleOpen, handlePackage
+ * @usage
+ *   import { usePackaging } from './foundry-dashboard/use-packaging.js';
+ *   const pkg = usePackaging(core, projectId, showToast);
+ * @version-history
+ *   v1.0.0 — 2026-03-22 — Extracted from foundry-tab.js ProjectDashboard
+ */
+import { useState } from 'preact/hooks';
+import { t } from '/js/i18n.js';
+import {
+  packageProject, updatePackageVersion, detectChanges,
+} from '/js/services/foundry-packaging.js';
+import { getPackage } from '/js/services/packages.js';
+
+/**
+ * @param {Object} core — useDashboardCore return value (project, components, loadData)
+ * @param {string} projectId
+ * @param {Function} showToast
+ */
+export function usePackaging(core, projectId, showToast) {
+  const [showDialog, setShowDialog] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [changes, setChanges] = useState(null);
+  const [category, setCategory] = useState('utility');
+  const [tags, setTags] = useState('');
+  const [visibility, setVisibility] = useState('private');
+  const [changelogNote, setChangelogNote] = useState('');
+
+  async function handleOpen() {
+    setShowDialog(true);
+    setChanges(null);
+    setChangelogNote('');
+    // If project is linked to a package, detect changes
+    if (core.project?.packageGroupId) {
+      try {
+        const pkgResp = await getPackage(core.project.packageGroupId);
+        const pkg = pkgResp?.data || pkgResp;
+        const packageable = core.components.filter(c => c.status === 'done' && c.result);
+        const ch = await detectChanges(packageable, pkg?.components);
+        setChanges(ch);
+      } catch { /* first time — no changes to detect */ }
+    }
+  }
+
+  async function handlePackage() {
+    setLoading(true);
+    try {
+      const tagList = tags.split(',').map(s => s.trim()).filter(Boolean);
+      if (core.project?.packageGroupId) {
+        // Update existing package
+        const { result } = await updatePackageVersion(projectId, {
+          category,
+          tags: tagList,
+          changelogNote,
+        });
+        showToast?.(t('profile.foundry.packageUpdateSuccess').replace('{version}', result?.data?.version || ''));
+      } else {
+        // Create new package
+        await packageProject(projectId, {
+          category,
+          tags: tagList,
+          visibility,
+        });
+        showToast?.(t('profile.foundry.packageSuccess'));
+      }
+      setShowDialog(false);
+      await core.loadData();
+    } catch (e) {
+      showToast?.(e.message, true);
+    }
+    setLoading(false);
+  }
+
+  return {
+    showDialog, setShowDialog, loading, changes,
+    category, setCategory, tags, setTags,
+    visibility, setVisibility, changelogNote, setChangelogNote,
+    handleOpen, handlePackage,
+  };
+}