unspaghettit 0.1.7 → 0.2.0

package/src/features/builder-mode/presentation/components/BuilderTagChips.svelte

@@ -0,0 +1,289 @@
+<script lang="ts" module>
+  let nextDatalistSerial = 0;
+</script>
+
+<script lang="ts">
+  import { tick } from 'svelte';
+  import { humanizeTagText, tagKey, tagLabel, type Tag } from '$shared/domain/Tags';
+  import { builderModeStore } from '$features/builder-mode/presentation/stores/builderModeStore.svelte';
+  import type { TagColor } from '$shared/domain/TagPalette';
+  import type { Action } from 'svelte/action';
+
+  /**
+   * Smoothly tween the wrapper's height to its content height whenever that
+   * content changes — the add `+` appearing on hover, or chips wrapping to a
+   * new line. Without this the card would jump in height.
+   *
+   * While a form is open (`editing`) the wrapper goes `overflow: visible` /
+   * `height: auto`: a clipped, fixed-height box throws off the native datalist
+   * dropdown's anchor (it renders far from the input) and would clip the form.
+   * Honors prefers-reduced-motion.
+   */
+  const animateHeight: Action<HTMLElement, boolean> = (node, editing = false) => {
+    const inner = node.firstElementChild as HTMLElement | null;
+    if (!inner) return;
+    const reduce =
+      typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+    const hasObserver = typeof ResizeObserver !== 'undefined';
+    let last = inner.offsetHeight;
+
+    const toOpen = () => {
+      // Unclip so inputs and the native type dropdown lay out / anchor correctly.
+      node.style.transition = '';
+      node.style.overflow = 'visible';
+      node.style.height = 'auto';
+    };
+    const toClipped = () => {
+      node.style.overflow = 'hidden';
+      if (!hasObserver) {
+        node.style.height = 'auto';
+        return;
+      }
+      const start = node.offsetHeight;
+      last = inner.offsetHeight;
+      if (reduce) {
+        node.style.height = `${last}px`;
+        return;
+      }
+      node.style.transition = 'height 240ms cubic-bezier(0.22, 1, 0.36, 1)';
+      node.style.height = `${start}px`;
+      void node.offsetHeight; // commit the start height before transitioning
+      node.style.height = `${last}px`;
+    };
+
+    let isEditing = editing;
+    if (isEditing) toOpen();
+    else {
+      node.style.overflow = 'hidden';
+      node.style.height = `${last}px`;
+      if (!reduce) node.style.transition = 'height 240ms cubic-bezier(0.22, 1, 0.36, 1)';
+    }
+
+    let observer: ResizeObserver | null = null;
+    if (hasObserver) {
+      observer = new ResizeObserver(() => {
+        if (isEditing) return; // height:auto handles growth while a form is open
+        const next = inner.offsetHeight;
+        if (next === last) return;
+        if (reduce) {
+          node.style.height = `${next}px`;
+          last = next;
+          return;
+        }
+        node.style.height = `${last}px`;
+        void node.offsetHeight;
+        node.style.height = `${next}px`;
+        last = next;
+      });
+      observer.observe(inner);
+    } else if (!isEditing) {
+      node.style.height = 'auto';
+    }
+
+    return {
+      update(next: boolean) {
+        if (next === isEditing) return;
+        isEditing = next;
+        if (isEditing) toOpen();
+        else toClipped();
+      },
+      destroy: () => observer?.disconnect()
+    };
+  };
+
+  let {
+    tags,
+    onToggle,
+    isActive,
+    onAdd,
+    onRemove,
+    onRename,
+    typeOptions = [],
+    class: className = ''
+  }: {
+    readonly tags: readonly Tag[];
+    readonly onToggle?: (tag: Tag) => void;
+    readonly isActive?: (tag: Tag) => boolean;
+    readonly onAdd?: (type: string, value: string) => void | Promise<void>;
+    readonly onRemove?: (tag: Tag) => void | Promise<void>;
+    readonly onRename?: (from: Tag, to: Tag) => void | Promise<void>;
+    readonly typeOptions?: readonly string[];
+    readonly class?: string;
+  } = $props();
+
+  const datalistId = `buildertags-types-${++nextDatalistSerial}`;
+
+  // Mix the palette color toward a deep slate for the dark builder plate (the
+  // shared light-theme styles mix toward white). `active` brightens the chip.
+  const SLATE = '#64748b';
+  const chipStyle = (color: TagColor | null, active: boolean): string => {
+    const base = color ?? SLATE;
+    const fill = active ? 42 : 20;
+    const ring = active ? 72 : 42;
+    return [
+      `background-color: color-mix(in srgb, ${base} ${fill}%, #0b1220)`,
+      `color: color-mix(in srgb, ${base} 72%, white)`,
+      `box-shadow: inset 0 0 0 1px color-mix(in srgb, ${base} ${ring}%, transparent)`
+    ].join('; ');
+  };
+
+  // ── add ──
+  let adding = $state(false);
+  let addType = $state('');
+  let addValue = $state('');
+  let addInput = $state<HTMLInputElement | null>(null);
+
+  async function startAdd() {
+    adding = true;
+    await tick();
+    addInput?.focus();
+  }
+  function cancelAdd() {
+    adding = false;
+    addType = '';
+    addValue = '';
+  }
+  async function submitAdd(event: SubmitEvent) {
+    event.preventDefault();
+    const value = addValue.trim();
+    if (!value) return;
+    const type = addType.trim() || 'tag';
+    cancelAdd(); // close the form immediately; the chip appears once persisted
+    await onAdd?.(type, value);
+  }
+
+  // ── rename (propagates everywhere the tag is used) ──
+  let editingKey = $state<string | null>(null);
+  let editType = $state('');
+  let editValue = $state('');
+  let editInput = $state<HTMLInputElement | null>(null);
+
+  async function startEdit(tag: Tag) {
+    editingKey = tagKey(tag);
+    editType = humanizeTagText(tag.type);
+    editValue = humanizeTagText(tag.value);
+    await tick();
+    editInput?.select();
+  }
+  function cancelEdit() {
+    editingKey = null;
+  }
+  async function submitEdit(event: SubmitEvent, from: Tag) {
+    event.preventDefault();
+    const value = editValue.trim();
+    const type = editType.trim();
+    if (!value || !type) return;
+    cancelEdit();
+    await onRename?.(from, { type, value });
+  }
+
+  function onFormKey(event: KeyboardEvent, cancel: () => void) {
+    if (event.key === 'Escape') cancel();
+  }
+</script>
+
+{#if tags.length > 0 || onAdd}
+  <div class={className} use:animateHeight={adding || editingKey !== null}>
+    <div class="flex flex-wrap items-center gap-1.5">
+    {#each tags as tag (tagKey(tag))}
+      {#if editingKey === tagKey(tag)}
+        <form class="inline-flex items-center gap-1" onsubmit={(e) => submitEdit(e, tag)}>
+          <input
+            bind:this={editInput}
+            bind:value={editType}
+            list={typeOptions.length > 0 ? datalistId : undefined}
+            placeholder="Type"
+            onkeydown={(e) => onFormKey(e, cancelEdit)}
+            class="h-6 w-16 rounded border border-slate-700 bg-slate-900/70 px-1.5 text-[11px] text-slate-200 outline-none focus:border-brand-500"
+          />
+          <input
+            bind:value={editValue}
+            placeholder="Value"
+            onkeydown={(e) => onFormKey(e, cancelEdit)}
+            class="h-6 w-20 rounded border border-slate-700 bg-slate-900/70 px-1.5 text-[11px] text-slate-200 outline-none focus:border-brand-500"
+          />
+          <button type="submit" class="text-[11px] font-semibold text-brand-300 hover:text-brand-200" title="Rename everywhere">✓</button>
+          <button type="button" class="text-[11px] text-slate-500 hover:text-slate-300" onclick={cancelEdit} title="Cancel">✕</button>
+        </form>
+      {:else}
+        {@const color = builderModeStore.colorForTag(tag)}
+        {@const active = isActive?.(tag) ?? false}
+        <span
+          class="group/chip inline-flex max-w-full items-center gap-1 rounded-full py-0.5 pl-2 pr-1.5 text-[10px] font-medium transition"
+          style={chipStyle(color, active)}
+        >
+          <span class="size-1.5 shrink-0 rounded-full" style="background-color: {color ?? SLATE}"></span>
+          {#if onToggle}
+            <button
+              type="button"
+              class="truncate"
+              onclick={() => onToggle(tag)}
+              aria-pressed={active}
+              title={`${tagLabel(tag)} — click to filter`}
+            >{humanizeTagText(tag.value)}</button>
+          {:else}
+            <span class="truncate" title={tagLabel(tag)}>{humanizeTagText(tag.value)}</span>
+          {/if}
+          {#if onRename}
+            <button
+              type="button"
+              class="shrink-0 opacity-0 transition group-hover/chip:opacity-70 hover:opacity-100!"
+              onclick={() => startEdit(tag)}
+              aria-label={`Rename ${tagLabel(tag)}`}
+              title="Rename (applies everywhere)"
+            >✎</button>
+          {/if}
+          {#if onRemove}
+            <button
+              type="button"
+              class="shrink-0 opacity-0 transition group-hover/chip:opacity-70 hover:opacity-100!"
+              onclick={() => onRemove(tag)}
+              aria-label={`Remove ${tagLabel(tag)}`}
+              title="Remove from this item"
+            >✕</button>
+          {/if}
+        </span>
+      {/if}
+    {/each}
+
+    {#if onAdd}
+      {#if adding}
+        <form class="inline-flex items-center gap-1" onsubmit={submitAdd}>
+          <input
+            bind:this={addInput}
+            bind:value={addType}
+            list={typeOptions.length > 0 ? datalistId : undefined}
+            placeholder="Type"
+            onkeydown={(e) => onFormKey(e, cancelAdd)}
+            class="h-6 w-16 rounded border border-slate-700 bg-slate-900/70 px-1.5 text-[11px] text-slate-200 outline-none focus:border-brand-500"
+          />
+          <input
+            bind:value={addValue}
+            placeholder="Value"
+            onkeydown={(e) => onFormKey(e, cancelAdd)}
+            class="h-6 w-20 rounded border border-slate-700 bg-slate-900/70 px-1.5 text-[11px] text-slate-200 outline-none focus:border-brand-500"
+          />
+          <button type="submit" class="text-[11px] font-semibold text-brand-300 hover:text-brand-200" title="Add tag">✓</button>
+          <button type="button" class="text-[11px] text-slate-500 hover:text-slate-300" onclick={cancelAdd} title="Cancel">✕</button>
+        </form>
+      {:else}
+        <button
+          type="button"
+          class="size-5 items-center justify-center rounded-full border border-dashed border-slate-600 text-[11px] leading-none text-slate-400 transition hover:border-brand-500 hover:text-brand-300 hidden group-hover:inline-flex group-focus-within:inline-flex"
+          onclick={startAdd}
+          aria-label="Add tag"
+          title="Add tag"
+        >+</button>
+      {/if}
+    {/if}
+
+    {#if typeOptions.length > 0}
+      <datalist id={datalistId}>
+        {#each typeOptions as option (option)}
+          <option value={option}></option>
+        {/each}
+      </datalist>
+    {/if}
+    </div>
+  </div>
+{/if}

package/src/features/builder-mode/presentation/components/ClampedDescription.svelte

@@ -0,0 +1,174 @@
+<script lang="ts">
+  let {
+    text,
+    class: className = ''
+  }: {
+    readonly text: string;
+    readonly class?: string;
+  } = $props();
+
+  let expanded = $state(false);
+  let overflowing = $state(false);
+  let animating = $state(false);
+  let el = $state<HTMLParagraphElement | null>(null);
+
+  // Open feels expansive (easeOutExpo — fast then a long, soft settle); close
+  // is a touch quicker and symmetric (easeInOutCubic). The values are tuned to
+  // read as one physical motion rather than a linear height tween.
+  const OPEN = '560ms cubic-bezier(0.16, 1, 0.3, 1)';
+  const CLOSE = '440ms cubic-bezier(0.65, 0, 0.35, 1)';
+  const SOFT_EDGE = 'linear-gradient(to bottom, #000 calc(100% - 1.3em), transparent)';
+
+  const prefersReducedMotion = (): boolean =>
+    typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  const clampedHeight = (node: HTMLElement): number => {
+    const lineHeight = parseFloat(getComputedStyle(node).lineHeight) || 20;
+    return lineHeight * 2;
+  };
+
+  // Cancels the in-flight animation's transitionend listener so a mid-flight
+  // re-toggle doesn't get its cleanup stomped by the previous run.
+  let cancelPending: (() => void) | null = null;
+
+  // Reveal only carries a toggle when the clamped text actually overflows.
+  // While clamped, scrollHeight (full content) exceeds clientHeight (2 lines).
+  // Re-measured on text changes and width changes (the columns resize).
+  $effect(() => {
+    const node = el;
+    if (!node) return;
+    void text;
+    const measure = () => {
+      if (expanded || animating) return; // clientHeight === scrollHeight once open
+      overflowing = node.scrollHeight > node.clientHeight + 1;
+    };
+    measure();
+    if (typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(measure);
+    observer.observe(node);
+    return () => observer.disconnect();
+  });
+
+  function toggle(): void {
+    const node = el;
+    if (!node) return;
+    if (expanded) collapse(node);
+    else expand(node);
+  }
+
+  /**
+   * Run `max-height` from `startPx` to `endPx` with `timing`. The caller must
+   * already have the clamp in the right state; we pin the start height (no
+   * transition), commit it, then transition to the end. Starting from a caller-
+   * supplied height — captured BEFORE any clamp change — is what makes both
+   * directions animate, and makes mid-flight re-toggles reverse seamlessly.
+   */
+  function animateHeight(
+    node: HTMLElement,
+    startPx: number,
+    endPx: number,
+    timing: string,
+    onDone: () => void
+  ): void {
+    cancelPending?.();
+    animating = true;
+    node.style.overflow = 'hidden';
+    node.style.webkitMaskImage = SOFT_EDGE;
+    node.style.maskImage = SOFT_EDGE;
+    node.style.transition = 'none';
+    node.style.maxHeight = `${startPx}px`;
+    void node.offsetHeight; // commit the start frame before transitioning
+    node.style.transition = `max-height ${timing}`;
+    node.style.maxHeight = `${endPx}px`;
+
+    const done = (event: TransitionEvent) => {
+      if (event.propertyName !== 'max-height') return;
+      node.removeEventListener('transitionend', done);
+      cancelPending = null;
+      animating = false;
+      onDone();
+    };
+    node.addEventListener('transitionend', done);
+    cancelPending = () => node.removeEventListener('transitionend', done);
+  }
+
+  function expand(node: HTMLElement): void {
+    // Capture the clamped (2-line) height BEFORE unclamping — otherwise the
+    // element is already at full height and start === end (the instant-open bug).
+    const startPx = node.clientHeight;
+    expanded = true;
+    // Drop the line-clamp so content can exceed two lines; the pinned start
+    // height keeps it visually at two lines until the transition takes over.
+    node.classList.remove('clamp-2');
+    if (prefersReducedMotion()) return;
+    void node.offsetHeight; // let scrollHeight reflect the now-unclamped content
+    animateHeight(node, startPx, node.scrollHeight, OPEN, () => {
+      // Fully open: release every constraint so later reflow can't clip it.
+      node.style.transition = '';
+      node.style.maxHeight = 'none';
+      node.style.overflow = '';
+      node.style.webkitMaskImage = '';
+      node.style.maskImage = '';
+    });
+  }
+
+  function collapse(node: HTMLElement): void {
+    const startPx = node.clientHeight; // current (expanded / mid-animation) height
+    expanded = false;
+    if (prefersReducedMotion()) {
+      node.classList.add('clamp-2');
+      node.style.maxHeight = '';
+      return;
+    }
+    animateHeight(node, startPx, clampedHeight(node), CLOSE, () => {
+      // Restore the resting clamp (with its ellipsis) and drop inline overrides.
+      node.classList.add('clamp-2');
+      node.style.transition = '';
+      node.style.maxHeight = '';
+      node.style.overflow = '';
+      node.style.webkitMaskImage = '';
+      node.style.maskImage = '';
+    });
+  }
+</script>
+
+<div class={className}>
+  <p bind:this={el} class="clamp-2 text-sm leading-5 text-slate-400">{text}</p>
+  {#if overflowing || expanded || animating}
+    <button
+      type="button"
+      class="relative z-20 mt-1 inline-flex items-center gap-1 text-xs font-semibold text-brand-400 transition hover:text-brand-300"
+      onclick={toggle}
+      aria-expanded={expanded}
+    >
+      <span>{expanded ? 'View less' : 'View more'}</span>
+      <svg
+        viewBox="0 0 16 16"
+        class="h-3 w-3 transition-transform duration-500 ease-out {expanded ? 'rotate-180' : ''}"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        aria-hidden="true"
+      >
+        <path d="M4 6l4 4 4-4" stroke-linecap="round" stroke-linejoin="round" />
+      </svg>
+    </button>
+  {/if}
+</div>
+
+<style>
+  /*
+   * Resting two-line clamp with ellipsis. Toggled imperatively (not via a
+   * reactive class) because the open/close animation needs the clamp gone for
+   * the exact frame it swaps to a max-height transition — line-clamp itself
+   * can't be animated, and a deferred reactive update would race the freeze
+   * frame. Kept in the markup's initial class so the scoped rule isn't pruned.
+   */
+  .clamp-2 {
+    display: -webkit-box;
+    -webkit-box-orient: vertical;
+    -webkit-line-clamp: 2;
+    line-clamp: 2;
+    overflow: hidden;
+  }
+</style>

package/src/features/builder-mode/presentation/components/GameScore.svelte

@@ -0,0 +1,194 @@
+<script lang="ts">
+  let {
+    label,
+    value
+  }: {
+    readonly label: string;
+    readonly value: number | null;
+  } = $props();
+
+  const normalized = $derived(value === null ? 0 : Math.max(0, Math.min(100, value)));
+  const displayValue = $derived(`${normalized}%`);
+  const dash = $derived(normalized * 0.87965);
+  const toneClass = $derived(
+    normalized >= 80
+        ? 'is-high'
+        : normalized >= 45
+          ? 'is-mid'
+          : 'is-low'
+  );
+</script>
+
+<div class="score-meter {toneClass}">
+  <div class="score-meter__dial">
+    <svg viewBox="0 0 36 36" class="score-meter__svg" aria-hidden="true">
+      <circle cx="18" cy="18" r="16" fill="none" class="score-meter__outer" stroke-width="1.2" />
+      <circle cx="18" cy="18" r="14" fill="none" class="score-meter__track" stroke-width="2.4" />
+      <circle
+        cx="18"
+        cy="18"
+        r="14"
+        fill="none"
+        class="score-meter__arc-glow"
+        stroke-width="8"
+        stroke-linecap={normalized > 0 ? 'round' : 'butt'}
+        stroke-dasharray={`${dash} 87.965`}
+      />
+      <circle
+        cx="18"
+        cy="18"
+        r="14"
+        fill="none"
+        class="score-meter__arc"
+        stroke-width="2.4"
+        stroke-linecap={normalized > 0 ? 'round' : 'butt'}
+        stroke-dasharray={`${dash} 87.965`}
+      />
+    </svg>
+    <span class="score-meter__readout">
+      {displayValue}
+    </span>
+  </div>
+  <span class="score-meter__label">{label}</span>
+</div>
+
+<style>
+  .score-meter {
+    --accent: #94a3b8;
+    --accent-soft: rgba(148, 163, 184, 0.24);
+    display: flex;
+    min-width: 76px;
+    flex-direction: column;
+    align-items: center;
+    gap: 8px;
+  }
+
+  .score-meter.is-high {
+    --accent: #34d399;
+    --accent-soft: rgba(52, 211, 153, 0.34);
+  }
+
+  .score-meter.is-mid {
+    --accent: #fb923c;
+    --accent-soft: rgba(251, 146, 60, 0.28);
+  }
+
+  .score-meter.is-low {
+    --accent: #f43f5e;
+    --accent-soft: rgba(244, 63, 94, 0.24);
+  }
+
+  .score-meter.is-empty {
+    --accent: #94a3b8;
+    --accent-soft: rgba(148, 163, 184, 0.2);
+  }
+
+  .score-meter__dial {
+    position: relative;
+    width: 68px;
+    height: 68px;
+    border: 1px solid rgba(15, 23, 42, 0.92);
+    border-radius: 999px;
+    background:
+      radial-gradient(circle at 34% 26%, rgba(255, 255, 255, 0.18), transparent 22%),
+      radial-gradient(circle at 50% 66%, rgba(255, 255, 255, 0.08), transparent 43%),
+      linear-gradient(180deg, rgba(71, 85, 105, 0.96), rgba(15, 23, 42, 0.98));
+    box-shadow:
+      0 14px 22px rgba(0, 0, 0, 0.34),
+      0 1px 0 rgba(255, 255, 255, 0.18) inset,
+      0 -3px 0 rgba(2, 6, 23, 0.9) inset,
+      0 0 0 6px rgba(15, 23, 42, 0.66) inset;
+  }
+
+  .score-meter__dial::before {
+    content: "";
+    position: absolute;
+    inset: 5px;
+    border-radius: inherit;
+    background:
+      linear-gradient(180deg, rgba(255, 255, 255, 0.12), transparent 42%),
+      linear-gradient(180deg, rgba(2, 6, 23, 0.2), rgba(2, 6, 23, 0.72));
+    box-shadow:
+      0 1px 1px rgba(255, 255, 255, 0.08) inset,
+      0 10px 18px rgba(0, 0, 0, 0.4) inset;
+  }
+
+  .score-meter__dial::after {
+    content: "";
+    position: absolute;
+    inset: 6px;
+    border-radius: inherit;
+    background: radial-gradient(circle, var(--accent-soft), transparent 58%);
+    opacity: 0.28;
+    filter: blur(7px);
+  }
+
+  .score-meter__svg {
+    position: absolute;
+    inset: 6px;
+    z-index: 1;
+    overflow: visible;
+    /* The lit well sits high (top-left light + thick bottom rim), so geometric-center
+       content reads as low — lift the arc + readout ~1px into the optical center. */
+    transform: translateY(-1px) rotate(-90deg);
+  }
+
+  .score-meter__outer {
+    stroke: rgba(226, 232, 240, 0.16);
+  }
+
+  .score-meter__track {
+    stroke: rgba(30, 41, 59, 0.72);
+    filter:
+      drop-shadow(0 1px 0 rgba(255, 255, 255, 0.08))
+      drop-shadow(0 -1px 0 rgba(0, 0, 0, 0.28))
+      drop-shadow(0 0 5px rgba(148, 163, 184, 0.12));
+  }
+
+  .score-meter.is-empty .score-meter__track {
+    stroke: rgba(71, 85, 105, 0.72);
+    filter:
+      drop-shadow(0 1px 0 rgba(255, 255, 255, 0.08))
+      drop-shadow(0 -1px 0 rgba(0, 0, 0, 0.2))
+      drop-shadow(0 0 7px rgba(148, 163, 184, 0.16));
+  }
+
+  .score-meter__arc-glow {
+    stroke: var(--accent);
+    opacity: 0.16;
+    filter: blur(2.8px);
+  }
+
+  .score-meter__arc {
+    stroke: var(--accent);
+    opacity: 0.68;
+    filter:
+      drop-shadow(0 1px 0 rgba(255, 255, 255, 0.07))
+      drop-shadow(0 0 7px var(--accent-soft));
+  }
+
+  .score-meter__readout {
+    position: absolute;
+    inset: 0;
+    z-index: 2;
+    display: grid;
+    place-items: center;
+    /* match the arc's optical lift and kill inherited line-height drift */
+    transform: translateY(-1px);
+    line-height: 1;
+    color: white;
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+    font-size: 13px;
+    font-weight: 800;
+    font-variant-numeric: tabular-nums;
+    text-shadow: 0 1px 2px rgba(0, 0, 0, 0.75);
+  }
+
+  .score-meter__label {
+    color: rgb(148, 163, 184);
+    font-size: 11px;
+    font-weight: 800;
+    letter-spacing: 0;
+    text-transform: uppercase;
+  }
+</style>

package/src/features/builder-mode/presentation/ports/BuilderHostPorts.ts

@@ -0,0 +1,39 @@
+import type { Container } from '$shared/infrastructure/container';
+import type { SyncEvent } from '$lib/client/sync/syncEvents';
+import type { Tag } from '$shared/domain/Tags';
+import type { TagColor } from '$shared/domain/TagPalette';
+
+/**
+ * Driven ports for the builder view (hexagonal architecture). Each interface is
+ * one responsibility the view needs from its host; `BuilderHost` composes them.
+ *
+ * These are pure abstractions — type-only imports, no concrete singletons — so
+ * the view's store depends on *these*, never on the app's infrastructure
+ * directly (dependency inversion). Concrete implementations ("adapters") live
+ * under `infrastructure/adapters`, and the composition root wires them in.
+ */
+
+/** Hands the view the resolved DI container (repositories + use-cases). */
+export interface BuilderDataGateway {
+  getContainer(): Promise<Container>;
+}
+
+/** Tag colors and cross-entity tag rename. */
+export interface TagPaletteGateway {
+  refresh(): Promise<void>;
+  registerTypes(types: readonly string[]): void;
+  colorForTag(tag: Tag): TagColor | null;
+  renameTag(from: Tag, to: Tag): Promise<void>;
+}
+
+/** Live "projects/features changed" notifications. */
+export interface SyncGateway {
+  subscribe(handler: (event: SyncEvent) => void): () => void;
+}
+
+/** The composed set of host services the builder view depends on. */
+export interface BuilderHost {
+  readonly data: BuilderDataGateway;
+  readonly tags: TagPaletteGateway;
+  readonly sync: SyncGateway;
+}