html-report-stable-base

Files (44)

• plugin.json · .codex-plugin/
• .gitignore
• LICENSE
• README.md
• README.zh-CN.md
• SKILL.md
• openai.yaml · agents/
• ppt-example.svg · assets/examples/
• single-page-example.svg · assets/examples/
• echarts.min.js · assets/template/assets/
• logo-deepseek.png · assets/template/assets/
• logo-doubao.png · assets/template/assets/
• logo-qianwen.png · assets/template/assets/
• logo-wenxin.png · assets/template/assets/
• html-report-ppt-base.html · assets/template/
• html-report-single-base.html · assets/template/
• report-editor.css · assets/template/shared/
• report-editor.js · assets/template/shared/
• 2026-08-24-stable-name-migration.md · docs/superpowers/plans/
• 2026-08-26-ppt-safe-performance.md · docs/superpowers/plans/
• 2026-08-26-pptx-json-contract-v2.md · docs/superpowers/plans/
• 2026-08-24-stable-name-migration.md · docs/superpowers/specs/
• 2026-08-26-pptx-json-contract-v2.md · docs/superpowers/specs/
• editor-contract-ppt.json · fixtures/
• editor-contract-single.json · fixtures/
• liby-pptx-json-v2-test.json · fixtures/
• single-page-demo.json · fixtures/
• package-lock.json
• package.json
• drawer-contract.md · references/
• existing-html-adaptation.md · references/
• requirements.txt
• bootstrap_html_report_deps.mjs · scripts/
• build_html_report_from_model.py · scripts/
• check_html_report.py · scripts/
• export_html_report.py · scripts/
• export_single_page_long.mjs · scripts/
• qa_editor_enhancements.mjs · scripts/
• qa_html_report.mjs · scripts/
• qa_preview_export.mjs · scripts/
• start_html_report_preview.mjs · scripts/
• test_editable_pptx_export.py · scripts/
• test_pptx_contract_v2.py · scripts/
• test_report_modes.py · scripts/

SKILL.md (first lines)

# HTML Report

## Purpose

Provide a content-neutral HTML report foundation. The calling skill, existing report, model, or user owns the topic, outline, copy, page count, colors, charts, images, and analysis. Template demo content is disposable and must never be treated as recommended report content or visual direction.

## Confirm The Mode First

Every new report must explicitly use one mode:

- `single-page`: one vertically scrolling, fluid HTML report. It supports editing, standalone HTML export, and click-triggered long PNG / one-page long PDF export through the local preview service.
- `ppt`: a slide deck with a fixed `1440 × 810` canvas, navigation, optional adaptive browsing, `html-pptx-data`, and click-triggered PNG/PDF/PPTX export through the local preview service. The PNG button exports one image per `.slide`; the PDF button exports the current edited browser snapshot, with each `.slide` captured as one PDF page.

If the calling skill or model already declares the mode, use it. Otherwise ask the calling skill or user before generating files. Do not infer or default the mode.

## Shared Editing Contract

Both modes must keep:

- a compact bottom-right gear and right-side drawer; drawer width is `320px` and the label column stays compact so inputs remain usable;
- drawer control groups as collapsed accordion sections by default, with one visible section open at a time; both modes use task-oriented common groups named `浏览与模式`, `全局样式`, `对象编辑`, and `图表数据`; PPT mode also includes `表格设置`; both modes include a visually distinct fixed `修复识别` repair group above the `导出` footer;
- each drawer group must include a short help sentence that explains when to use it;
- an explicit edit-mode toggle;
- global font family, L1/L2/L3/L4/metric/body/note sizes, body line-height, and table padding controls; the font-family control is a multiline textarea so long fallback stacks are editable; L-levels map to HTML headings but avoid confusion with HTML tags. Use direct numeric inputs without `min`/`max`, not sliders;
- typography level badges shown in edit mode sit just outside each element's top-right corner, so the badge names the selected text level without covering the content box;
- before editing or opening the drawer, global typography inputs must refresh from the currently rendered page values. For example, if the visible L1 element computes to `62px` while the template default is `60`, the L1 input must show `62` and user changes must start from `62`;
- metric values such as `.metric .value`, `.metric strong`, or `[data-ppt-level="metric"]` follow `--metric-size`; labels and descriptions inside metric cards remain body text;
- direct text editing only while edit mode is enabled;
- per-element selection and independent inline styles;
- `表格设置` and `图表数据` are separate context-aware groups: table controls are disabled until a table column/cell is selected or a table is manually recognized, while chart controls are disabled until an ECharts chart is selected or manually recognized; neither group is available while editing ordinary text, shape, or image elements;
- color controls pair the native color swatch with a HEX text field that accepts pasted `#RGB` or `#RRGGBB` values;
- a selected-element panel with a delete command, plus lightweight reset commands for global typography, dimensions, text styles, and box styles;
- a manual recognition module in both `ppt` and `single-page` modes so users can select an unrecognized page element and mark it as text, shape, chart, image, or table; keep this module in the fixed repair area rather than mixed into common drawer controls;
- recognizable icons for every drawer module;
- a compact, low-contrast footer line at the bottom with the GitHub project link `https://github.com/Lucas-Fong/html-report-stable-base`, author `Lucas Fong`, `MIT License`, and `© 2026`, without repeating the same author/copyright text;
- ECharts canvas rendering when supplied content includes charts.

Mark independently editable elements with exactly one type:

```html
<h2 class="editable" data-editable-element="text">Title</h2>
<div data-editable-element="shape">Card</div>
<div class="chart" data-editable-element="chart"></div>
<img data-editable-element="image" src="..." alt="...">
```

Supported independent controls:

| Type | Controls |
|---|---|
| `text` | width, height, font size, color, weight, alignment, line-height, background, border color/width, radius |
| `shape` | width, height, fill, border color/width, radius |
| `chart` | width and height; call the ECharts instance `resize()` after changes; ECharts data JSON editor for `categories` / `series` and advanced `{ "option": {...} }` updates |
| `image` | width and height; after choosing a local replacement for the selected real `<img>`, open a crop step whose frame matches the image's rendered aspect ratio; apply the cropped result as an inline data URL while preserving the target's object-fit/aspect behavior in standalone HTML and exports |

Only one element may be selected. Independent styles are written inline and override global variables only for that element. Width edits must work for inline text, flex children, and elements constrained by `max-width`; the editor may set `display:inline-block`, a matching flex basis, and `max-width:none` on the selected element. Do not add free dragging or absolute-position controls.

Read `references/drawer-contract.md` when creating or adapting a template.

When adapting an existing HTML report and the user asks to preserve the style, also read `references/existing-html-adaptation.md` before generating the model.

## Model Contract

Use `scripts/build_html_report_from_model.py`. The top-level `mode` is required.

For `ppt`, keep the existing `slides` model and structured `objects`:

```json
{"mode":"ppt","title":"Deck","slides":[{"title":"Page 1","html":"...","objects":[]}]}
```

For `single-page`, use sections without PPTX objects:

```json
{"mode":"single-page","title":"Report","sections":[{"id":"overview","title":"Overview","html":"..."}]}
```

Each section may include optional `id`, `title`, and `class`; `html` is required. The builder must reject a missing or invalid mode rather than choosing one.

## Bundled Asset Skills

The plugin distribution also bundles two independent helper skills under `skills/`:

- `skills/echarts-charts`: use when supplied report data needs a standalone ECharts HTML chart, an ECharts `option`, or an embeddable chart asset.
- `skills/generate-word-clouds`: use when supplied keyword/weight data needs one or more horizontal PNG word clouds.

When a report needs these assets, read the bundled helper skill first and resolve its `scripts/` and `references/` paths relative to that helper skill directory. Insert generated chart HTML/options or PNG files into the HTML report model only after the helper output exists.

For a fresh environment, run `node <skill-root>/scripts/bootstrap_html_report_deps.mjs` before browser export, browser QA, PPTX export, or word-cloud generation if Node/Python dependencies or Chromium are missing. The bootstrap installs Node dependencies, creates `<skill-root>/.venv` for Python dependencies, and installs Playwright Chromium for this plugin. If the system `python` lacks dependencies after bootstrapping, use `<skill-root>/.venv/bin/python` for Python commands.

## Visual Examples

Use these visuals as orientation for authors who are applying the skill to new content or adapting an existing report. They are examples of the shell and interaction pattern only; do not copy their dummy content into a report.

### Single-Page Report

![Single-page editable report shell](assets/examples/single-page-example.svg)

Use this pattern when the output should read as a long, vertically scrolling report: a hero or opening section, repeated content sections, optional side section navigation, and a right-side style drawer. Keep the report in normal document flow and let section height expand with the content.

Minimal model:

```json
{
  "mode": "single-page",
  "title": "Market Audit",
  "sections": [
    {
      "id": "summary",
      "title": "Executive Summary",
      "html": "<h1 class=\"editable\" data-editable-element=\"text\">Executive Summary</h1><p class=\"editable\" data-editable-element=\"text\">...</p>"
    }
  ]
}
```

### PPT Report

![PPT editable report shell](assets/examples/ppt-example.svg)

From Lucas-Fong/html-report-stable-base, MIT.

More from Lucas-Fong/html-report-stable-base