chore(app-mode): trim small net-new files (-82 lines)

Comment-trim pass on the seven smaller net-new files the previous
pass skipped. Same pattern: drop paraphrase comments, tighten doc
preambles, keep load-bearing rationale.

src/components/appMode/layout/panels/PanelDragPreview.vue

@@ -1,40 +1,28 @@
 <script setup lang="ts">
 /**
- * PanelDragPreview — translucent brand-blue rectangle rendered at the
- * snap-target preset's bounds while a panel is being dragged. Appears
- * above the live panel to signal where the panel will land on release.
- *
- * Passing `panelHeight` makes the preview match the live panel's
- * content-fit height instead of stretching to the preset's full
- * `max-height`; each preset's `max-height` still caps the preview on
- * small viewports.
+ * Translucent outline rendered at the snap-target preset's bounds
+ * during a panel drag. Sits above the live panel to signal where it
+ * will land on release.
  */
 import { computed } from 'vue'
 
 import { PANEL_PRESET_CLASSES } from './panelPresetClasses'
-import { isDockPreset } from './panelTypes';
-import type { PanelPreset } from './panelTypes';
+import { isDockPreset } from './panelTypes'
+import type { PanelPreset } from './panelTypes'
 
 const props = defineProps<{
   preset: PanelPreset
   panelHeight?: number
   panelWidth?: number
 }>()
 
-// Preset classes are shared with FloatingPanel via
-// `PANEL_PRESET_CLASSES` so the drop preview always lands where the
-// live panel will.
 const presetClass = computed(() => PANEL_PRESET_CLASSES[props.preset])
 const isDocked = computed(() => isDockPreset(props.preset))
-// Match the live panel's rendered dimensions so the preview lands the
-// same size the panel will — important when the user has drag-resized
-// the dock wider than the default. Dock presets span the full slot via
-// `top` + `bottom` CSS anchors, so leave the height out for them; an
-// explicit `height` would override the bottom anchor and shrink the
-// preview to the live panel's content-fit height (which is what was
-// happening when dragging from a float corner toward a dock — the
-// preview rendered as a short rectangle at the top instead of a
-// full-height column).
+// Match the live panel's rendered dimensions so the preview lands at
+// the size the panel will. Dock presets span the full slot via
+// top+bottom anchors, so leave height out for them — an explicit
+// height would override the bottom anchor and shrink the preview to
+// the live panel's content-fit height.
 const sizeStyle = computed(() => {
   const style: Record<string, string> = {}
   if (!isDocked.value && props.panelHeight != null)
@@ -47,9 +35,9 @@ const sizeStyle = computed(() => {
 <template>
   <div
     :class="[
-      // Base chrome: absolute, accent-temp outline + 30% tint fill,
-      // content non-interactive, animated through the shared layout
-      // duration/easing so the preview tweens between presets.
+      // Accent-temp outline + 30% tint fill, animated through the
+      // shared layout duration/easing so the preview tweens between
+      // presets when the snap target changes.
       'pointer-events-none absolute z-20',
       'w-(--panel-dock-width,440px)',
       'rounded-[10px] border-2 border-(--color-app-mode-accent-temp)',

src/components/appMode/layout/panels/panelTypes.ts

@@ -1,6 +1,6 @@
 /**
  * Panel + block config types for the semi-customizable floating panel.
- * State is in-memory only for now; persistence is a follow-up.
+ * In-memory only for now; persistence is a follow-up.
  */
 
 export type PanelPreset =
@@ -11,12 +11,8 @@ export type PanelPreset =
   | 'float-tl'
   | 'float-bl'
 
-/**
- * Preset-shape predicates. Centralized so consumers don't reinvent
- * `preset === 'right-dock' || preset === 'left-dock'` (or the more
- * fragile `startsWith` / `endsWith` parses) at every call site — the
- * `PanelPreset` union stays the single source of truth.
- */
+// Preset-shape predicates — keep consumers off `startsWith` /
+// `endsWith` parses; the union stays the single source of truth.
 export const isDockPreset = (p: PanelPreset): boolean =>
   p === 'right-dock' || p === 'left-dock'
 

src/components/appMode/layout/panels/usePanelResize.ts

@@ -1,12 +1,7 @@
 /**
- * usePanelResize — pointer-driven width resize for FloatingPanel when
- * docked. Snaps to whole cell + gutter increments so the panel always
- * lands on the layout grid. Activates on pointerdown over an inner-
- * edge hit area (caller wires `startResize` to that element).
- *
- * Clamped to [MIN_CELLS, MAX_CELLS]; the min matches the default dock
- * width so the panel can never be narrower than its non-resizable
- * baseline.
+ * Pointer-driven width resize for FloatingPanel's dock presets.
+ * Snaps to whole cell+gutter steps so the panel lands on the grid.
+ * Clamped to [MIN_CELLS, MAX_CELLS] (min = default dock width).
  */
 import { useEventListener, useWindowFocus } from '@vueuse/core'
 import { ref, watch } from 'vue'
@@ -22,8 +17,8 @@ interface UsePanelResizeOptions {
 const MIN_CELLS = 8
 const MAX_CELLS = 19
 
-/** Read the grid step (cell + gutter, in px) from design-system tokens
- *  at runtime so theme overrides take effect without a constant sync. */
+/** Read cell + gutter from design-system tokens at runtime so theme
+ *  overrides take effect without a constant sync. */
 function readGridStep(): number {
   if (typeof document === 'undefined') return 56
   const cs = getComputedStyle(document.documentElement)
@@ -60,9 +55,8 @@ export function usePanelResize(opts: UsePanelResizeOptions) {
 
   useEventListener(window, 'pointermove', (e: PointerEvent) => {
     if (!isOurPointer(e)) return
-    // For right-dock the panel's inner edge is on the LEFT — dragging
-    // the pointer left should widen the panel (negative clientX delta
-    // → more cells). For left-dock it's the opposite.
+    // Right-dock's inner edge is on the LEFT, so a leftward pointer
+    // delta widens the panel; left-dock is opposite.
     const delta = e.clientX - startX
     const widenPx = opts.side.value === 'right' ? -delta : delta
     const deltaCells = Math.round(widenPx / gridStep)
@@ -83,9 +77,8 @@ export function usePanelResize(opts: UsePanelResizeOptions) {
     reset()
   })
 
-  // Abandon on window blur so a resize doesn't survive alt-tab / OS
-  // modals waiting for a pointerup that never arrives. Matches
-  // usePanelDrag's behavior for the same reason.
+  // Abandon on window blur so a resize can't get stuck waiting for a
+  // pointerup that never arrives (alt-tab, OS modal, etc.).
   const focused = useWindowFocus()
   watch(focused, (nowFocused) => {
     if (!nowFocused && activePointerId !== null) reset()

src/components/builder/BuilderBackdrop.vue

@@ -1,22 +1,10 @@
 <script setup lang="ts">
 /**
- * BuilderBackdrop — dot-grid canvas + LinearPreview backdrop for the
- * builder's Preview step. Mirrors LayoutView's backdrop exactly so the
- * Preview visually reads as App Mode: dot-grid canvas color behind,
- * LinearPreview in front (which internally shows LinearArrange's dashed
- * output-area marker in arrange mode, or the actual output when run).
- *
- * Mounts only in the arrange step: during Inputs / Outputs the user
- * clicks on graph-canvas nodes, so the graph has to stay visible.
- * In arrange (Preview), graph interaction isn't meaningful — this
- * backdrop replaces the graph canvas so authors see a clean
- * App-Mode-style preview of where their outputs and inputs will sit.
- *
- * Pan/zoom — same workspace-transform pattern as LayoutView, sharing
- * `appModeStore.viewport*` so the user's zoom level survives a
- * builder ↔ app-mode round trip. AppChrome's nav cluster routes its
- * builder handlers to App Mode actions while `isArrangeMode` is true,
- * so the cluster operates this backdrop instead of the hidden graph.
+ * Dot-grid canvas + LinearPreview backdrop for the builder's Preview
+ * step. Mirrors LayoutView's backdrop so Preview reads as App Mode.
+ * Mounts only in arrange (graph interaction isn't meaningful there).
+ * Shares `appModeStore.viewport*` with App Mode so zoom level
+ * survives a round trip.
  */
 import { useEventListener } from '@vueuse/core'
 import { storeToRefs } from 'pinia'
@@ -80,11 +68,10 @@ const workspaceTransform = computed(
     `scale(${viewportScale.value})`
 )
 
-// Same LOD-doubling math LayoutView uses — keep the dot grid pitch
-// from collapsing into noise when zoomed out, while letting it
-// scale up when zoomed in.
 const DOT_SIZE_PX = 24
 const MIN_GRID_SPACING_PX = 16
+// LOD-doubling keeps the grid pitch from collapsing into noise
+// when zoomed out (same trick LayoutView used pre-LOD-redesign).
 const gridSpacing = computed(() => {
   let s = DOT_SIZE_PX * viewportScale.value
   if (!(s > 0)) return DOT_SIZE_PX
@@ -94,16 +81,9 @@ const gridSpacing = computed(() => {
 </script>
 
 <template>
-  <!-- Same dot-grid + canvas-color treatment LayoutView uses so Preview
-       reads as App Mode. Sits between the graph canvas (below) and the
-       chrome / panel layers (above): z-50 covers the canvas but sits
-       under AppChrome (z-1/90), FloatingPanel (z-100), BuilderToolbar
-       and BuilderFooterToolbar. Sidebar-width offset keeps the Comfy
-       sidebar icon strip visible during arrange. The dot grid lives on
-       this outer element with dynamic background-size + position
-       driven by the viewport vars — same trick as LayoutView so the
-       grid pattern visually matches the transformed content without
-       this element itself needing to scale. -->
+  <!-- z-50 covers the graph canvas but sits under AppChrome /
+       FloatingPanel / BuilderToolbar. Sidebar-width offset keeps
+       the Comfy sidebar visible during arrange. -->
   <div
     v-if="isArrangeMode"
     :class="[
@@ -118,10 +98,8 @@ const gridSpacing = computed(() => {
       backgroundPosition: `${viewportOffsetX}px ${viewportOffsetY}px`
     }"
   >
-    <!-- Workspace layer: holds the transform + wheel/pointer handlers
-         so the cluster (when in arrange mode) and direct gestures
-         drive the same `appModeStore.viewport*` state LayoutView
-         reads. The dot grid above pans + scales in lockstep. -->
+    <!-- Workspace layer: holds transform + wheel/pointer handlers,
+         driving the same viewport state LayoutView reads. -->
     <div
       ref="bgRef"
       class="builder-backdrop__workspace absolute inset-0 flex flex-col"
@@ -135,20 +113,15 @@ const gridSpacing = computed(() => {
   </div>
 </template>
 
-<!-- Exception (docs/guidance/vue-components.md §Styling): :deep(*) is
-     the only practical way to re-enable pointer events on the slotted
-     <LinearPreview> subtree. The root is pointer-events-none so graph/
-     chrome clicks fall through empty builder-backdrop space; slotted
-     content needs pointer-events-auto so LinearArrange's clickable
-     zones still register. We don't own LinearPreview's render tree, so
-     we can't push the rule into that component's template. -->
+<!-- Documented exception (docs/guidance/vue-components.md §Styling):
+     :deep(*) re-enables pointer events on the slotted LinearPreview
+     subtree because we don't own its render tree. Root is
+     pointer-events-none so empty backdrop space lets clicks fall
+     through to graph/chrome. -->
 <style scoped>
 .builder-backdrop :deep(*) {
   pointer-events: auto;
 }
-/* The workspace layer is itself a child of the pointer-events-none
-   root, so re-enable pointer events here too — wheel + pointerdown
-   need to reach our handlers. */
 .builder-backdrop__workspace {
   pointer-events: auto;
   transform-origin: center;

src/components/builder/BuilderPanel.vue

@@ -1,22 +1,10 @@
 <script setup lang="ts">
 /**
- * BuilderPanel — floating right-dock panel for the App Builder flow.
- *
- * Renders the same PanelBlockList App Mode shows, via the same shared
- * state in appModeStore, so the builder is WYSIWYG by construction:
- * what you see while picking / arranging inputs is exactly what App
- * Mode renders at runtime. InputCell's `builder` variant adds the ⋯
- * Rename/Remove menu and inerts the widget body so preview inputs
- * aren't typed into while arranging.
- *
- * Panel preset, collapse state, and `panelRows` all live on
- * appModeStore; moving or rearranging in either view updates both.
- * Graph-canvas click-to-select overlays (widget highlights + output
- * rings) live in AppBuilder.vue — this component owns the panel
- * surface only.
- *
- * Run + Number-of-runs live in BuilderChrome (upper-right cluster) to
- * match App Mode's runtime chrome, not in this panel.
+ * Floating right-dock panel for the App Builder flow. Renders the
+ * same PanelBlockList as App Mode, reading from the same appModeStore
+ * — the builder is WYSIWYG with App Mode by construction. InputCell's
+ * `builder` variant adds rename/remove and inerts the widget body so
+ * inputs aren't typed into during arrangement.
  */
 import { storeToRefs } from 'pinia'
 import { computed } from 'vue'
@@ -37,8 +25,7 @@ const { panelPreset, panelCollapsed, panelRows } = storeToRefs(appModeStore)
 const { isSelectInputsMode, isSelectOutputsMode } = useAppMode()
 const { inputEntryMap, moveBlock } = useAppPanelLayout()
 
-// Match App Mode's panel title (the workflow filename) so builder + App
-// Mode read as the same surface across modes.
+// Match App Mode's panel title (workflow filename) for WYSIWYG parity.
 const panelTitle = computed(() => {
   const path = workflowStore.activeWorkflow?.path
   if (!path) return t('linearMode.builder.title')
@@ -57,18 +44,12 @@ const emptyCopy = computed(() => {
 </script>
 
 <template>
-  <!-- Positioned ancestor so FloatingPanel's preset-based absolute
-       positioning resolves inside the builder just like it does inside
-       .layout-view. Left edge is offset by `--sidebar-width` so the
-       wrapper's coordinate system starts after the Comfy sidebar —
-       matching App Mode, where LayoutView is a flex sibling of the
-       sidebar and so already starts past it. With both contexts sharing
-       the same origin, the FloatingPanel preset classes use `left: 0`
-       and land flush against the sidebar in either mode. The root is
-       pointer-events-none so clicks on empty chrome areas fall through
-       to the graph canvas; FloatingPanel opts back into pointer-
-       events-auto in its own root class list so the panel itself still
-       captures input. -->
+  <!-- Positioned ancestor so FloatingPanel's absolute positioning
+       resolves correctly. Left offset by `--sidebar-width` so the
+       coordinate system starts past the Comfy sidebar — matching
+       App Mode, where LayoutView is a flex sibling of the sidebar
+       and already starts past it. Root is pointer-events-none so
+       empty chrome space falls through to the graph canvas. -->
   <div
     class="pointer-events-none fixed top-(--workflow-tabs-height) right-0 bottom-0 left-(--sidebar-width,0px) z-100"
   >
@@ -86,9 +67,7 @@ const emptyCopy = computed(() => {
         @reorder="moveBlock"
       />
 
-      <!-- Empty-state picker target. Dashed affordance matches the original
-           builder signal that this is a "drop zone" for widget picks from
-           the canvas; radius + colors align with design tokens. -->
+      <!-- Empty-state drop-zone affordance for widget picks from the canvas. -->
       <div
         v-else
         :class="[

src/renderer/extensions/linearMode/outputWindowStore.ts

@@ -5,28 +5,23 @@ import type { AssetItem } from '@/platform/assets/schemas/assetSchema'
 import type { ResultItemImpl } from '@/stores/queueStore'
 
 /**
- * One floating output window in the App Mode workspace.
- *
- * Lifecycle is fed by `linearOutputStore.activeWorkflowInProgressItems`:
- * windows spawn in `'skeleton'`, transition to `'latent'` / `'image'`,
- * and stay in the store after the source item gets absorbed out of
- * the in-progress list — that's what gives the canvas its moodboard
- * accumulation across runs.
+ * One floating output window. Fed by
+ * `linearOutputStore.activeWorkflowInProgressItems`: spawns at
+ * `'skeleton'`, transitions to `'latent'` / `'image'`, and stays
+ * after the source item is absorbed out of the in-progress list —
+ * that's what gives the canvas its moodboard accumulation.
  */
 export interface OutputWindowEntry {
   id: string
-  /** Used to match the window back to its `AssetItem` once the run
-   *  lands in `outputs.media`. */
+  /** Matches the window back to its `AssetItem` via `outputs.media`. */
   jobId?: string
   state: 'skeleton' | 'latent' | 'image'
   latentPreviewUrl?: string
   output?: ResultItemImpl
-  /** Populated by `useOutputWindowSync` once the asset shows up in
-   *  `outputs.media`. Unlocks rerun / reuse-params and the Cloud
-   *  `asset_hash` URL fix. */
+  /** Populated by useOutputWindowSync; unlocks rerun + reuse-params
+   *  and the Cloud asset_hash URL fix. */
   asset?: AssetItem
-  /** Workspace coordinates (pre-transform). LayoutView's transform
-   *  handles zoom/pan. */
+  /** Workspace coordinates (pre-transform). */
   position: { x: number; y: number }
   zIndex: number
 }
@@ -90,8 +85,7 @@ export const useOutputWindowStore = defineStore('appModeOutputWindow', () => {
   function promote(id: string): void {
     const w = windows.value.find((w) => w.id === id)
     if (!w) return
-    // No-op when already topmost — avoids unbounded zIndex climb from
-    // idle clicks on the focused window.
+    // Skip when already topmost — caps zIndex climb from idle clicks.
     const maxZ = windows.value.reduce(
       (m, x) => (x.zIndex > m ? x.zIndex : m),
       0