@taloswork/ose-shared 0.1.9 → 0.1.10

package/skills/document/rewrite.md

@@ -1,28 +1,30 @@
 # Generate / edit documents (L3)
 
-## Themes — the presentation layer for `doc-gen` DOCUMENTS (docx / pdf / spec-pptx)
+## Themes — the presentation layer for `doc-gen` DOCUMENTS (docx / pdf)
 
 > **Decks use skins, not themes.** For an html2pptx deck (路演/汇报/pitch), pick a
 > **skin** via `--style` (`styles/README.md`, the SKILL deck route) — NOT a
 > `themes/*.json`. The `themes/` + `--theme` system below is for `doc-gen`
-> DOCUMENTS (Word/PDF reports, structured-spec decks) — a separate, still-valid path.
+> DOCUMENTS (Word/PDF reports) — a separate, still-valid path. `doc-gen` makes no
+> decks at all; `html2pptx --theme` reads a theme's colors/fonts and its three
+> slide colors (`pptx{background,titleColor,textColor}`).
 
 Content (the spec) and presentation (the theme) are separate. A theme is a JSON
-file — template skills ship their own; this skill ships **8 built-ins** in `themes/`
-(theme = colors/fonts for `doc-gen` output): `cool-tech` · `apple-keynote` ·
-`mckinsey-consulting` · `anthropic-clay` · `black-gold` · `hand-drawn` · `mono` ·
-`warm-editorial`. For a plain Word/PDF report, `mckinsey-consulting` (white · deep
+file — template skills ship their own; this skill ships **12 built-ins** in `themes/`
+(theme = colors/fonts for `doc-gen` output; `themes/README.md` lists them with their
+best fit): `cool-tech` · `apple-keynote` · `mckinsey-consulting` · `anthropic-clay` ·
+`black-gold` · `hand-drawn` · `mono` · `warm-editorial` · `ivory-gold` · `cinereel` ·
+`magazine-ink` · `swiss-grid`. For a plain Word/PDF report, `mckinsey-consulting` (white · deep
 navy · structured tables) is a safe default; `mono` for a stark minimal look.
 
 ```
 node <skill>/bin/doc-gen.cjs docx out.docx spec.json --theme <skill>/themes/mckinsey-consulting.json
 ```
 
-**Topic-adaptive color (pptx, when the user hasn't named a theme/brand)**: pass
-`--topic "<deck subject>"` (or put `"topic"` in the spec). The engine picks a
+**Topic-adaptive color (when the user hasn't named a theme/brand)**: pass
+`--topic "<subject>"` (or put `"topic"` in the spec). The engine picks a
 palette that FITS the subject — deterministically, by keyword then stable hash —
-instead of the same default on every deck (the #1 "AI-generated" tell), and turns
-on the richness tokens (motif + gradient wash + depth). `--palette <id>` forces a
+instead of the same default every time (the #1 "AI-generated" tell). `--palette <id>` forces a
 named one; `doc-gen --list-palettes` prints the library. A `--theme` file or a
 saved/brand preference (step 1 below) still wins — use `--topic` for the "just
 make it look designed-for-this" case, not when the user has a look in mind.
@@ -60,10 +62,10 @@ existing deck can seed one too: `pptx-theme ref.pptx <skill>/themes/custom/x.jso
 
 ```
 node <skill>/bin/pptx-theme.cjs ref.pptx /tmp/ref-theme.json
-node <skill>/bin/doc-gen.cjs pptx out.pptx spec.json --theme /tmp/ref-theme.json
+node <skill>/bin/html2pptx.cjs deck.html out.pptx --theme /tmp/ref-theme.json
 ```
 
-This captures colors/fonts/title-body sizes (heuristic fallbacks print on
+This captures colors/fonts (heuristic fallbacks print on
 stderr), NOT slide layouts — to reuse the deck's actual LAYOUTS, tokenize it into
 a fillable template instead (see "Reuse a user's UPLOADED deck" below:
 `pptx-tokenize` → `doc-fill`).
@@ -71,26 +73,18 @@ a fillable template instead (see "Reuse a user's UPLOADED deck" below:
 Theme fields (all optional; invalid values default + warn on stderr, never fail):
 `bestFor` (one-line 适用场景, for the picker) · `fonts{heading,body}` ·
 `colors{primary,accent,secondary,text,muted,tableHeaderBg,tableBorder}`
-(`accent` drives timeline markers/card bars/KPI numbers and defaults to
-`primary`; `secondary` defaults to `muted`) ·
-`page{size:A4|Letter,margin,header,footer}` (`{title}` `{page}` `{pages}` interpolate;
+(`accent` defaults to `primary`; `secondary` defaults to `muted`) ·
+`page{size:A4|Letter,margin,header,footer}` (`margin` is a CSS length string such as `margin:"20mm"` — mm/cm/in/pt/px; a bare number is not accepted and falls back to the default margin, which changes the page count; `{title}` `{page}` `{pages}` interpolate;
 **page header/footer: prefer Latin/digits — CJK there renders blank in the PDF path**) ·
 `heading{h1..h4}{size,color,bold,spaceAfter}` (color takes hex or a palette key like `"primary"`) ·
 `body{size,lineHeight,justify}` · `cover{enabled,subtitle,date,logo}` (base64 logo; title moves onto the cover) ·
-`pptx{background,titleColor,textColor,titleSize,bodySize,logo,logoPos,slideNumber,
-motif:"none|corner|sidebar",bgWash,depth}`
-(dark deck = dark `background` + light `titleColor`/`textColor`; docx/PDF stay
-white-paper regardless. `motif` stamps a repeated accent on content slides;
-`bgWash` makes the master background a subtle gradient; `depth` gives statement
-slides (cover/section/ending) a gradient background + an oversized ghosted accent
-shape (layered, not flat). Background lives on the slide MASTER — edit it once in
-PowerPoint to reflow every slide.)
+`pptx{background,titleColor,textColor}` — read only by `html2pptx --theme`, as the
+slide background / title / body CSS colors (dark deck = dark `background` + light
+`titleColor`/`textColor`; docx/PDF stay white-paper regardless).
 
 Per format the theme becomes: **pdf** CSS + cover page + live page headers/footers;
 **docx** real document styles (Heading1–4, default font/size, table header shading)
-+ header/footer parts + cover page; **pptx** a slide master (background/logo/footer/
-slide numbers) + themed title/body — and content **flow-layouts**: it never overlaps,
-overflow spills to a "(续)" continuation slide. A spec may embed `"theme": {...}`;
++ header/footer parts + cover page. A spec may embed `"theme": {...}`;
 `--theme <file>` wins.
 
 ## Template decks — `bin/pptx-clone` (one styled slide per data item)
@@ -192,18 +186,20 @@ each, drop the template slide).
 layouts → `pptx-theme` (extract palette) + our families. Repeat a styled slide
 per data row → `pptx-clone`.
 
-All-Node generation (no Python): `docx`, `pptxgenjs`, `exceljs`, `pdf-lib`. Same
-capability tier as the Anthropic docx/pptx/xlsx skills.
+All-Node generation (no Python): `docx`, `exceljs`, and Chromium for PDF; decks go
+through html2pptx. Same capability tier as the Anthropic docx/pptx/xlsx skills.
 
 ## Generate — `bin/doc-gen` (self-contained; no npm install, works offline)
 
 ```
-node <skill>/bin/doc-gen.cjs <docx|xlsx|pptx|pdf> <out> <spec.json>
+node <skill>/bin/doc-gen.cjs <docx|xlsx|pdf> <out> <spec.json>
 ```
 Simple spec shapes:
 - **docx / pdf**: `{ "title"?: "...", "paragraphs": ["...", ...] }`
 - **xlsx**: `{ "sheets": { "SheetName": [["h1","h2"], ["a", 1], ...] } }` (row 1 = bold header)
-- **pptx**: `{ "slides": [{ "title"?: "...", "bullets"?: ["...", ...] }] }`
+
+`doc-gen pptx` exits 64 and points at html2pptx: decks are laid out as HTML
+(deck-design.md), never generated from a slide spec.
 
 `doc-gen` validates these shapes **strictly before rendering**: unknown fields are
 errors, not ignored. For DOCX/PDF use `paragraphs` and/or `blocks`—never
@@ -221,76 +217,20 @@ Rich spec shapes (use these for real documents, not just prose):
 - **xlsx** per sheet, either the row array above OR
   `{ "rows": [...], "header"?, "columnWidths"?: [n...], "numFmt"?: ["#,##0.00"...] }`.
   A cell string starting with `=` is written as a **live formula** (e.g. `"=SUM(A2:A3)"`).
-- **pptx** per slide, add any of `"table": [[...]]`, `"image": {data, x,y,w,h}`,
-  `"chart": {type:"bar|line|pie|doughnut|area", labels:[...], series:[{name, values:[...]}]}` —
-  charts are NATIVE (PowerPoint-editable c:chart parts), series colors cycle the
-  theme's layered palette (accent→secondary→primary), dark decks get readable
-  axis/legend text automatically. Prefer a chart over a numbers table when the
-  point is a trend or comparison.
-- **pptx design archetypes** (per slide — USE THESE for pitch/roadshow decks
-  (路演/汇报/评审/宣讲), not bullets-of-everything; all theme-colored,
-  flow-layouted, overflow-safe). **For a substantive deck, first read
-  content-pipeline.md** (research → pyramid structure → per-page content
-  structure → the mapping to these archetypes → density + diversity rules).
-  Catalog:
-  - **Role**: `"cover": {title, subtitle?, presenter?, date?, variant?}` (封面,
-    own slide) · `"toc": {items:[{index?,title,desc?}], variant?:"numbered|grid"}`
-    (目录) · `"section": {title, subtitle?, index?, variant?:"centered|left|index"}`
-    (章节页,own slide) · `"ending": {message, cta?, contact?, variant?}` (结尾).
-  - **Metrics**: `"kpiCards"` — array OR `{items:[{value,label?,delta?,icon?}], variant?:"row|grid|hero|iconTop"}`
-    ("+x%" green, "-x%" red; `iconTop` shows the card's lucide `icon` above the number) ·
-    `"bigStat": {value, label?, context?, sub?:[kpi]}` (单个巨型数字).
-  - **Content**: `"cards"` — array OR `{items:[{title,text?,accent?,icon?,image?}], variant?:"accentBar|numbered|iconCircle|imageTop"}`
-    (`iconCircle` = lucide `icon` in an accent circle; `imageTop` = the card's base64 `image` as a top banner) ·
-    `"comparison": {columns:[{title,badge?,rows:[…],recommended?}], dimensions?:[…], variant?:"columns|matrix"}`
-    (2–3 栏对比;`matrix` = 特性打勾矩阵,cells 是 有/是/✓ → 绿勾、无/否/- → 叉,否则文字) ·
-    `"quadrant": {xAxis?,yAxis?, cells:[TL,TR,BL,BR]}` (2×2 矩阵) ·
-    `"iconList": {items:[{icon?,title,text?,accent?}], variant?:"rows|grid"}` (icon = a
-    lucide name e.g. "zap"/"shield"/"target"/"users"/"trending-up"; unknown → marker fallback) ·
-    `"quote": {text, author?, role?}`.
-  - **Process/time**: `"steps": {items:[{label,detail?,output?,duration?}], variant?:"horizontal|vertical"}` ·
-    `"timeline"` — array OR `{items:[{label,text?}], variant?:"horizontal|vertical|detailCards"}`
-    (`detailCards` = nodes on a line each with a styled detail card beneath).
-  - **Media**: `"splitImage": {image:{data}, side?:"left|right", title?, bullets?:[…], cards?:[…]}`.
-  Render order within a slide: kpiCards → cards → comparison → quadrant → bigStat →
-  quote → toc → steps → iconList → splitImage → timeline → bullets → table → image → chart.
-  **Vary variants across pages** (content-pipeline.md diversity rule) — a
-  monotone deck of one variant reads as lazy.
-
-  **Designed HTML render (`--design html`, in-app, magazine ceiling)**: the SAME
-  spec, but `cover`/`section`/`bigStat`/`comparison`/`quadrant`/`splitImage`/
-  `iconList` slides render through curated HTML/CSS templates (fuller design)
-  instead of native shapes:
-  `doc-gen.cjs pptx out.pptx spec.json --theme <t> --design html`.
-  Trade-off — richer look, but the output is a flat collage (editable text, **no
-  master/placeholder structure**); charts fall back to native. It needs the
-  app's Chromium; **headless or any slide without a designed template auto-falls
-  back to the native renderer** (same spec, no failure). Use it when the user
-  wants a polished pitch/cover and the deck is mostly the covered archetypes;
-  stick with the default (native) for editable structure, charts, or headless.
-  A layout the templates still can't express → deck-design.md freeform html2pptx.
-
-Under the hood it uses `docx` / `exceljs` / `pptxgenjs` / `pdf-lib` — the same
+Under the hood it uses `docx` / `exceljs`, and prints PDF in Chromium — the same
 tier as the Anthropic docx/pptx/xlsx skills, but all-Node (no Python /
 LibreOffice) and bundled into the script. For anything past these shapes, write a
 short Node script using those libraries directly (they are on the skill's path).
 
-**PDF rendering (two engines, automatic):**
-- **In-app (default): Chromium `printToPDF`.** When running inside Talos,
-  `doc-gen pdf` renders your spec as HTML through the main process → professional
-  CJK line-breaking, per-glyph font fallback (Latin + 中文 mixed just works),
-  justification, tables. This is the formal-delivery path. Output tags
-  `[pdf (chromium)]`. The spec's `blocks` (headings/lists/tables) are supported
-  here too, not just `title`/`paragraphs`.
-- **Headless fallback: pdf-lib.** Outside the app (no render service), it uses the
-  bundled pdf-lib engine (word-wrap + CJK char-wrap + per-script fonts). For CJK
-  it embeds a subset Unicode font from a system font or `$TALOS_PDF_FONT` /
-  `spec.fontPath`; if none is found it errors clearly — set `$TALOS_PDF_FONT`, or
-  generate `.docx` (OOXML references fonts by name, so CJK just works). Output
-  tags `[pdf (pdf-lib)]`.
-
-Either way, **prefer `.docx` for the richest CJK layout** when a PDF isn't
-strictly required.
+**PDF rendering (always Chromium, one layout everywhere):** `doc-gen pdf`
+renders your spec as themed HTML and prints it in Chromium — professional CJK
+line-breaking, per-glyph font fallback (Latin + 中文 mixed just works),
+justification, tables, clickable links that wrap inside the page, and the
+theme's page size and margin. Inside Talos it goes through the app's service
+(`[pdf (chromium)]`); elsewhere it uses a headless Chromium
+(`[pdf (headless chromium)]`, needs Playwright). With neither it exits 69 and
+writes nothing — tell the user the PDF could not be produced. The spec's
+`blocks` (headings/lists/tables) are supported, not just `title`/`paragraphs`.
 
 ## Fill a template — `bin/doc-fill` (preserves styling; the best "edit" path)
 
@@ -361,9 +301,13 @@ node <skill>/bin/doc-run.cjs --list          # the guaranteed module registry
 ```
 
 Inside the script, plain CommonJS `require()` of these names is guaranteed:
-`pptxgenjs` (decks) · `docx` (Word) · `xlsx` (SheetJS workbooks) ·
-`pdf-lib` (PDF assembly) · `jszip` / `pizzip` (OOXML zip surgery) ·
-`hyperformula` (formula evaluation). Nothing else is guaranteed — do not
+`pptxgenjs` (non-deck pptx only — data tables, one-off shapes; every deck goes through html2pptx) · `docx` (Word) · `exceljs` (formatted workbooks: fills,
+fonts, borders, merges, formulas) · `xlsx` (SheetJS: reading and plain-data
+workbooks only — it writes no cell styles) · `pdf-lib` (PDF assembly) ·
+`jszip` / `pizzip` (OOXML zip surgery) · `hyperformula` (formula evaluation).
+An exceljs formula is written without a cached result; run
+`bin/xlsx-recalc.cjs` on the file when the values must show before Excel
+recalculates. Nothing else is guaranteed — do not
 `require` other packages, and never run `npm install`.
 
 Rules of the tier ladder (try in this order, don't skip levels). **NOTE — decks

package/skills/document/styles/README.md

@@ -126,13 +126,6 @@ Opt-outs (auto-pick skips these; `--backdrop` still works explicitly if ever
 needed): `mckinsey`, `mono` → 纯色(no backdrop, by design) · `cinereel` → 常驻胶片
 取景框(每页恒定,故意排除在自动挑选之外).
 
-Leave `--backdrop` unset and html2pptx **auto-picks one of the skin's available
-`backdrop*.html` variants**, seeded by the deck's HTML content — the same
-deck.html always resolves to the same variant (stable across the QA fix-loop's
-re-renders), but different decks land on different variants, so repeat
-generations of the same skin don't all look identical. Pass `--backdrop
-<variant>` only when you need a specific one pinned.
-
 ## Extend
 
 Add a skin = **one `styles/<name>/skin.css`** defining the full class contract

package/skills/document/theme-system.md

@@ -43,6 +43,7 @@ rewrite a layout.
 ```json
 {
   "style": "cool",
+  "scenario": "发布会",
   "themeVersion": 2,
   "decorRhythm": "auto",
   "mediaStyle": "device-stage",

package/skills/document/themes/README.md

@@ -1,11 +1,11 @@
 # Built-in themes
 
-**12 套主题**,`doc-gen --theme themes/<name>.json` 或 `html2pptx --theme` 使用。每个文件
-是 doc-theme 契约的纯 JSON(`bestFor` = 适用场景)。
+**12 套主题**,给 `doc-gen --theme themes/<name>.json`(Word/PDF 文档)使用;`html2pptx --theme`
+是 legacy 路径,deck 一律用 `--style <catalog id>`。每个文件是 doc-theme 契约的纯 JSON
+(`bestFor` = 适用场景)。
 
-**一个主题 = 一套自洽视觉**,与一个 `templates/<家族>` **一一对应**:主题管**颜色 / 字体**,
-家族管**版式**(slide 布局 + 签名装饰)。用户选一次主题 = 同时定了配色和布局。
-非 deck 文档(Word/PDF/Excel)没有家族概念,只吃主题的调色板(白纸 + 品牌色标题/表格)。
+主题只管**颜色 / 字体**;"配对家族"一列是同名 deck 风格(`catalog.json` 的 entry),
+方便文档与 deck 配色一致。非 deck 文档没有版式概念,只吃主题的调色板(白纸 + 品牌色标题/表格)。
 
 | 主题 | 配对家族 | 基调 | 适用场景 |
 |---|---|---|---|

package/skills/document/themes/anthropic-clay.json

@@ -33,12 +33,6 @@
   "pptx": {
     "background": "#f0eee6",
     "titleColor": "#191919",
-    "textColor": "#191919",
-    "titleSize": 26,
-    "bodySize": 16,
-    "motif": "none",
-    "bgWash": true,
-    "depth": true,
-    "slideNumber": true
+    "textColor": "#191919"
   }
 }

package/skills/document/themes/apple-keynote.json

@@ -25,12 +25,6 @@
   "pptx": {
     "background": "#000000",
     "titleColor": "#f5f5f7",
-    "textColor": "#f5f5f7",
-    "titleSize": 32,
-    "bodySize": 18,
-    "motif": "none",
-    "bgWash": true,
-    "depth": false,
-    "slideNumber": false
+    "textColor": "#f5f5f7"
   }
 }

package/skills/document/themes/black-gold.json

@@ -18,7 +18,6 @@
   "pptx": {
     "background": "#0b0b0d",
     "titleColor": "#f5e6b8",
-    "textColor": "#cbbd97",
-    "slideNumber": true
+    "textColor": "#cbbd97"
   }
 }

package/skills/document/themes/cinereel.json

@@ -18,7 +18,6 @@
   "pptx": {
     "background": "#0D0D0C",
     "titleColor": "#F5F4F0",
-    "textColor": "#C7C5BE",
-    "slideNumber": true
+    "textColor": "#C7C5BE"
   }
 }

package/skills/document/themes/cool-tech.json

@@ -18,7 +18,6 @@
   "pptx": {
     "background": "#0a0e1a",
     "titleColor": "#ffffff",
-    "textColor": "#aab6d4",
-    "slideNumber": true
+    "textColor": "#aab6d4"
   }
 }

package/skills/document/themes/hand-drawn.json

@@ -18,7 +18,6 @@
   "pptx": {
     "background": "#fbfaf6",
     "titleColor": "#2b2b2b",
-    "textColor": "#3a3a3a",
-    "slideNumber": true
+    "textColor": "#3a3a3a"
   }
 }

package/skills/document/themes/ivory-gold.json

@@ -18,7 +18,6 @@
   "pptx": {
     "background": "#EEE8DA",
     "titleColor": "#A97C3F",
-    "textColor": "#2B2823",
-    "slideNumber": true
+    "textColor": "#2B2823"
   }
 }

package/skills/document/themes/magazine-ink.json

@@ -18,7 +18,6 @@
   "pptx": {
     "background": "#F1F3F5",
     "titleColor": "#0A1F3D",
-    "textColor": "#384962",
-    "slideNumber": true
+    "textColor": "#384962"
   }
 }

package/skills/document/themes/mckinsey-consulting.json

@@ -41,12 +41,6 @@
   "pptx": {
     "background": "#ffffff",
     "titleColor": "#051c2c",
-    "textColor": "#1c2b3a",
-    "titleSize": 24,
-    "bodySize": 15,
-    "motif": "none",
-    "bgWash": false,
-    "depth": false,
-    "slideNumber": true
+    "textColor": "#1c2b3a"
   }
 }

package/skills/document/themes/mono.json

@@ -14,7 +14,6 @@
   "pptx": {
     "background": "#ffffff",
     "titleColor": "#0a0a0a",
-    "textColor": "#555555",
-    "slideNumber": true
+    "textColor": "#555555"
   }
 }

package/skills/document/themes/swiss-grid.json

@@ -18,7 +18,6 @@
   "pptx": {
     "background": "#FAFAF8",
     "titleColor": "#0A0A0A",
-    "textColor": "#3D3D3B",
-    "slideNumber": true
+    "textColor": "#3D3D3B"
   }
 }

package/skills/document/themes/warm-editorial.json

@@ -18,7 +18,6 @@
   "pptx": {
     "background": "#f7f2ea",
     "titleColor": "#241a12",
-    "textColor": "#6b5d4c",
-    "slideNumber": true
+    "textColor": "#6b5d4c"
   }
 }

package/skills/image-layout/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: image-layout
-description: "Use this skill whenever the user wants EXISTING images combined or altered as pixels — 拼图 / 拼接 / 拼一张 / 宫格 / 九宫格 / 长图 / 对比图 / 前后对比 / 加水印 / 加标签 / 加边框 / 裁剪 / 圆角 / 缩放, or stitch / combine / merge images / collage / contact sheet / side-by-side / before-after / watermark / label / crop / round corners / resize. Examples: 'combine these four into one picture', '把生成的几张图拼成九宫格', 'add a caption under each'. Method: HTML+CSS rendered by this skill's bin/html2img.cjs. The mechanical test: if the images do not exist as files yet, this is NOT the skill. Do NOT trigger for: generating NEW images, INCLUDING when the request names a layout word — '生成一张九宫格的图' asks for ONE generated picture whose COMPOSITION is a grid, not for tiling existing files; documents / PDF / PowerPoint (document skill); Xiaohongshu cards (talos-xhs-ops); or upscaling / background removal / content-aware fill, which need a model, not CSS."
+description: "Use when EXISTING images (files already on disk) are combined or altered as pixels: 拼图 / 拼接 / 宫格 / 九宫格 / 长图 / 对比图 / 加水印 / 加标签 / 裁剪 / 圆角 / 缩放, stitch / combine / collage / contact sheet / side-by-side / before-after / watermark / label / crop / resize. The mechanical test: if the images do not exist as files yet, this is NOT the skill. Do NOT trigger for generating NEW images, INCLUDING when the request names a layout word ('生成一张九宫格的图' is one generated picture); documents (document skill); Xiaohongshu cards (talos-xhs-ops); or upscaling / background removal, which need a model."
 license: Proprietary. LICENSE.txt has complete terms
 ---