# Tutorial · Plano de taller (drawing workbench)

Tutorial paso a paso del **módulo de dibujo técnico** de Despiece: el
workbench multi-hoja que arma los planos para llevar al taller
(TechDraw-inspired), con vistas ortogonales, cotas, anotaciones,
leader/flecha, rótulo por hoja, multi-sheet y export PDF/SVG.

El atajo es `Shift+D`.

El módulo es un **`DrawingDocument`** con *sheets*
(`DrawingSheet[]`, soft `parts.drawing v:1`), cada hoja con su *paper*
(A4/A3), *templateId*, *views* (`PartView | SectionView | DetailView`),
*dimensions*, *annotations*, *leaders*, *cosmetics* y un *title block*
con `overrides` por hoja (`title | date | notes | drawnBy`).

---

## 1. Cargar el modelo y abrir el Plano

![Botón del Plano en la topbar](img/01-overview-plano.jpg)

Al importar el STEP/IGES/BREP/glTF/GLB, la sidebar izquierda muestra el
árbol jerárquico. Para entrar al workbench de Plano el atajo es
`Shift+D`, que abre el modal full-screen `dwb-root`.

Si nunca abriste el Plano en este proyecto, la primera vez crea
automáticamente un `DrawingDocument` vacío con una hoja default
(`a4-landscape-plain`, A4 landscape sin cajetín). Las hojas
subsiguientes se crean con `+ Hoja nueva` o derivan de un módulo.

La cámara vuelve a vista isométrica con `Home`; el zoom encaja con `F`.

## 2. Hoja nueva desde un módulo

![Workbench abierto en hoja vacía](img/02-workbench-plano.jpg)

Antes de crear vistas, elegí la **fuente** en el rail izquierdo
(Source):

- **Modelo** (default) — todo el árbol; todas las vistas miran al
  modelo entero.
- **Módulo** — bloqueá a un assembly específico. La lista de módulos
  aparece abajo y se popula con los assemblies del árbol (excluye la
  raíz sintética).

Una vez elegido el módulo, el botón **+ Hoja del módulo** crea
automáticamente una `DrawingSheet` nueva con 3 vistas (front / top /
right) pre-calculadas en escala ajustada y los `templateFields`
iniciales (cliente, orden, fecha) levantados del módulo Cliente.

> **Detrás del botón**: `seedModuleSheet(doc, ...)` en
> `src/drawing/document-seed.ts`. Crea la hoja, setea
> `activeSheetId` y dispara la captura de las 3 vistas
> (`captureViewImages`) — sin re-capturar lo que ya estaba en otras
> hojas.

## 3. Anatomía del workbench

![Anatomía del workbench: topbar, tabs, rails, canvas](img/03-anatomy-plano.jpg)

El workbench tiene 6 zonas con responsabilidades claras:

| # | Zona | Selector | Función |
|---|------|----------|---------|
| 1 | Topbar | `.dwb-topbar` | Brand + herramientas (select / text / line / arrow) + acciones (Nueva vista / PDF / SVG / cerrar). |
| 2 | Tab strip | `.dwb-doc-tabs` | Modo del documento: Planos (default) / Piezas / Herrajes / Proyecto / Rótulo. |
| 3 | Hojas | `.dwb-sheet-tabs` | Tabs multi-hoja: activar / cerrar / rename / drag-reorder. |
| 4 | Rail izq | `.dwb-left` | Template SVG + source (model / módulo) + lista de vistas de la hoja activa. |
| 5 | Canvas | `#dwb-canvas` | SVG 2D con template + vistas + cotas + overlays; `data-tool` cambia el comportamiento del click. |
| 6 | Rail der | `.dwb-right` | Propiedades de la vista seleccionada (scale, rotation, hidden lines), atajos a título block. |

Las herramientas `select · text · line · arrow` mutan `WorkbenchTool`
(en `workbench-tool-state.ts`) y cambian el modo del canvas
(`data-tool="select"` es drag; `"text"` crea anotación; etc.).

## 4. Tabs: Planos · Piezas · Herrajes · Proyecto · Rótulo

![Tab strip con los 5 modos](img/04-doc-tab-strip.jpg)

El tab strip vive justo debajo del topbar:

```
[Planos] [Piezas] [Herrajes] [Proyecto] [Rótulo]
```

Cada tab abre un **overlay** que no rompe el layout del workbench:

| Tab | Qué muestra | Scope |
|-----|--------------|-------|
| **Planos** | Hoja activa (default). | `doc.activeSheetId` |
| **Piezas** | Lista de piezas del scope (módulo / modelo), con cantidad y material. | Hoja viva (`scopeHint`) |
| **Herrajes** | Aplicación de reglas de herraje (similar a `H` panel). | Hoja viva |
| **Proyecto** | Metadatos del documento: sheets count, export options, etc. | Documento |
| **Rótulo** | Editor del `SheetTitleBlock` de la hoja activa (enable / orientation / field visibility / overrides). | Hoja activa |

> Click en el tab activo lo cierra y vuelve a **Planos**. El scrim
> bloquea clicks sobre las herramientas subyacentes y cierra el
> overlay con el mismo botón.

## 5. Crear una vista (scope + escala)

![Diálogo Nueva vista](img/05-new-view-plano.jpg)

El botón **Nueva vista** del topbar dispara `runNewView(...)` en
`src/main/drawing-workbench-new-view.ts`. Antes de abrir el diálogo,
captura un preview del viewport actual; al confirmar, vuelca el
preview a `sessionImages[viewId]` y agrega la vista a la hoja activa.

El diálogo te pide cinco cosas:

| Campo | Opciones | Default |
|-------|----------|---------|
| **Scope** | Modelo / Módulo / Piezas (3-radio) | lo que esté elegido en el rail izquierdo |
| **Perspectiva** | ortogonal / perspectiva | ortogonal |
| **Rotación** | 0° / 90° / 180° / 270° | 0° |
| **Escala** | preset (`2:1` / `1:1` / `1:2` / `1:5` / `1:10` / `1:20` / `1:25` / `1:50` / `1:100`) o input *1:N* | `fit-scale` ajusta a la bounding box del scope en el área 0.9 × paper |
| **Líneas ocultas** | show / hide | hide |

El preset `fit-scale` llama a `fitScaleToArea({model}, area)` en
`src/drawing/scale-presets.ts`: deja la cara del módulo ocupando 90 %
del área de dibujo de la hoja (con margen 5 % alrededor). Para una
cocina 2400 × 600 mm en A4 landscape (297 × 210 mm) da `1:10` como
escala.

> Una vez creada, la vista se puede arrastrar y re-escalar con
> `Wheel` + `Shift`. `Shift+G` (snap-to-grid 5 mm) enciende/apaga el
> snap a múltiplos de `GRID_MM = 5` para drags más prolijos.

## 6. Anotaciones: texto, leader, flecha

![Anotaciones y leader sobre una vista](img/06-annotations-plano.jpg)

Con la herramienta `Texto` activada, click en el canvas crea una
`DrawingAnnotation` con un editor inline
(`workbench-inline-text.ts`). Mientras editás, el SVG paint omite esa
anotación (`getEditingAnnotationId()`) para no tapar el campo.
`Enter` confirma, `Esc` cancela.

Con `Línea` o `Flecha` activadas, click-drag crea un `DrawingLeader`
con `endStyle = 'arrow'` o `'none'`. Los dos estilos de dash
(`solid | short | long | dot`) y los grosores (`0.15 / 0.30 / 0.50 /
0.85` mm) se eligen en el rail derecho cuando el overlay está
seleccionado.

| Herramienta | Toolbar button | Genera |
|-------------|----------------|--------|
| Select | `data-dwb-tool="select"` | — (drag y selección de vistas) |
| Texto | `data-dwb-tool="text"` | `DrawingAnnotation` |
| Línea | `data-dwb-tool="line"` | `DrawingLeader` con `endStyle='none'` |
| Flecha | `data-dwb-tool="arrow"` | `DrawingLeader` con `endStyle='arrow'` |

## 7. Rótulo: habilitar y overrides

![Tab Rótulo con field visibility y overrides](img/07-rotation-plano.jpg)

El tab **Rótulo** abre el editor del `SheetTitleBlock` de la **hoja
activa** (soft field en `parts.drawing v:1`, sin bump del schema). El
componente vive en `workbench-titleblock-ui.ts`.

Estructura:

```ts
// src/drawing/types.ts
interface SheetTitleBlock {
  enabled:    boolean;                              // muestra/oculta el cajetín
  orientation: 'horizontal' | 'vertical';          // horizontal: abajo, vertical: lateral
  visible:    Partial<Record<FieldKey, boolean>>;  // qué campos imprime
  overrides:  Partial<Record<OverrideKey, string>>;// texto editable
}
```

Overrides disponibles por hoja:

| Field key | Override | ¿Aparece por default? |
|-----------|----------|----------------------|
| `title` | `title` | sí (calcado de `project.activeName`) |
| `client` | — (sync desde Cliente) | sí |
| `order` | — (sync desde Cliente) | sí |
| `date` | `date` | sí (YYYY-MM-DD) |
| `scale` | — (derivada de las vistas) | sí |
| `sheet` | — (`i / N` automático) | sí |
| `notes` | `notes` | opcional |
| `drawnBy` | `drawnBy` | opcional |
| `workshop` | — (sync desde Taller) | opcional |

> Los overrides **no** rompen el sync: si el campo es de sync
> (cliente / order / scale / sheet / workshop), el override gana
> hasta que lo limpies — pero la próxima captura lo puede pisar.
> Mejor usarlo solo para `title / date / notes / drawnBy`.

## 8. Multi-hoja: agregar · renombrar · drag

![Sheet bar con 3 hojas + tabs arrastrables](img/08-multi-sheet-plano.jpg)

El bar de hojas (`.dwb-sheet-tabs`) vive arriba del canvas principal.
Sus operaciones vienen de `src/drawing/document-sheet-ops.ts`:

| Operación | Acción | Estado mutado |
|-----------|--------|----------------|
| **Activar** | click en tab | `setActiveSheet` |
| **Cerrar** | click en `×` de la tab | `removeSheet` |
| **Renombrar** | doble-click en tab | inline edit → `beginInlineRename` |
| **Reordenar** | drag de tab (intercambia 2 hojas) | `reorderSheets` |
| **Hoja de módulo** | *+ Hoja del módulo* en el rail izq | `seedModuleSheet` (paso 2) |

Cada hoja es un `DrawingSheet` independiente con su paper, template y
lista de vistas. Soft flag `includeInExport` (`false` excluye de
PDF/SVG). El `DrawingDocument.export.scopeMode` elige entre
`'document'` (todas las `includeInExport !== false`) o
`'selectedSheets'`.

> El sheet tab bar usa el sistema de drag-reorder hand-rolled
> (mousedown/mousemove/mouseup), no HTML5 DnD, así que touchscreens
> lo soportan gratis.

## 9. Exportar PDF · SVG

![Botones PDF / SVG en el topbar del workbench](img/09-export-plano.jpg)

Dos botones en el topbar:

| Botón | Salida | Módulo |
|-------|--------|--------|
| **PDF** | `{modelo}-plano.pdf` — un PDF por cada hoja `includeInExport !== false`, con template SVG + vistas + cotas + cajetín. | `src/main/drawing-export-bundle.ts:makePdfBlob` + `jspdf` |
| **SVG** | `{modelo}-plano-hoja-{N}.svg` — solo la hoja activa, vista por vista en su propio `<g>`. | `makeSvgBlob`, capas `template` / `view-{idx}` / `overlay` |

Ambos re-capturan las vistas antes de exportar (la fuente de verdad
son los `sessionImages` cacheados, no el mesh en vivo) — por lo que
un export siempre refleja lo que viste en pantalla.

> **Fallback**: si en el proyecto no hay `DrawingDocument` todavía,
> los botones están deshabilitados. El atajo `Shift+D` sigue abriendo
> el workbench con una hoja nueva automática.

## 10. Atajos de teclado

![Hoja de atajos](img/10-atajos-plano.jpg)

`Help` (botón de la topbar o `?`) abre la hoja completa. Los más
usados en el flujo del Plano:

| Atajo | Acción |
|-------|--------|
| `Shift+D` | Abrir / cerrar el Drawing workbench (toggle). |
| `Esc` | Cerrar el workbench (overlay / panel). |
| Click + drag | Mover la vista seleccionada (snap-to-grid si está activo). |
| Rueda + `Shift` | Zoom / reescalar la vista bajo el cursor. |
| Doble-click en tab de hoja | Renombrar inline. |
| Drag de tab de hoja | Reordenar (handler hand-rolled). |
| `?` / `F1` | Abrir la hoja de atajos completa. |
| `F` / `Home` | Fit / Fit + iso del viewport 3D. |

En Mac el modificador de sistema es `⌘`; en otros sistemas `Ctrl`.

---

## Ver también

- [Tutorial · Cantos y auto-cantos](cantos-y-auto-cantos.html)
- [Tutorial · Roles y auto-roles](roles-y-auto-roles.html)
- [Tutorial · Optimización de corte](optimizacion-corte.html)
- Spec
  [`2026-07-18-assembly-sheet.md`](../superpowers/specs/2026-07-18-assembly-sheet.md)
  — embrión del módulo (PDF legacy).
- Spec
  [`2026-07-23-drawing-module.md`](../superpowers/specs/2026-07-23-drawing-module.md)
  — diseño del Drawing workbench (Option B, TechDraw-inspired).