@taloswork/ose-shared 0.1.11 → 0.1.13

package/skills/document/generated-visuals.md

@@ -0,0 +1,99 @@
+# Generated visuals inside a deck
+
+Assess whether generated scenes, product concepts or illustrations will help the
+deck explain its message. The user need not explicitly request image generation.
+Choose about 2–3 useful visual pages, not a quota; use fewer or none for a short or
+data-heavy deck, and respect a request to avoid generated images.
+
+The agent calls the actual available `gen` tools; `deck-plan` and `deck-build` only
+assemble existing assets, so rebuilding a deck never regenerates images. The gen
+connector is enabled by default. Call its discovered MCP tool directly using the
+exposed schema for model parameters and references; do not invent tool names or
+duplicate provider-specific rules. Respect a manually disabled connector. If no
+generation tool is available, report that limitation rather than enabling a connector
+or promising an image.
+
+## Plan before generating
+
+Include selected visual pages in the confirmed slide count. In `plan.json`, give each
+its conclusion, visual purpose, mode, notes and a `file` path. The outline
+can reference a file that does not exist yet; `deck-build` needs it after generation.
+Use the existing outline/style confirmation before generation, with no separate image authorization.
+Supporting visuals that preserve an approved outline's message and slide count need no
+new approval, even when chosen later during production.
+
+Default to **generated image + HTML text**: scene, product concept or illustration in
+the image; title, conclusion, accurate figures and sources in the HTML. Native text
+remains editable unless the selected skin bakes that class (`--talos-bake:1`).
+**Whole-page image** is an option for a poster or visual story; its internal text and
+objects cannot be edited separately. Keep evidence-based charts in the chart tools;
+describe a generated concept as a concept, not a photo of a real event or a source.
+
+Example slide entry among the ordinary slides in `plan.json`:
+
+```json
+{
+  "role": "content",
+  "title": "One workspace brings the team together",
+  "image": true,
+  "file": "visuals/workspace.html",
+  "narrative": "Generated visual: a shared workspace concept, image plus HTML text; make the proposed experience concrete.",
+  "notes": "Concept illustration. Explain how shared context reduces handoffs."
+}
+```
+
+Keep plan and spec in the same directory: `file` is resolved relative to the spec.
+Planning keeps the slide's position and notes; write its visible text in the HTML,
+since file slides do not fill catalog slots. Do not put `<img>` into ordinary `slots`
+(they escape HTML), and `image: true` alone does not supply an asset.
+
+## Generate for the actual image box
+
+Once approved, prepare each prompt for the intended box: message, subject/action,
+selected palette and photographic/illustration style, subject placement, crop
+tolerance and text space. Set size and aspect ratio in the tool fields for the actual
+image box. Keep titles and exact numbers outside the image by default. For related scenes, carry the same product/person references and visual
+direction through the supported `gen` reference mechanism.
+
+Keep a small working record of slide number, prompt file, references and returned
+image path. Use the **exact absolute path returned by `gen`** in the HTML; do not
+rename or move the image. The assembled deck may be in a different directory from
+the per-slide file. Escape HTML attribute characters in the path (`&`, `"`, `<`).
+Inspect each generated result before assembling. Reuse it for text/layout revisions;
+regenerate only when the image needs to change.
+
+If gen is unavailable, or a login or network failure prevents generation, report the
+actual error and affected pages. Do not claim a placeholder was generated. If a
+non-generated layout is a suitable fallback, disclose the change and revise the plan
+and slide together; never silently substitute an image already committed in the outline.
+Keep required-image checks on every generated image that remains in the deck.
+
+## Assemble through the existing file route
+
+Write exactly one `section.slide` per file. Example split page (replace the example
+image path with the real tool result and match the selected skin's type/spacing):
+
+```html
+<section class="slide" style="position:relative;width:1280px;height:720px">
+  <h2 class="deck-title" style="position:absolute;left:64px;top:80px;width:1152px;margin:0;color:var(--title);font-size:calc(48px * var(--type-scale,1))">One workspace brings the team together</h2>
+  <p style="position:absolute;left:64px;top:250px;width:420px;color:var(--body);font-size:calc(28px * var(--type-scale,1))">Shared context makes the next step visible.</p>
+  <img data-required-image src="/absolute/path/returned-by-gen.png" alt="Concept illustration of a shared team workspace" style="position:absolute;left:552px;top:210px;width:656px;height:420px;object-fit:cover">
+</section>
+```
+
+`data-required-image` is a presence marker: even `="false"` means required. Use it on
+every generated content image. Local read, fetch or browser decode failure blocks
+previews and PPTX export. Repair the path or asset; never silently replace
+a required image with a placeholder, drop the page, or remove the marker to deliver.
+
+An uploaded template keeps its title bar, logo and footer: use `h2.deck-title` and
+keep content at top ≥210px in its content zone. A whole-page image must also fit that
+zone; only use full bleed when the selected style permits it. Preserve the deck's
+export mode: a few generated images do not require global `--rasterize`.
+
+Build with the usual `deck-build` → `html2pptx` commands and the same style flags.
+Follow deck-design.md's preview and final QA once per image: verify page order and
+notes, image presence, subject crop, image text, contrast, template chrome and style
+consistency across the generated pages. Fix and recheck only changed pages.
+Deliver a PDF by converting the final PPTX through `doc-convert`, including its embedded
+images; do not separately print the slide HTML.

package/skills/document/layouts/MAINTAINERS.md

@@ -0,0 +1,33 @@
+# Maintaining the layout library
+
+Not read while making a deck — this is for whoever edits a `.tpl`, a skin's geometry or
+the catalog.
+
+- **Slot index.** Regenerate `layouts/slots.json` with `node scripts/deck/gen-slots.mjs`
+  after touching a `.tpl`.
+- **Capacity is measured, not written down.** `layouts/capacity.json` holds, per layout ×
+  catalog style, how wide each slot's text may get (CJK = 1, Latin ≈ 0.5), how many rows
+  each `{{#rows}}` block holds, and each chart's box — measured in headless Chromium by
+  `node scripts/deck/gen-capacity.mjs` (≈5 min). Re-run it after touching a `.tpl`, a
+  skin's geometry (sizes, spacing, `--type-scale`) or the catalog;
+  `tests/unit/deck-capacity.test.ts` fails until you do (colour-only edits are ignored).
+- **Optional lines** (2026-10-09): `subhead` (one line at `top:246px`, under a one-line
+  title) and `takeaway` (one line at `bottom:56px`, above the footer rule) are offered only
+  by layouts whose content clears them in every catalog style — measured: content top
+  ≥ 282px for `subhead`, content bottom ≤ 620px at the designed 3-row fill for
+  `takeaway`. Both render nothing when empty (`.deck-subhead:empty`,
+  `.deck-takeaway:empty` in `styles/_contract-defaults.css`).
+
+**不要给可变内容写死容器高度**（`.tpl` 与 bespoke 页都适用）。皮肤给 `.card` 设了
+`overflow:hidden` 时，`.card{height:…px}` 会把超出的文字**静默裁掉**（`blocks-2x2` 就这样
+带病出厂过）。让高度由内容决定：网格用 `grid-auto-rows:min-content`（必须显式写
+`min-content`——`1fr`/`auto` 的自动下限对 `overflow` 非 visible 的网格项一律归零），余量
+交给外层 `justify-content:space-between`。这样超量内容会顶出页面，被 `deck-qa` 的
+`off-canvas`/`overlap` 抓到。PPTX walker 不保留祖先的裁切，原来在 HTML 中被裁掉的字可能
+完整画到容器外；版式生产线的 `scripts/deck/deck-qa-sweep.mjs` 用 `clipped` 阻断裁切。
+
+`spill` measures in-flow text outside its nearest painted container. It remains
+advisory until the capacity probe uses the same measure; `decor-overlap` remains
+blocking. Explicitly positioned or transformed elements are excluded because a
+badge may intentionally cross its parent edge. Keep both clipped and visible
+overflow fixtures when changing the measurement.

package/skills/document/layouts/README.md

@@ -1,32 +1,33 @@
 # Layout library (structure) — pick by role + P1/P2/P3
 
 **Layouts are structure only** — grid, positions, semantic classes, `data-layout` id,
-**zero color** (they pass `lintHardcodedColors`). Theme V2 composes family paint,
-component profile, media treatment and art direction; the layout remains independently selected by
-content intent. See `../theme-system.md` and machine-readable `profiles.json`.
+**zero color** (they pass `lintHardcodedColors`); the skin paints them. This file is the
+single source for layout selection (P1/P2/P3) and the fill contract. One catalog style
+for the whole deck (never mix); which entries take Theme V2 and which layouts need it:
+`../theme-system.md`.
 
 ## How to pick (the deterministic selection)
 
-**Theme — once per deck.** Choose ONE catalog style id. Set `themeVersion:2` for modern
-entries and optionally override `mediaStyle`; entries in catalog collection `original-13`
-are frozen as `classic-v1`, so omit both fields and avoid `themeV2Layouts`. Never mix base
-Themes within one deck.
+`bin/deck-plan.cjs` applies these rules mechanically, plus the measured capacity — run
+it rather than matching by hand. The rules, in priority order (P1 outranks P2 outranks
+P3; never trade fit for variety):
 
-**Scene — automatic from intent.** `deck-build` maps intent to `hero`, `content`,
-`data`, `media`, or `closing`, then balances `decorDensity` across adjacent pages.
-Normally omit both fields; override them only when the automatic art rhythm is wrong.
-
-**Layout — per page, by matching this table:**
-- **P1 structure / image** (most important): does the page have an image? left/right?
-  is it a diagram? pure text? → match `structure` + `has-image` below.
-- **P2 density**: 1–2 points → `light`; 3–4 → `medium`; 5–6 → `dense`. → match `density`.
+- **P1 structure / image** (most important): image or not, which side, diagram or pure
+  text → match `structure` + `has-image` below. Never force text into an image slot or
+  an image into a text slot; drop an unused image slot rather than leave a placeholder.
+- **P2 density**: 1–2 points → `light`; 3–4 → `medium`; 5–6 → `dense` → match
+  `density`. Match the slot count to the point count — condense content to ≤6 items,
+  remove spare slots.
 - **P3 diversity (ENFORCED)**: never the same content layout **twice in a row**, and
-  **≤2× total** across the deck. `html2pptx` warns (`repeated-layout`) at render if you
-  break it. Structural roles (cover/toc/section/ending) are exempt from the ≤2 cap —
-  a `section` divider is reused per chapter.
+  **≤2× total** across the deck — vary the variant even when the family repeats.
+  `html2pptx` warns at render when you break it. Structural layouts (cover / toc /
+  section / transition / title / ending and their variants) are exempt: reuse ONE
+  `section` layout for every chapter break. If P1+P2 can't be met without repeating,
+  author a bespoke slide (deck-design.md) instead of a wrong-fit layout.
 
-Per role: **cover** once; **toc** by chapter count; **section** reused per chapter;
-**ending** once, by purpose.
+Per role: **cover** once; **toc** by chapter count (3–4 → centred/large title, 5–6 →
+list/grid, 7+ → dense/two-column); **section** reused per chapter; **ending** once, by
+purpose (thanks / Q&A / contact).
 
 ## How to fill (the deck-build contract)
 
@@ -36,8 +37,9 @@ slide fills a layout through three inputs:
 - **`slots`** — one value per `{{name|default}}` → `{"layout":"cover","slots":{"title":"…"}}`
 - **`rows`** — a variable-length list per `{{#key}}…{{/key}}` block; each row fills that
   block's own fields, and `{{_n}}`/`{{_nn}}` number the copies for you.
-- **`chart`** — replaces the layout's `data-chart` (a native, editable pptx chart). An
-  array fills several charts in document order.
+- **`chart`** — replaces the layout's chart data; an array fills several charts in
+  document order. Native editable `c:chart` by default; `"chartRender":"svg"` (spec) or
+  `"render":"svg"` (one chart) draws it as SVG — choice per deck-design.md "Charts".
 
 **Figure layouts take INPUT fields the template never prints** — deck-build derives the
 geometry from them, so the drawing always matches the numbers:
@@ -50,31 +52,40 @@ geometry from them, so the drawing always matches the numbers:
 | `radar` | `metrics` | `name`,`score` | **the radar chart itself** |
 
 `radar` is marked `"chart": "derived"` in slots.json: its chart is built from `metrics`,
-so pass rows and never `chart` for it.
+so pass rows, never chart data; `chart` may only add options (`{"max": 10}` = the outer
+ring, else a clean ceiling over the scores; `unit`, `showValues`, `render`).
+`deck-plan` routes a single-series `{type:"radar"}` chart here as `metrics` (a 660×394
+box vs chart-full's 1120×316 strip, where a radar is height-bound and small).
 
 Plain list layouts take rows too: `team-row.members{name,role}` ·
 `brand-values.values{name,body}` · `color-palette.swatches{name,hex}` ·
 `steps-vertical.steps{name,body}` · `toc-panel.entries{name,desc}`.
 
+**Optional lines** — a slide's `subtitle` (口径 / why it matters) and `takeaway` (启示) fill
+`subhead` (under a one-line title) and `takeaway` (above the footer), offered by
+cards-3 · three-kpi · two-kpi · steps · steps-vertical · timeline · icon-row ·
+ring-progress · versus · data-table · image-grid · gantt (both) and funnel · pyramid ·
+matrix-2x2 (subtitle) · comparison (takeaway). Left out, they render nothing; written for
+a layout without the line, `deck-plan` warns `dropped` and ranks a layout that has it.
+
 Anything the spec gets wrong — unknown layout/slot/field, a repeat block with no rows, a
 figure row missing its numbers — **fails the build** (exit 1, nothing written) rather than
-shipping the template's demo content. Regenerate the index with `node scripts/deck/gen-slots.mjs`
-after touching a `.tpl`.
-
-**不要给可变内容写死容器高度。** `.card{height:…px}` 这类写法在皮肤给 `.card` 设了
-`overflow:hidden` 时会把超出的文字**静默裁掉**（`blocks-2x2` 就这么带着缺陷出厂过）。
-让高度由内容决定：网格用 `grid-auto-rows:min-content`（下限必须显式写 `min-content` ——
-`1fr`/`auto` 的自动下限对 `overflow` 非 visible 的网格项一律归零），余量交给外层
-`justify-content:space-between`。这样内容超量时会把后续元素顶出页面，被 `deck-qa` 的
-`off-canvas`/`overlap` 抓到，而不是变成一排缺了下半截的字。被祖先 `overflow:hidden`
-裁掉的文字不会出现在 pptx 的几何里，运行时的 `deck-qa` 看不到——它只在版式生产线的
-`scripts/deck/deck-qa-sweep.mjs`（`clipped` 硬失败，逐个版式扫整册库）里被拦截；写 bespoke
-页时请直接避免定高容器。
+shipping the template's demo content. **Capacity is measured** (`layouts/capacity.json`,
+per layout × style: slot widths, row ceilings, chart boxes): `deck-plan` picks with it,
+`deck-build` rejects overflow with it. The density column below feeds `deck-plan` too: a
+rows layout is not offered for fewer items than its `(n–m)` names. A bespoke slide never
+fixes a card's height around variable text (`overflow:hidden` clips it silently) — use
+`grid-auto-rows:min-content`. Maintaining layouts: `layouts/MAINTAINERS.md`.
+
+QA: `clipped` and `decor-overlap` block; `spill` is advisory. The PPTX walker does
+not reproduce ancestor clipping, so inspect the exported deck too.
 
 ## Catalog
 
 Each slide carries `data-layout="<id>"` (drives the diversity lint + traceability).
 
+**Theme V2 only:** `pitch-problem` · `pitch-solution` · `market-rings` · `product-device` · `traction-milestones` · `business-model` · `pricing-tiers` · `funding-ask` · `customer-proof` · `team-founders` (profiles.json `themeV2Layouts`). A style in the `classic-v1` collection (cool, mckinsey, apple …) renders V1 and cannot use them — `deck-plan --layouts --style <id>` lists exactly what a style can use and the content each layout takes.
+
 | layout-id | role | structure (P1) | density (P2) | has-image (P1) | pick when |
 |---|---|---|---|---|---|
 | `cover` | cover | hero · left-title | — | text-only (bg) | 封面 / 开场 |
@@ -107,6 +118,8 @@ Each slide carries `data-layout="<id>"` (drives the diversity lint + traceabilit
 | `image-left` | content | image-left + text-right | medium (3) | **photo/diagram slot** | 图文案例(图在左) |
 | `image-grid` | content | 3-up image gallery + captions | medium (3) | **photo slots** | 三图并列 / 图库 |
 | `concept-hub` | content | center concept + satellites | medium (4) | text-only | 核心框架(中心+维度) |
+| `hub-flow` | content | 3 inputs → core → result | medium (3) | text-only | 多源汇聚→核心→产出(产品原理/数据流) |
+| `mock-qa` | content · product | interface sketch: question → cited answer + 2 sources | light (2) | text-only | 产品问答/证据链示意(无截图时) |
 | `image-full` | content | full-bleed image + overlay caption | light | **full-bleed photo** | 全出血大图 + 压字说明 |
 | `cover-image` | cover | full-bleed image + overlay title | — | **full-bleed photo** | 图片封面(压字) |
 | `timeline` | content | horizontal dated timeline | medium (4–5) | text-only | 时间轴 / 发展历程 |
@@ -115,7 +128,7 @@ Each slide carries `data-layout="<id>"` (drives the diversity lint + traceabilit
 | `section-stat` | section | ghost-number + hero stat | light | text-only | 章节页(带关键数字) |
 | `transition` | transition | minimal big-number break | light | text-only | 纯过渡页(整册复用一个) |
 | `funnel` | content · data | narrowing funnel stages | medium (4) | text-only | 转化漏斗 |
-| `radar` | content · data | native radar chart + score list (rows) | medium (4–6) | diagram (chart) | 能力雷达 / 多维评估 |
+| `radar` | content · data | radar chart (SVG or native) + score list (rows) | medium (4–6) | diagram (chart) | 能力雷达 / 多维评估 |
 | `ring-progress` | content · data | ring gauges (rows) | medium (2–4) | diagram | 环形进度 / 完成率 |
 | `icon-row` | content | icon row (3–4) | medium (4) | text-only | 图标行 · 能力/特性(L16) |
 | `gantt` | content · data | gantt schedule bars (rows) | dense | text-only | 甘特图 / 项目排期 |

package/skills/document/layouts/big-stat.tpl

@@ -1,4 +1,4 @@
 <!-- layouts/big-stat — structure-only (paint via styles/<skin>/skin.css). data-layout drives P1/P2/P3 + dedup. -->
 <section class="slide" data-layout="big-stat" style="position:relative;width:1280px;height:720px;overflow:hidden"><div class="slide-backdrop"></div><div class="eyebrow-row" style="position:absolute;left:calc(96px * var(--space-scale,1));top:132px;display:flex;align-items:center;gap:14px"><span class="accent-bar" style="width:30px;height:1px;display:inline-block"></span><span class="eyebrow" style="font-size:calc(13px * var(--type-scale,1));letter-spacing:.28em">{{eyebrow|KEY METRIC}}</span></div><h2 class="deck-title" style="position:absolute;left:calc(92px * var(--space-scale,1));top:158px;font-size:calc(48px * var(--type-scale,1));letter-spacing:-.4px">{{title|}}</h2>
- <div class="stat-num" style="position:absolute;left:90px;top:250px;font-weight:800;line-height:1;font-size:calc(216px * var(--type-scale,1));letter-spacing:-2px">{{stat|585}}<span class="stat-unit" style="font-size:calc(64px * var(--type-scale,1))">{{unit| 单位}}</span></div><div class="stat-lead" style="position:absolute;left:100px;top:520px;font-size:calc(30px * var(--type-scale,1));font-weight:600">{{lead|一句结论,数字说明了什么}}</div><p class="stat-note" style="position:absolute;left:100px;top:580px;width:900px;font-size:calc(17px * var(--type-scale,1));line-height:1.6">{{note|一句支撑说明,给上下文与来源。}}</p>
+ <div class="stat-num" style="position:absolute;left:calc(90px * var(--space-scale,1));top:250px;font-weight:800;line-height:1;font-size:calc(216px * var(--type-scale,1));letter-spacing:-2px">{{stat|585}}<span class="stat-unit" style="font-size:calc(64px * var(--type-scale,1))">{{unit| 单位}}</span></div><div class="stat-lead" style="position:absolute;left:calc(100px * var(--space-scale,1));top:520px;font-size:calc(30px * var(--type-scale,1));font-weight:600">{{lead|一句结论,数字说明了什么}}</div><p class="stat-note" style="position:absolute;left:calc(100px * var(--space-scale,1));top:580px;width:900px;font-size:calc(17px * var(--type-scale,1));line-height:1.6">{{note|一句支撑说明,给上下文与来源。}}</p>
 <div class="rule rule-foot" style="position:absolute;left:calc(96px * var(--space-scale,1));right:calc(96px * var(--space-scale,1));bottom:40px;height:1px"></div><div class="deck-footer" style="position:absolute;left:calc(96px * var(--space-scale,1));bottom:17px;font-size:calc(12px * var(--type-scale,1));letter-spacing:.1em">{{footer|报告标题 / 章节}}</div><div class="deck-pageno" style="position:absolute;right:calc(96px * var(--space-scale,1));bottom:17px;font-size:calc(12px * var(--type-scale,1))">{{pageno|01}}</div></section>