alran 0.0.0-stage → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ALRAN_TOOLS_NOTICES.md +64 -0
- package/LICENSE +27 -0
- package/LICENSE-STATUS.md +21 -0
- package/NOTICE +6 -0
- package/README.md +289 -2
- package/THIRD_PARTY_NOTICES.md +113 -0
- package/alran-tools.js +3 -0
- package/assets/agents/_default/prompt-auto_classifier.md +185 -0
- package/assets/agents/_default/prompt-auto_classifier_extras.md +17 -0
- package/assets/agents/_default/prompt-base-all.md +133 -0
- package/assets/agents/_default/prompt-base-all.md.hbs +228 -0
- package/assets/agents/_default/prompt-base-windows.md +5 -0
- package/assets/agents/_default/prompt-base-windows.md.hbs +5 -0
- package/assets/agents/_default/prompt-base-worker.md +10 -0
- package/assets/agents/_default/prompt-base-worker.md.hbs +27 -0
- package/assets/agents/_default/prompt-compact.md +76 -0
- package/assets/agents/_default/prompt-compact_continue.md +9 -0
- package/assets/agents/_default/prompt-git.md +8 -0
- package/assets/agents/_default/prompt-goal.md +13 -0
- package/assets/agents/_default/prompt-session-branch.md +3 -0
- package/assets/agents/_default/prompt-session-branch.md.hbs +30 -0
- package/assets/agents/_default/prompt-session-root.md +3 -0
- package/assets/agents/_default/prompt-session-root.md.hbs +32 -0
- package/assets/agents/_default/prompt-title.md +11 -0
- package/assets/agents/_default/prompt-tool_agent.md +22 -0
- package/assets/agents/_migration/README.md +20 -0
- package/assets/agents/_migration/coder/PERSONA.md +11 -0
- package/assets/agents/_migration/coder/system-prompt.md.hbs +42 -0
- package/assets/agents/_migration/general/PERSONA.md +11 -0
- package/assets/agents/_migration/general/system-prompt.md.hbs +49 -0
- package/assets/agents/_v2/AGENT_CONTEXT.md.hbs +245 -0
- package/assets/agents/_v2/PTC_TOOL_CALLS.md.hbs +35 -0
- package/assets/agents/_v2/coding/SYSTEM.md.hbs +173 -0
- package/assets/agents/_v2/explore.md.hbs +38 -0
- package/assets/agents/_v2/tui/SYSTEM.md.hbs +211 -0
- package/assets/agents/_v2/verifier.md.hbs +32 -0
- package/assets/agents/_v2/work/SYSTEM.md.hbs +186 -0
- package/assets/agents/_v2/worker.md.hbs +27 -0
- package/assets/agents/alran/PERSONA.md +7 -0
- package/assets/agents/alran/features/cron.md.hbs +0 -0
- package/assets/agents/alran/features/delegation.md.hbs +56 -0
- package/assets/agents/alran/features/memory.md.hbs +61 -0
- package/assets/agents/alran/features/recoverable-deletion.md.hbs +10 -0
- package/assets/agents/alran/features/task-management.md.hbs +11 -0
- package/assets/agents/alran/features/web-search.md.hbs +11 -0
- package/assets/agents/alran/modes/coding/online/PERSONA.md.hbs +20 -0
- package/assets/agents/alran/modes/coding/online/SYSTEM.md.hbs +158 -0
- package/assets/agents/alran/modes/work/online/PERSONA.md.hbs +20 -0
- package/assets/agents/alran/modes/work/online/SYSTEM.md.hbs +160 -0
- package/assets/agents/alran/prompt-session-root.md +4 -0
- package/assets/agents/alran/prompt-session-root.md.hbs +4 -0
- package/assets/agents/alran/skills/alran-code-product/SKILL.md +72 -0
- package/assets/agents/alran/skills/alran-code-product/references/account-models.md +61 -0
- package/assets/agents/alran/skills/alran-code-product/references/agents.md +34 -0
- package/assets/agents/alran/skills/alran-code-product/references/extensions.md +46 -0
- package/assets/agents/alran/skills/alran-code-product/references/workflows.md +56 -0
- package/assets/agents/alran/skills/control-in-app-browser/SKILL.md +590 -0
- package/assets/agents/alran/system-prompt.md.hbs +97 -0
- package/assets/agents/builtin-agents.json +1 -0
- package/assets/agents/desktop-task/archive-title/system-en.md +1 -0
- package/assets/agents/desktop-task/checkpoint/system.md +19 -0
- package/assets/agents/desktop-task/output-revision/system.md +1 -0
- package/assets/agents/desktop-task/retry/continuation.md +4 -0
- package/assets/agents/desktop-task/session-title/system.md +41 -0
- package/assets/agents/explore/PERSONA.md +8 -0
- package/assets/agents/explore/agent.md +14 -0
- package/assets/agents/explore/system-prompt.md.hbs +35 -0
- package/assets/agents/greeting.md +61 -0
- package/assets/agents/managed-prompts.json +47 -0
- package/assets/agents/prompt-exemptions.json +36 -0
- package/assets/agents/verifier/PERSONA.md +8 -0
- package/assets/agents/verifier/agent.md +17 -0
- package/assets/agents/verifier/system-prompt.md.hbs +28 -0
- package/assets/agents/worker/PERSONA.md +8 -0
- package/assets/agents/worker/agent.md +18 -0
- package/assets/agents/worker/system-prompt.md.hbs +22 -0
- package/assets/agents/workflow/code-review/review-candidates.md +120 -0
- package/assets/agents/workflow/code-review/reviewer-system.md +75 -0
- package/assets/agents/workflow/goal/budget-limit.md +16 -0
- package/assets/agents/workflow/goal/continuation.md +62 -0
- package/assets/agents/workflow/goal/objective-updated.md +16 -0
- package/assets/agents/workflow/goal/recovery-terminal-audit.md +13 -0
- package/assets/agents/workflow/goal/recovery.md +11 -0
- package/assets/agents/workflow/goal/terminal-audit.md +10 -0
- package/assets/agents/workflow/plan-mode/agent-entry.md +72 -0
- package/assets/agents/workflow/prompt-hook/system.md +0 -0
- package/assets/models-dev-catalog.json.gz +0 -0
- package/assets/prompts/code-review/review-candidates.md +120 -0
- package/assets/prompts/code-review/reviewer-system.md +75 -0
- package/assets/skills/alran-tools-master/SKILL.md +127 -0
- package/assets/skills/code-review/SKILL.md +51 -0
- package/assets/skills/cu-desktop/SKILL.md +255 -0
- package/assets/skills/deep-research/SKILL.md +30 -0
- package/assets/skills/deploy-website/SKILL.md +52 -0
- package/assets/skills/docx/LICENSE +21 -0
- package/assets/skills/docx/SKILL.md +259 -0
- package/assets/skills/docx/assets/styles/academic_styles.xml +250 -0
- package/assets/skills/docx/assets/styles/corporate_styles.xml +284 -0
- package/assets/skills/docx/assets/styles/default_styles.xml +449 -0
- package/assets/skills/docx/assets/xsd/aesthetic-rules.xsd +470 -0
- package/assets/skills/docx/assets/xsd/business-rules.xsd +130 -0
- package/assets/skills/docx/assets/xsd/common-types.xsd +159 -0
- package/assets/skills/docx/assets/xsd/wml-subset.xsd +589 -0
- package/assets/skills/docx/docs/acceptance-checklists/create.md +7 -0
- package/assets/skills/docx/docs/acceptance-checklists/edit.md +6 -0
- package/assets/skills/docx/docs/acceptance-checklists/layout-repair.md +7 -0
- package/assets/skills/docx/docs/acceptance-checklists/template.md +6 -0
- package/assets/skills/docx/docs/acceptance.md +139 -0
- package/assets/skills/docx/docs/anti-patterns.md +14 -0
- package/assets/skills/docx/docs/backends.md +116 -0
- package/assets/skills/docx/docs/evidence.md +73 -0
- package/assets/skills/docx/docs/failure-taxonomy.md +71 -0
- package/assets/skills/docx/docs/index.md +50 -0
- package/assets/skills/docx/docs/rendered-delivery.md +125 -0
- package/assets/skills/docx/docs/router.md +122 -0
- package/assets/skills/docx/docs/tables-and-numbering.md +27 -0
- package/assets/skills/docx/docs/task-apply-template.md +141 -0
- package/assets/skills/docx/docs/task-compare-two-docx.md +48 -0
- package/assets/skills/docx/docs/task-create.md +124 -0
- package/assets/skills/docx/docs/task-edit-fill.md +69 -0
- package/assets/skills/docx/docs/task-read-content.md +148 -0
- package/assets/skills/docx/docs/task-read-rendered.md +78 -0
- package/assets/skills/docx/docs/task-read-structure.md +93 -0
- package/assets/skills/docx/docs/task-repair-layout.md +70 -0
- package/assets/skills/docx/docs/template-dsl.md +32 -0
- package/assets/skills/docx/docs/track-changes.md +15 -0
- package/assets/skills/docx/docs/xml-patch-dsl.md +33 -0
- package/assets/skills/docx/references/cjk_typography.md +357 -0
- package/assets/skills/docx/references/cjk_university_template_guide.md +184 -0
- package/assets/skills/docx/references/comments_guide.md +191 -0
- package/assets/skills/docx/references/design_good_bad_examples.md +829 -0
- package/assets/skills/docx/references/design_principles.md +819 -0
- package/assets/skills/docx/references/openxml_element_order.md +308 -0
- package/assets/skills/docx/references/openxml_encyclopedia_part1.md +4061 -0
- package/assets/skills/docx/references/openxml_encyclopedia_part2.md +2820 -0
- package/assets/skills/docx/references/openxml_encyclopedia_part3.md +3381 -0
- package/assets/skills/docx/references/openxml_namespaces.md +82 -0
- package/assets/skills/docx/references/openxml_units.md +72 -0
- package/assets/skills/docx/references/sample-patch-plans.json +22 -0
- package/assets/skills/docx/references/sample-task-intents.json +5 -0
- package/assets/skills/docx/references/sample-template-manifests.json +21 -0
- package/assets/skills/docx/references/scenario_a_create.md +284 -0
- package/assets/skills/docx/references/scenario_b_edit_content.md +295 -0
- package/assets/skills/docx/references/scenario_c_apply_template.md +456 -0
- package/assets/skills/docx/references/track_changes_guide.md +200 -0
- package/assets/skills/docx/references/troubleshooting.md +506 -0
- package/assets/skills/docx/references/typography_guide.md +294 -0
- package/assets/skills/docx/references/xsd_validation_guide.md +158 -0
- package/assets/skills/docx/scripts/build_patch_plan.py +29 -0
- package/assets/skills/docx/scripts/diff_docx_structure.py +61 -0
- package/assets/skills/docx/scripts/doc_to_docx.ps1 +85 -0
- package/assets/skills/docx/scripts/doc_to_docx.sh +40 -0
- package/assets/skills/docx/scripts/docx_preview.ps1 +76 -0
- package/assets/skills/docx/scripts/docx_preview.sh +37 -0
- package/assets/skills/docx/scripts/docx_to_pdf.py +87 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/AlranAIDocx.Cli.csproj +19 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/Program.cs +18 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/AlranAIDocx.Core.csproj +15 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/AnalyzeCommand.cs +147 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ApplyTemplateCommand.cs +322 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/CreateCommand.cs +324 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/DiffCommand.cs +155 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/EditContentCommand.cs +487 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/FixOrderCommand.cs +108 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/MergeRunsCommand.cs +122 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ValidateCommand.cs +107 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/CommentSynchronizer.cs +169 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/ElementOrder.cs +80 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/NamespaceConstants.cs +42 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/RunMerger.cs +81 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/StyleAnalyzer.cs +81 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/TrackChangesHelper.cs +99 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/UnitConverter.cs +23 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples.cs +1832 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch1.cs +910 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch2.cs +999 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch3.cs +1048 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch4.cs +1038 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/CharacterFormattingSamples.cs +1020 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/DocumentCreationSamples.cs +1121 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FieldAndTocSamples.cs +624 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FootnoteAndCommentSamples.cs +675 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/HeaderFooterSamples.cs +838 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ImageSamples.cs +917 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ListAndNumberingSamples.cs +826 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ParagraphFormattingSamples.cs +1199 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/StyleSystemSamples.cs +1487 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TableSamples.cs +1163 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TrackChangesSamples.cs +595 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/CjkHelper.cs +39 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/FontDefaults.cs +24 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/PageSizes.cs +20 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/BusinessRuleValidator.cs +224 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/GateCheckValidator.cs +148 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/ValidationResult.cs +23 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/XsdValidator.cs +69 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.slnx +4 -0
- package/assets/skills/docx/scripts/env_check.ps1 +327 -0
- package/assets/skills/docx/scripts/env_check.sh +340 -0
- package/assets/skills/docx/scripts/extract_docx_text.py +1075 -0
- package/assets/skills/docx/scripts/pack_docx.py +31 -0
- package/assets/skills/docx/scripts/read_docx_structure.py +1032 -0
- package/assets/skills/docx/scripts/render_docx_pages.py +147 -0
- package/assets/skills/docx/scripts/rendered_report.py +609 -0
- package/assets/skills/docx/scripts/setup.ps1 +542 -0
- package/assets/skills/docx/scripts/setup.sh +537 -0
- package/assets/skills/docx/scripts/unpack_docx.py +29 -0
- package/assets/skills/docx/scripts/validate_template_manifest.py +60 -0
- package/assets/skills/docx/scripts/verify_anchor_atomicity.py +87 -0
- package/assets/skills/edit-deployed-website/SKILL.md +27 -0
- package/assets/skills/init/SKILL.md +135 -0
- package/assets/skills/llm-call/SKILL.md +48 -0
- package/assets/skills/llm-call/scripts/llm_call.py +458 -0
- package/assets/skills/pdf/SKILL.md +280 -0
- package/assets/skills/pdf/docs/advanced-reference.md +711 -0
- package/assets/skills/pdf/docs/create-guide.md +437 -0
- package/assets/skills/pdf/docs/design-guide.md +204 -0
- package/assets/skills/pdf/docs/forms-guide.md +462 -0
- package/assets/skills/pdf/docs/html-pdf-spec.md +500 -0
- package/assets/skills/pdf/docs/latex-academic-thesis-guide.md +233 -0
- package/assets/skills/pdf/docs/latex-technical-book-guide.md +112 -0
- package/assets/skills/pdf/docs/pitfalls-index.md +792 -0
- package/assets/skills/pdf/docs/read-guide.md +358 -0
- package/assets/skills/pdf/docs/reformat-guide.md +238 -0
- package/assets/skills/pdf/docs/skill-readme-archive.md +151 -0
- package/assets/skills/pdf/docs/troubleshooting.md +86 -0
- package/assets/skills/pdf/docs/vision-guide.md +188 -0
- package/assets/skills/pdf/scripts/__init__.py +0 -0
- package/assets/skills/pdf/scripts/_pdf_read_lib.py +284 -0
- package/assets/skills/pdf/scripts/fill/__init__.py +0 -0
- package/assets/skills/pdf/scripts/fill/acroform_apply.py +153 -0
- package/assets/skills/pdf/scripts/fill/overlay_apply.py +109 -0
- package/assets/skills/pdf/scripts/lib/__init__.py +0 -0
- package/assets/skills/pdf/scripts/lib/acroform_io.py +170 -0
- package/assets/skills/pdf/scripts/lib/cli_utils.py +41 -0
- package/assets/skills/pdf/scripts/lib/geometry.py +79 -0
- package/assets/skills/pdf/scripts/make.sh +388 -0
- package/assets/skills/pdf/scripts/merge.py +112 -0
- package/assets/skills/pdf/scripts/pdf_inspect/__init__.py +0 -0
- package/assets/skills/pdf/scripts/pdf_inspect/acroform_inspect.py +52 -0
- package/assets/skills/pdf/scripts/pdf_inspect/acroform_probe.py +57 -0
- package/assets/skills/pdf/scripts/pdf_inspect/layout_scan.py +164 -0
- package/assets/skills/pdf/scripts/read_pdf_vision.py +473 -0
- package/assets/skills/pdf/scripts/reformat_parse.py +181 -0
- package/assets/skills/pdf/scripts/render/__init__.py +0 -0
- package/assets/skills/pdf/scripts/render/overlay_preview.py +86 -0
- package/assets/skills/pdf/scripts/render/page_rasterize.py +85 -0
- package/assets/skills/pdf/scripts/render_html.cjs +205 -0
- package/assets/skills/pdf/scripts/validate/__init__.py +0 -0
- package/assets/skills/pdf/scripts/validate/geometry_lint.py +124 -0
- package/assets/skills/pdf/templates/INDEX.md +90 -0
- package/assets/skills/pdf/templates/bilingual-menu-premium/README.md +175 -0
- package/assets/skills/pdf/templates/bilingual-menu-premium/skeleton.html +343 -0
- package/assets/skills/pdf/templates/brand-guide-2page/README.md +140 -0
- package/assets/skills/pdf/templates/brand-guide-2page/skeleton.html +264 -0
- package/assets/skills/pdf/templates/data-viz-report/README.md +234 -0
- package/assets/skills/pdf/templates/data-viz-report/skeleton.html +835 -0
- package/assets/skills/pdf/templates/form-fill-acroform/README.md +195 -0
- package/assets/skills/pdf/templates/form-fill-acroform/field_values.template.json +118 -0
- package/assets/skills/pdf/templates/latex-academic-thesis/README.md +146 -0
- package/assets/skills/pdf/templates/latex-academic-thesis/source.tex +334 -0
- package/assets/skills/pdf/templates/latex-technical-book/README.md +130 -0
- package/assets/skills/pdf/templates/latex-technical-book/README.template-source.md +62 -0
- package/assets/skills/pdf/templates/latex-technical-book/source.tex +439 -0
- package/assets/skills/pdf/templates/multi-article-aggregator/README.md +148 -0
- package/assets/skills/pdf/templates/multi-article-aggregator/pipeline.md +223 -0
- package/assets/skills/pdf/templates/multilang-research-report/README.md +136 -0
- package/assets/skills/pdf/templates/multilang-research-report/skeleton.html +242 -0
- package/assets/skills/pdf/templates/reformat-default/README.md +136 -0
- package/assets/skills/pdf/templates/reformat-default/skeleton.html +204 -0
- package/assets/skills/pdf/templates/translate-preserve-layout/README.md +136 -0
- package/assets/skills/pdf/templates/translate-preserve-layout/skeleton.html +96 -0
- package/assets/skills/pdf/templates/translate-preserve-layout/terminology.template.json +66 -0
- package/assets/skills/pptx/SKILL.md +283 -0
- package/assets/skills/pptx/references/design-system.md +424 -0
- package/assets/skills/pptx/references/editing.md +162 -0
- package/assets/skills/pptx/references/element-map.md +229 -0
- package/assets/skills/pptx/references/pitfalls.md +205 -0
- package/assets/skills/pptx/references/pptxgenjs.md +420 -0
- package/assets/skills/pptx/references/preview-selection-writeback.md +65 -0
- package/assets/skills/pptx/references/python-pptx-recipes.md +63 -0
- package/assets/skills/pptx/references/slide-types.md +413 -0
- package/assets/skills/pptx/scripts/alran-ppt-map.cjs +280 -0
- package/assets/skills/pptx/scripts/audit_pptx.py +708 -0
- package/assets/skills/pptx/scripts/extract_comments.py +468 -0
- package/assets/skills/pptx/scripts/extract_images.py +226 -0
- package/assets/skills/pptx/scripts/extract_pptx.py +285 -0
- package/assets/skills/pptx/scripts/pdf2png.swift +203 -0
- package/assets/skills/pptx/scripts/pptx-screenshot.sh +105 -0
- package/assets/skills/resume-codex/SKILL.md +53 -0
- package/assets/skills/resume-codex/scripts/session-reader.mjs +445 -0
- package/assets/skills/skill-creator/SKILL.md +188 -0
- package/assets/skills/skill-creator/references/anti-patterns.md +149 -0
- package/assets/skills/skill-creator/references/commands-macos-linux.md +38 -0
- package/assets/skills/skill-creator/references/commands-windows-powershell.md +48 -0
- package/assets/skills/skill-creator/references/description-rubric.md +83 -0
- package/assets/skills/skill-creator/references/skill-template.md +101 -0
- package/assets/skills/skill-creator/references/when-to-bundle-scripts.md +139 -0
- package/assets/skills/skill-creator/scripts/lint-skill.js +226 -0
- package/assets/skills/skill-refiner/SKILL.md +137 -0
- package/assets/skills/visual-page/SKILL.md +194 -0
- package/assets/skills/x-link-reader/SKILL.md +108 -0
- package/assets/skills/xlsx/SKILL.md +498 -0
- package/assets/skills/xlsx/docs/advanced-reference.md +410 -0
- package/assets/skills/xlsx/docs/conventions-guide.md +217 -0
- package/assets/skills/xlsx/docs/create-edit-guide.md +410 -0
- package/assets/skills/xlsx/docs/pitfalls-index.md +759 -0
- package/assets/skills/xlsx/docs/raw-xml-escape-hatch.md +201 -0
- package/assets/skills/xlsx/docs/recalc-guide.md +295 -0
- package/assets/skills/xlsx/scripts/office/helpers/__init__.py +0 -0
- package/assets/skills/xlsx/scripts/office/helpers/merge_runs.py +199 -0
- package/assets/skills/xlsx/scripts/office/helpers/simplify_redlines.py +197 -0
- package/assets/skills/xlsx/scripts/office/pack.py +159 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd +1499 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd +146 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd +1085 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd +11 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd +3081 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd +23 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd +185 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd +287 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd +1676 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd +28 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd +144 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd +174 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd +25 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd +18 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd +59 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd +56 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd +195 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd +582 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd +25 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd +4439 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd +570 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd +509 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd +12 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd +108 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd +96 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd +3646 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd +116 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd +42 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd +50 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd +49 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd +33 -0
- package/assets/skills/xlsx/scripts/office/schemas/mce/mc.xsd +75 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2010.xsd +560 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2012.xsd +67 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2018.xsd +14 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cex-2018.xsd +20 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cid-2016.xsd +13 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd +4 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-symex-2015.xsd +8 -0
- package/assets/skills/xlsx/scripts/office/soffice.py +191 -0
- package/assets/skills/xlsx/scripts/office/unpack.py +132 -0
- package/assets/skills/xlsx/scripts/office/validate.py +117 -0
- package/assets/skills/xlsx/scripts/office/validators/__init__.py +15 -0
- package/assets/skills/xlsx/scripts/office/validators/base.py +851 -0
- package/assets/skills/xlsx/scripts/office/validators/docx.py +446 -0
- package/assets/skills/xlsx/scripts/office/validators/pptx.py +275 -0
- package/assets/skills/xlsx/scripts/office/validators/redlining.py +247 -0
- package/assets/skills/xlsx/scripts/recalc.py +450 -0
- package/chunks/account-commands-JZ6NXTTK.js +2 -0
- package/chunks/anthropic-MN33DP4E.js +2 -0
- package/chunks/application-ITGAJ4HC.js +2 -0
- package/chunks/auth-command-V3RVPLZO.js +2 -0
- package/chunks/azure-openai-responses-OWHMUNKC.js +2 -0
- package/chunks/chunk-2TF6JAQM.js +2 -0
- package/chunks/chunk-33CNY6GP.js +2 -0
- package/chunks/chunk-3AODGLMF.js +2 -0
- package/chunks/chunk-44VPC5LA.js +38 -0
- package/chunks/chunk-4CN3IJFH.js +2 -0
- package/chunks/chunk-4PDIO3M6.js +2 -0
- package/chunks/chunk-4X22UJQH.js +164 -0
- package/chunks/chunk-6255CZPL.js +2 -0
- package/chunks/chunk-6P4UKHGR.js +2 -0
- package/chunks/chunk-7QLAXRD2.js +1085 -0
- package/chunks/chunk-7XYOYZX2.js +2 -0
- package/chunks/chunk-A7GMJNA2.js +29 -0
- package/chunks/chunk-AGUSPIUP.js +2 -0
- package/chunks/chunk-BQ3CF3KE.js +2 -0
- package/chunks/chunk-C3CMJAAV.js +3 -0
- package/chunks/chunk-CJM7ZJ6W.js +7 -0
- package/chunks/chunk-CSOUJVKM.js +2 -0
- package/chunks/chunk-D66ZSHXR.js +2 -0
- package/chunks/chunk-D7MGU75P.js +2 -0
- package/chunks/chunk-E3GLGDGC.js +5 -0
- package/chunks/chunk-ENHOPPS7.js +16 -0
- package/chunks/chunk-EOR6EDNR.js +2 -0
- package/chunks/chunk-EYK25HWR.js +2 -0
- package/chunks/chunk-F46IELF5.js +2 -0
- package/chunks/chunk-FC4M2B7E.js +2 -0
- package/chunks/chunk-FSNYOJPJ.js +2 -0
- package/chunks/chunk-FUERW2DW.js +3 -0
- package/chunks/chunk-FXOH6TEQ.js +21 -0
- package/chunks/chunk-GP52JZMY.js +2 -0
- package/chunks/chunk-GRXX6I72.js +2 -0
- package/chunks/chunk-GSYHBK5Q.js +6 -0
- package/chunks/chunk-HNWBFJNO.js +2 -0
- package/chunks/chunk-IIE366LR.js +6706 -0
- package/chunks/chunk-IWK7PZP7.js +207 -0
- package/chunks/chunk-J3KCPYZT.js +2 -0
- package/chunks/chunk-KCLRJQ53.js +59 -0
- package/chunks/chunk-LU4RPLJ3.js +2 -0
- package/chunks/chunk-LZJYNT32.js +2 -0
- package/chunks/chunk-M7GW4VMR.js +27 -0
- package/chunks/chunk-MACBL5HF.js +2 -0
- package/chunks/chunk-N5NTXCJI.js +2 -0
- package/chunks/chunk-N5SVBCUB.js +7 -0
- package/chunks/chunk-N6W7ZL26.js +2 -0
- package/chunks/chunk-NWB7LFOK.js +131 -0
- package/chunks/chunk-OIQ336YE.js +16 -0
- package/chunks/chunk-OQNU3VPS.js +30 -0
- package/chunks/chunk-OTDNOWXG.js +16 -0
- package/chunks/chunk-PNXZWSWT.js +3 -0
- package/chunks/chunk-QFUV5PX6.js +2 -0
- package/chunks/chunk-QIN5ZBE2.js +2 -0
- package/chunks/chunk-QKBN5CGI.js +2 -0
- package/chunks/chunk-QPGTKSIQ.js +2 -0
- package/chunks/chunk-SIOLUFGG.js +2 -0
- package/chunks/chunk-TW23QKAD.js +3 -0
- package/chunks/chunk-U3RMPDXU.js +2 -0
- package/chunks/chunk-U7U3DJHF.js +2 -0
- package/chunks/chunk-VLXX22YO.js +2 -0
- package/chunks/chunk-WHD2XVT2.js +2 -0
- package/chunks/chunk-WTAJMYF2.js +249 -0
- package/chunks/chunk-WWNUAU4P.js +29 -0
- package/chunks/chunk-WYANV3IX.js +4 -0
- package/chunks/chunk-XAGZ6ZEU.js +9 -0
- package/chunks/chunk-XFCC2CI2.js +24 -0
- package/chunks/chunk-XQK7JM66.js +2 -0
- package/chunks/chunk-YLQXZBEL.js +2 -0
- package/chunks/chunk-YPV2X2RG.js +2 -0
- package/chunks/chunk-Z6BHCXKT.js +25 -0
- package/chunks/chunk-Z6HBNJCA.js +8 -0
- package/chunks/chunk-ZQKVUPKA.js +2 -0
- package/chunks/chunk-ZQOALVGL.js +2 -0
- package/chunks/clipboard-image-PQPC4EHR.js +2 -0
- package/chunks/data-dir-LDVKDCJ2.js +2 -0
- package/chunks/dist-2BRD4JFU.js +11 -0
- package/chunks/dist-EXKHRFQO.js +5 -0
- package/chunks/emscripten-module-RD6P2XH5.js +2 -0
- package/chunks/emscripten-module-WYNDFH3N.js +2 -0
- package/chunks/emscripten-module-XPTEOIWW.js +2 -0
- package/chunks/emscripten-module-ZS3PMSDF.js +2 -0
- package/chunks/ffi-IO7WZQNG.js +2 -0
- package/chunks/ffi-M5UP5J6C.js +2 -0
- package/chunks/ffi-ORLOPBB3.js +2 -0
- package/chunks/ffi-OUPK6AY6.js +2 -0
- package/chunks/google-UJAPMFAB.js +2 -0
- package/chunks/google-vertex-VLSF55PW.js +2 -0
- package/chunks/install-source-JTIUC4G4.js +2 -0
- package/chunks/launcher-FCZ3EDBF.js +61 -0
- package/chunks/lifecycle-GY435YMF.js +2 -0
- package/chunks/main-TQGGRHTS.js +13 -0
- package/chunks/mistral-ZJZUEF2X.js +3 -0
- package/chunks/module-6F3E5H7Y-BN7QWGYB.js +2 -0
- package/chunks/module-asyncify-R6PWJ6ZV-P4FWSBAY.js +2 -0
- package/chunks/multipart-parser-L6M455MS.js +2 -0
- package/chunks/network-proxy-U72JCK2I.js +2 -0
- package/chunks/openai-codex-responses-FPCDNRL5.js +2 -0
- package/chunks/openai-completions-D32YW6KL.js +2 -0
- package/chunks/openai-responses-ZCGSENM4.js +2 -0
- package/chunks/openrouter-G2EHY5BD.js +2 -0
- package/chunks/otel-OHXIZ666.js +2 -0
- package/chunks/package-contract-GVXTMJ3N.js +2 -0
- package/chunks/pdfjs-SHZAF7PF.js +107 -0
- package/chunks/photon_rs-C52RL4CI.js +3 -0
- package/chunks/plugin-command-OSAFHS7C.js +2 -0
- package/chunks/provider-command-SKTCHD4E.js +2 -0
- package/chunks/questionnaire-bridge-ISQOCYWY.js +2 -0
- package/chunks/run-acp-command-SG2BDMFJ.js +2 -0
- package/chunks/run-exec-command-5ADSQR2Z.js +15 -0
- package/chunks/skills-command-XXXEZAG6.js +2 -0
- package/chunks/src-DNIDEMVV.js +2 -0
- package/chunks/src-IBHIRTD7.js +2 -0
- package/chunks/telemetry-J7ZLGF5X.js +2 -0
- package/chunks/telemetry-command-COQG2AKK.js +5 -0
- package/chunks/tools-WDBB2JKV.js +2 -0
- package/chunks/undici-TUGHZJSA.js +2 -0
- package/chunks/update-NB6OD572.js +14 -0
- package/chunks/update-hint-ED7O67WU.js +3 -0
- package/chunks/wechat-onboard-UWXQW2HT.js +2 -0
- package/cli.js +5 -0
- package/configs/data-minimal.yaml +50 -0
- package/embedded/alran-tools/cli.mjs +4961 -0
- package/embedded/alran-tools/manifest.json +25 -0
- package/emscripten-module.wasm +0 -0
- package/image-preview-worker.js +2 -0
- package/internal-bin/alran-tools +9 -0
- package/internal-bin/alran-tools.cmd +8 -0
- package/matrix-mcp-stdio.js +4 -0
- package/native/darwin/prebuilds/darwin-arm64/darwin-modifiers.node +0 -0
- package/native/darwin/prebuilds/darwin-x64/darwin-modifiers.node +0 -0
- package/native/win32/prebuilds/win32-arm64/win32-console-mode.node +0 -0
- package/native/win32/prebuilds/win32-x64/win32-console-mode.node +0 -0
- package/package.json +38 -4
- package/photon_rs_bg.wasm +0 -0
- package/quickjs-worker.js +152 -0
- package/vendor/java-proxy-agent/build.ts +97 -0
- package/vendor/java-proxy-agent/srt-proxy-agent.jar +0 -0
- package/vendor/seccomp/arm64/apply-seccomp +0 -0
- package/vendor/seccomp/build.ts +74 -0
- package/vendor/seccomp/x64/apply-seccomp +0 -0
- package/vendor/srt-win/arm64/srt-win.exe +0 -0
- package/vendor/srt-win/build.ts +40 -0
- package/vendor/srt-win/x64/srt-win.exe +0 -0
|
@@ -0,0 +1,500 @@
|
|
|
1
|
+
# HTML → PDF Spec
|
|
2
|
+
|
|
3
|
+
> The single source of truth for *how* a CREATE / REFORMAT HTML page must be
|
|
4
|
+
> authored so it survives Chromium's print snapshot. Every template's
|
|
5
|
+
> `skeleton.html` is wired up to follow this spec; if you write a fresh HTML
|
|
6
|
+
> from scratch, follow this checklist before invoking
|
|
7
|
+
> `bash make.sh render`.
|
|
8
|
+
|
|
9
|
+
The pipeline is fixed: **HTML (file or URL) → Playwright Chromium →
|
|
10
|
+
`page.pdf()`**, driven by [`scripts/render_html.cjs`](../scripts/render_html.cjs).
|
|
11
|
+
There is no token pipeline, no ReportLab, no LaTeX. If a primitive cannot be
|
|
12
|
+
expressed in HTML+CSS+JS, it does not belong in this skill.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 1. Page geometry
|
|
17
|
+
|
|
18
|
+
```css
|
|
19
|
+
@page { size: A4 portrait; margin: 14mm 12mm; } /* default for reports */
|
|
20
|
+
@page { size: A4 landscape; margin: 12mm 14mm; } /* dashboards / wide tables */
|
|
21
|
+
@page { size: Letter portrait; margin: 0.75in 0.6in; } /* US-only audience */
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
**A4 is the default — design every HTML against the A4 aspect ratio.**
|
|
25
|
+
The renderer (`render_html.cjs`) defaults to `--format A4`, and Chromium's
|
|
26
|
+
`page.pdf({ format: 'A4' })` *overrides* any CSS `@page { size: 8.5in 11in }`
|
|
27
|
+
you may have inherited from a web template. Mismatches between the CSS you
|
|
28
|
+
wrote-for and the format the renderer prints-to are the most common source
|
|
29
|
+
of "huge margins / clipped content / 16:9 layout that looks tiny on the
|
|
30
|
+
page" complaints.
|
|
31
|
+
|
|
32
|
+
Concrete numbers to design against (A4 portrait, 14×12 mm margins):
|
|
33
|
+
|
|
34
|
+
- Page size: **210 × 297 mm** (1 : 1.414 aspect ratio)
|
|
35
|
+
- Content area: **186 × 269 mm**
|
|
36
|
+
- Aspect ratio for full-bleed sections / hero blocks: **roughly 5 : 7**
|
|
37
|
+
(taller than your laptop screen — do not assume 16:9 or 4:3)
|
|
38
|
+
|
|
39
|
+
Hard rules:
|
|
40
|
+
|
|
41
|
+
- **Always declare `@page`.** Without it Chromium picks 8.5×11 with 1-inch
|
|
42
|
+
margins, and your layout drifts.
|
|
43
|
+
- **Don't write `8.5in 11in` or `Letter` unless the user is US-only.** It
|
|
44
|
+
will be silently overridden to A4 by the renderer's `--format A4`
|
|
45
|
+
default; the visual result is "your CSS thinks Letter, the PDF is A4"
|
|
46
|
+
and content overflows or gets cropped. Either author against A4 in CSS,
|
|
47
|
+
or pass `--format Letter` to the renderer to make CSS and PDF match.
|
|
48
|
+
- **Use `mm` / `in`, not `px`.** Pixels render at 96 DPI in Chromium and
|
|
49
|
+
look fine on screen but wrong in print. `vw` / `vh` / `100%` height
|
|
50
|
+
are also off-limits at the page level — you will get one "screen" per
|
|
51
|
+
page instead of A4 pages.
|
|
52
|
+
- The renderer accepts `--margin "14mm 12mm"` and `--format A4|Letter`;
|
|
53
|
+
CSS `@page` takes precedence over the CLI flags only when both are set.
|
|
54
|
+
- **Cover / full-bleed sections**: explicit `height: 268mm` (A4 portrait
|
|
55
|
+
297 − 2×14 mm − 1 mm bleed). For other margin schemes, recompute:
|
|
56
|
+
`height = 297 - top_margin - bottom_margin - 1mm`. Don't use `100vh` —
|
|
57
|
+
it expands with viewport, not with the printed page.
|
|
58
|
+
- **Charts / images** get `max-width: 100%` (relative to content area
|
|
59
|
+
186 mm, not viewport). Set explicit `mm` heights on `.chart-wrap`
|
|
60
|
+
rather than relying on `aspect-ratio` (Chromium's print pipeline
|
|
61
|
+
computes aspect-ratio from screen, then prints; the 1.414 page ratio
|
|
62
|
+
isn't applied).
|
|
63
|
+
|
|
64
|
+
### Screen-emulation block — make `open page.html` look like the PDF
|
|
65
|
+
|
|
66
|
+
The `@page` rule is **ignored on screen**, so opening the source HTML in
|
|
67
|
+
a browser shows one giant horizontal page that looks nothing like the
|
|
68
|
+
A4 PDF. **Every skeleton must include this `@media screen` block** so
|
|
69
|
+
the browser preview reads as a stack of A4 sheets — the agent (and the
|
|
70
|
+
human reviewer) gets the same geometry in both views, no surprise at
|
|
71
|
+
PDF time.
|
|
72
|
+
|
|
73
|
+
```css
|
|
74
|
+
@media screen {
|
|
75
|
+
html { background: #d0d0d0; }
|
|
76
|
+
body { margin: 0; padding: 20px 0; }
|
|
77
|
+
/* Each top-level <section> renders as one A4 sheet on screen */
|
|
78
|
+
body > section {
|
|
79
|
+
width: 210mm;
|
|
80
|
+
min-height: 297mm; /* full A4; cover's height: 268mm is overridden up */
|
|
81
|
+
margin: 0 auto 20px;
|
|
82
|
+
background: #fff;
|
|
83
|
+
box-shadow: 0 4px 24px rgba(0,0,0,0.18);
|
|
84
|
+
box-sizing: border-box;
|
|
85
|
+
overflow: hidden;
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Notes:
|
|
91
|
+
- The block is **screen-only**; `@page`, page-breaks, and Chromium's PDF
|
|
92
|
+
pipeline are unaffected.
|
|
93
|
+
- Sections that already have their own background (`.cover` linear-
|
|
94
|
+
gradient, dark conclusion blocks) keep their styling because class
|
|
95
|
+
selectors out-rank the type selector `body > section`.
|
|
96
|
+
- This is *visual* parity, not pixel-perfect — `page-break-inside: avoid`
|
|
97
|
+
and Chart.js render timing only run during PDF generation. For
|
|
98
|
+
pixel-perfect screen parity, opt in to a paged-media polyfill
|
|
99
|
+
([Paged.js](https://pagedjs.org/)); not required by default.
|
|
100
|
+
|
|
101
|
+
## 2. Universal print color fidelity
|
|
102
|
+
|
|
103
|
+
```css
|
|
104
|
+
* { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
- Apply to the **universal selector**, not just `body`. Gradient KPI cards,
|
|
108
|
+
cover gradients, and dark conclusion blocks all desaturate without this.
|
|
109
|
+
- The renderer defaults to `printBackground: true`. Pass `--no-print-background`
|
|
110
|
+
only when you want a transparent body (rare).
|
|
111
|
+
|
|
112
|
+
## 3. Page-break rules
|
|
113
|
+
|
|
114
|
+
### 3.1 Protect elements from being split
|
|
115
|
+
|
|
116
|
+
- Wrap every chart / large table / multi-column card in a container with
|
|
117
|
+
`page-break-inside: avoid` (use `.avoid-break { page-break-inside: avoid }`).
|
|
118
|
+
- Use `page-break-after: always` on a wrapper element to force a split (e.g.
|
|
119
|
+
cover page, end of a chapter). **Use sparingly** — every forced split is a
|
|
120
|
+
page that can become half-empty.
|
|
121
|
+
- Headings should declare `page-break-after: avoid` (don't strand a title at
|
|
122
|
+
the bottom of a page).
|
|
123
|
+
- **Never** use absolute positioning to "fix" a layout that overflows. Re-flow
|
|
124
|
+
with `flex` / `grid` and adjust the `mm` sizing.
|
|
125
|
+
|
|
126
|
+
### 3.2 Page balance — every page must be full (≥ 2/3)
|
|
127
|
+
|
|
128
|
+
A protected element (chart card, table, conclusion block) that doesn't fit
|
|
129
|
+
in the remaining space gets pushed to the next page, leaving a fat blank
|
|
130
|
+
gap above it. Same for `page-break-before: always` on a section that comes
|
|
131
|
+
right after a short subsection. **This is the #1 cause of "amateurish"
|
|
132
|
+
PDFs.** Inspect every page and fix any blank gap > 1/3 of the page height.
|
|
133
|
+
|
|
134
|
+
**Estimate before authoring.** Rough capacity for A4 portrait at 14×12 mm
|
|
135
|
+
margins, body 10.5 pt / line-height 1.55:
|
|
136
|
+
|
|
137
|
+
| Element | Vertical cost (approx.) |
|
|
138
|
+
| --- | --- |
|
|
139
|
+
| Section header (eyebrow + h2 + rule) | 28 mm |
|
|
140
|
+
| Lead paragraph (3 lines) | 18 mm |
|
|
141
|
+
| KPI 4-grid (one row) | 28 mm |
|
|
142
|
+
| Chart card (default `.chart-wrap`) | 100 mm |
|
|
143
|
+
| Chart card (`.tall`) | 130 mm |
|
|
144
|
+
| Data table (10 rows) | 70 mm |
|
|
145
|
+
| Insight callout (1 paragraph) | 18 mm |
|
|
146
|
+
| Recommend triple (3-up cards) | 70 mm |
|
|
147
|
+
| Versus pair (2-up cards) | 65 mm |
|
|
148
|
+
| Body line | ~5 mm |
|
|
149
|
+
|
|
150
|
+
A4 content height ≈ **268 mm** (297 − 2×14 mm margin). Add up the elements
|
|
151
|
+
on a page, check whether they fit. If a chart card (100 mm) lands on a page
|
|
152
|
+
that already has 200 mm filled, **don't let it spill** — either pull
|
|
153
|
+
something forward (a small insight / takeaway) to fill the gap on the
|
|
154
|
+
current page, or re-order so the chart card starts the next page.
|
|
155
|
+
|
|
156
|
+
**Three fixes when a page has > 1/3 blank** (from cheapest to most-invasive):
|
|
157
|
+
|
|
158
|
+
1. **Pull next-section content backward** into the current page. Small
|
|
159
|
+
primitives travel well: insight callouts, takeaway rows, a footer-meta
|
|
160
|
+
block, even one extra KPI card. Move them across the section boundary
|
|
161
|
+
(the visual section break still works because the H2 below is
|
|
162
|
+
unmistakable).
|
|
163
|
+
2. **Expand current-section content**. Lengthen the lead paragraph,
|
|
164
|
+
add a 4-row "key facts" mini-table, or split a single big chart into
|
|
165
|
+
two smaller ones (one "overview", one "detail").
|
|
166
|
+
3. **Re-order major elements** so a tall element doesn't get orphaned.
|
|
167
|
+
Move a long table before a chart card if the table fills the gap better.
|
|
168
|
+
|
|
169
|
+
**Three things you must NOT do**:
|
|
170
|
+
- ❌ Add `<br>` / ` ` / `.spacer { height: 50mm }` to fake fullness.
|
|
171
|
+
- ❌ Shrink page margins (`@page margin: 8mm`) to force-fit content.
|
|
172
|
+
- ❌ Inflate font-size / line-height purely to consume space.
|
|
173
|
+
|
|
174
|
+
**page-break-before discipline**: only `<h1>` / cover / chapter headers
|
|
175
|
+
should carry `page-break-before: always`. H2 and H3 must not — that's
|
|
176
|
+
how short subsections create huge gaps. Sections that flow naturally fill
|
|
177
|
+
better than sections that hard-split.
|
|
178
|
+
|
|
179
|
+
**The check is iterative**. After the first render, open the PDF and
|
|
180
|
+
look at every page bottom. Fix the worst gap, re-render, repeat. Don't
|
|
181
|
+
declare done until the worst-page-gap is ≤ 1/3.
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
### 3.3 Running headers and footers
|
|
185
|
+
|
|
186
|
+
Headers/footers are part of the document contract, not decoration. For any formal or multi-page output (contracts, proposals, reports, forms, manuals, translated documents), decide and implement them before the first serious render.
|
|
187
|
+
|
|
188
|
+
Decision rules:
|
|
189
|
+
|
|
190
|
+
- If the source document has headers/footers, preserve their text and placement unless the user asks for a redesign.
|
|
191
|
+
- If the source has no headers/footers but the output is formal and multi-page, add a conservative running header/footer: document title or section identity in the header, page number or classification/date in the footer.
|
|
192
|
+
- Keep cover/title pages clean unless the source explicitly has first-page headers/footers.
|
|
193
|
+
- If no header/footer is appropriate (poster, single-page certificate, full-bleed cover), state that decision in the delivery note.
|
|
194
|
+
|
|
195
|
+
Implementation pattern for hand-authored HTML:
|
|
196
|
+
|
|
197
|
+
```css
|
|
198
|
+
@page { size: A4 portrait; margin: 18mm 20mm; }
|
|
199
|
+
.page {
|
|
200
|
+
position: relative;
|
|
201
|
+
min-height: 261mm; /* 297 - top/bottom @page margins */
|
|
202
|
+
padding-top: 10mm; /* reserved header area */
|
|
203
|
+
padding-bottom: 12mm; /* reserved footer area */
|
|
204
|
+
break-after: page;
|
|
205
|
+
}
|
|
206
|
+
.cover { padding-top: 0; padding-bottom: 0; }
|
|
207
|
+
.running-header {
|
|
208
|
+
position: absolute; top: 0; left: 0; right: 0; height: 7mm;
|
|
209
|
+
border-bottom: 0.5pt solid #bdbdbd;
|
|
210
|
+
font-size: 8.5pt; color: #555; line-height: 7mm;
|
|
211
|
+
}
|
|
212
|
+
.running-header .left { float: left; }
|
|
213
|
+
.running-header .right { float: right; }
|
|
214
|
+
.running-footer {
|
|
215
|
+
position: absolute; bottom: 0; left: 0; right: 0; height: 8mm;
|
|
216
|
+
border-top: 0.5pt solid #bdbdbd;
|
|
217
|
+
font-size: 8.5pt; color: #555; line-height: 8mm; text-align: center;
|
|
218
|
+
}
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
```html
|
|
222
|
+
<section class="page">
|
|
223
|
+
<div class="running-header"><span class="left">Document title</span><span class="right">Section</span></div>
|
|
224
|
+
<!-- page content -->
|
|
225
|
+
<div class="running-footer">Page 1</div>
|
|
226
|
+
</section>
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Verification:
|
|
230
|
+
|
|
231
|
+
- Rasterize at least one body page and the last/signature/table-heavy page; confirm header/footer alignment and no overlap.
|
|
232
|
+
- `pdftotext` should expose running text/page numbers, but visual raster is the real gate.
|
|
233
|
+
- If a footer collides with a table/chart, increase `.page` bottom padding or split/reflow the protected element; do not shrink margins below the document standard just to fit it.
|
|
234
|
+
|
|
235
|
+
### 3.4 Clickable TOC / index links
|
|
236
|
+
|
|
237
|
+
Every generated multi-page PDF must include a visible table of contents or
|
|
238
|
+
index that links to the corresponding section pages. This is part of the PDF
|
|
239
|
+
navigation contract, not optional decoration.
|
|
240
|
+
|
|
241
|
+
Author HTML TOCs with internal anchors and stable target IDs:
|
|
242
|
+
|
|
243
|
+
```html
|
|
244
|
+
<nav class="toc" aria-label="Table of contents">
|
|
245
|
+
<a class="toc-row" href="#sec-summary">
|
|
246
|
+
<span>Executive summary</span><span class="page-ref">2</span>
|
|
247
|
+
</a>
|
|
248
|
+
<a class="toc-row" href="#sec-methodology">
|
|
249
|
+
<span>Methodology</span><span class="page-ref">5</span>
|
|
250
|
+
</a>
|
|
251
|
+
</nav>
|
|
252
|
+
|
|
253
|
+
<section class="page" id="sec-summary">
|
|
254
|
+
<h2>Executive summary</h2>
|
|
255
|
+
...
|
|
256
|
+
</section>
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Rules:
|
|
260
|
+
|
|
261
|
+
- Every major section, appendix, and reference block gets a unique ASCII `id`.
|
|
262
|
+
- TOC rows are real `<a href="#...">` links, not inert `<div>` rows styled to
|
|
263
|
+
look like links.
|
|
264
|
+
- Displayed page numbers must match the rendered PDF. If the final page count
|
|
265
|
+
shifts, re-render or update the TOC before delivery.
|
|
266
|
+
- Keep TOC styling print-friendly: visible row text, dot leaders or right-aligned
|
|
267
|
+
page numbers, and sufficient line height for clicking.
|
|
268
|
+
- If the PDF is assembled after rendering (merge/split/reportlab/pypdf), add PDF
|
|
269
|
+
outline/bookmarks and `/Link` annotations so the visible TOC remains clickable.
|
|
270
|
+
- Single-page posters/forms/certificates may omit the TOC, but the delivery note
|
|
271
|
+
must explicitly state that it was omitted because the document is one page.
|
|
272
|
+
|
|
273
|
+
Verification:
|
|
274
|
+
|
|
275
|
+
- Inspect the final PDF in a viewer and spot-click at least 3 TOC entries (or all
|
|
276
|
+
entries when fewer than 3) to confirm they jump to the intended pages.
|
|
277
|
+
- Use `pdfinfo out.pdf` and/or a short `pypdf` probe to confirm link annotations
|
|
278
|
+
or outlines exist; `pdftotext` alone is insufficient because it cannot prove
|
|
279
|
+
clickability.
|
|
280
|
+
- For long documents, also verify that the PDF side-panel outline/bookmarks
|
|
281
|
+
match the visible TOC hierarchy when bookmarks are expected.
|
|
282
|
+
|
|
283
|
+
## 4. Typography
|
|
284
|
+
|
|
285
|
+
```css
|
|
286
|
+
body {
|
|
287
|
+
font-family:
|
|
288
|
+
-apple-system, BlinkMacSystemFont, "SF Pro Display",
|
|
289
|
+
"PingFang SC", /* Simplified Chinese — keep for CN content */
|
|
290
|
+
"Hiragino Sans", /* Japanese fallback */
|
|
291
|
+
"Apple SD Gothic Neo",/* Korean — REQUIRED for hangul, Hiragino doesn't cover it */
|
|
292
|
+
"Helvetica Neue", Arial, sans-serif;
|
|
293
|
+
font-size: 10.5pt;
|
|
294
|
+
line-height: 1.55;
|
|
295
|
+
-webkit-font-smoothing: antialiased;
|
|
296
|
+
}
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
- Body 10–11 pt, line-height 1.45–1.7. Below 10 pt becomes hard to read;
|
|
300
|
+
above 12 pt eats too much page area.
|
|
301
|
+
- **Cascade order matters for CJK.** If you put `Hiragino Sans` before
|
|
302
|
+
`PingFang SC`, simplified-Chinese characters render in JP forms.
|
|
303
|
+
- Don't ship a CDN webfont and hope it loads — Chromium prints whatever it
|
|
304
|
+
has at snapshot time. Either use system fonts (above) or `@font-face` from a
|
|
305
|
+
local file under `assets/fonts/` and rely on
|
|
306
|
+
`page.waitForFunction(() => document.fonts.ready)` (the renderer already
|
|
307
|
+
does this).
|
|
308
|
+
|
|
309
|
+
## 5. Color & accessibility
|
|
310
|
+
|
|
311
|
+
- **One accent color** per document. Section-line, chart-title bar, primary
|
|
312
|
+
bar fill, link border — all the same hex.
|
|
313
|
+
- **At most 3 data colors + 1 accent + 5 grayscale shades.** More than that
|
|
314
|
+
is visual noise.
|
|
315
|
+
- Accent contrast vs background ≥ **4.5:1** (WCAG AA). Skip pure blue
|
|
316
|
+
(`#007AFF`) for non-Apple-themed reports — overused.
|
|
317
|
+
- 5-level status pills are fixed semantics, do not invent more:
|
|
318
|
+
|
|
319
|
+
| Class | Background | Text | Meaning |
|
|
320
|
+
| --- | --- | --- | --- |
|
|
321
|
+
| `pill-bad` | `#ffebee` | `#c62828` | hard fail |
|
|
322
|
+
| `pill-warn` | `#fff3e0` | `#e65100` | risky / borderline |
|
|
323
|
+
| `pill-ok` | `#e8f5e9` | `#2e7d32` | passes baseline |
|
|
324
|
+
| `pill-good` | `#e3f2fd` | `#1565c0` | comfortably exceeds |
|
|
325
|
+
| `pill-best` | `#f3e5f5` | `#6a1b9a` | top-tier / recommended |
|
|
326
|
+
|
|
327
|
+
## 6. Charts (Chart.js)
|
|
328
|
+
|
|
329
|
+
```html
|
|
330
|
+
<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
|
|
331
|
+
<script>
|
|
332
|
+
Chart.defaults.animation = false; /* CRITICAL — see below */
|
|
333
|
+
Chart.defaults.font.family = '-apple-system, "PingFang SC", sans-serif';
|
|
334
|
+
Chart.defaults.font.size = 10;
|
|
335
|
+
Chart.defaults.color = '#424245';
|
|
336
|
+
// … new Chart(...)
|
|
337
|
+
</script>
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
- **`Chart.defaults.animation = false`** is non-negotiable. With animation on,
|
|
341
|
+
Chromium frequently snapshots mid-frame and you get a half-drawn bar.
|
|
342
|
+
- Render with `--wait 15000` (15 s settle window) when the page has Chart.js,
|
|
343
|
+
lazy images, or any other late-loading JS. Default `--wait 800` is enough
|
|
344
|
+
for static HTML.
|
|
345
|
+
- Wrap each `<canvas>` in `.chart-card.avoid-break` so a chart never splits
|
|
346
|
+
across pages.
|
|
347
|
+
- **Two-decade value range (e.g. 80 vs 5,841)** — use `scales.x.type:
|
|
348
|
+
'logarithmic'` (or `y.type`) and call out the log scale in the chart's
|
|
349
|
+
sub-title.
|
|
350
|
+
- **Dual-axis charts** require `position: 'right', grid: { display: false }`
|
|
351
|
+
on the secondary axis.
|
|
352
|
+
- 8 baseline chart types live in
|
|
353
|
+
[`templates/data-viz-report/skeleton.html`](../templates/data-viz-report/skeleton.html):
|
|
354
|
+
dual-axis bar+line, horizontal grouped bar, grouped vertical bar, scatter
|
|
355
|
+
matrix, stacked bar, log-axis bar, radar, dual-axis bar (price/power).
|
|
356
|
+
Copy from there before writing fresh init code.
|
|
357
|
+
|
|
358
|
+
## 7. Tables
|
|
359
|
+
|
|
360
|
+
- 9–9.5 pt body, 8.5 pt header, line-height 1.4–1.5.
|
|
361
|
+
- `border-collapse: collapse`, zebra `nth-child(even)` row, `padding: 7px 10px`.
|
|
362
|
+
- `page-break-inside: avoid` on small tables; for large tables, allow split
|
|
363
|
+
but repeat headers via `<thead>`.
|
|
364
|
+
- **Use half-width punctuation inside cells** (`()`、`:`、`/`). Full-width
|
|
365
|
+
CJK punctuation forces line-wrap in narrow columns.
|
|
366
|
+
- Status badges go in their own column with one of the 5 `pill-*` classes.
|
|
367
|
+
|
|
368
|
+
## 8. Images / SVG / icons
|
|
369
|
+
|
|
370
|
+
- Inline SVG is the most reliable; `<svg>…</svg>` direct or
|
|
371
|
+
`data:image/svg+xml;base64,…`.
|
|
372
|
+
- For raster images, prefer **inline base64** (`data:image/png;base64,…`) or
|
|
373
|
+
absolute `file://` paths. `http://` is fragile in headless mode.
|
|
374
|
+
- Lazy-loaded `<img loading="lazy">` may not paint in time — pre-load via
|
|
375
|
+
`<link rel="preload" as="image" href="...">` or remove the attribute.
|
|
376
|
+
- `max-width: 100%; height: auto;` on every body image.
|
|
377
|
+
|
|
378
|
+
## 9. Special characters & encoding
|
|
379
|
+
|
|
380
|
+
- **Don't fake superscripts with HTML entities.** `3nm⊃2;` (intent: `3nm²`)
|
|
381
|
+
prints the literal `⊃2;`. Paste real unicode: `²` `³` `⁺` `⁻` `™` `°` `µ`.
|
|
382
|
+
- **Never use full-width / CJK quotes in HTML or CSS syntax.** Editors that
|
|
383
|
+
default to 中文标点 will silently turn `"` into `“ ”` and `'` into `‘ ’`,
|
|
384
|
+
producing invalid markup that Chromium parses as a malformed attribute /
|
|
385
|
+
selector. Symptoms: attributes get dropped (`class=` becomes inert),
|
|
386
|
+
`font-family` falls back, charts won't render. Always type ASCII
|
|
387
|
+
`"` / `'` in:
|
|
388
|
+
- HTML attribute values: `class="kpi blue"`, `<a href="...">` — never
|
|
389
|
+
`class=“kpi blue”`
|
|
390
|
+
- CSS string values: `font-family: "PingFang SC"` — never `"PingFang SC"`
|
|
391
|
+
- JS string literals: `'use strict'` — never `‘use strict’`
|
|
392
|
+
- JSON / template literals
|
|
393
|
+
Full-width quotes are fine in **body prose** between tags, e.g.
|
|
394
|
+
`<p>他说"你好"</p>`. The rule is structural-syntax-only.
|
|
395
|
+
- **Other CJK punctuation also breaks syntax.** Watch for `;`(;vs `;`),
|
|
396
|
+
`:`(:vs `:`), `,`(,vs `,`), `()`(()vs `()`), and `——`(em-dash
|
|
397
|
+
used as JS minus). Same rule: full-width OK in prose, ASCII-only in code.
|
|
398
|
+
- **Don't write `&` in HTML attributes you've already escaped.** Use a
|
|
399
|
+
raw `&` inside CDATA / template literals.
|
|
400
|
+
- Always declare `<meta charset="UTF-8">` in `<head>`; without it, Chromium
|
|
401
|
+
guesses Latin-1 and CJK becomes mojibake.
|
|
402
|
+
|
|
403
|
+
## 10. Resource bundling / offline rendering
|
|
404
|
+
|
|
405
|
+
- The renderer respects `--wait` for CDN-loaded scripts but cannot recover
|
|
406
|
+
from a hard 4xx. If the agent runs offline (corporate VPN, sandbox), vendor:
|
|
407
|
+
- `chart.js@4.4.0/dist/chart.umd.min.js` → `templates/<slug>/vendor/`
|
|
408
|
+
- any `@font-face` woff2 files → `templates/<slug>/assets/fonts/`
|
|
409
|
+
Reference them with relative paths from the HTML file.
|
|
410
|
+
|
|
411
|
+
## 11. Quality gate (agent self-check before declaring done)
|
|
412
|
+
|
|
413
|
+
Run these every time before reporting "PDF ready":
|
|
414
|
+
|
|
415
|
+
```bash
|
|
416
|
+
# 1. The PDF actually exists and is non-trivial
|
|
417
|
+
ls -lh out.pdf
|
|
418
|
+
[[ $(stat -f%z out.pdf 2>/dev/null || stat -c%s out.pdf) -gt 50000 ]] || echo "FAIL: too small"
|
|
419
|
+
|
|
420
|
+
# 2. Page count matches expectation
|
|
421
|
+
pdfinfo out.pdf | grep Pages
|
|
422
|
+
|
|
423
|
+
# 3. Body text is extractable (not rasterized) — first 40 lines should be readable
|
|
424
|
+
pdftotext -layout out.pdf - | head -40
|
|
425
|
+
|
|
426
|
+
# 4. Visual eyeball check — open EVERY page, look at the bottom of each
|
|
427
|
+
open out.pdf # macOS — confirm charts drew, no blank canvases, fonts correct
|
|
428
|
+
# AND no page has > 1/3 blank below the last element (see §3.2)
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
Before committing the source HTML, confirm:
|
|
432
|
+
|
|
433
|
+
- [ ] All `<!-- PLACEHOLDER -->` tokens replaced (search for `<!--`).
|
|
434
|
+
- [ ] `@page { size: A4 portrait }` matches the renderer's `--format`
|
|
435
|
+
(default A4). No stray `8.5in 11in` / `Letter` in the source unless
|
|
436
|
+
you also pass `--format Letter`. Cover heights computed from page
|
|
437
|
+
size minus margins, **not** `100vh`.
|
|
438
|
+
- [ ] **Source HTML includes the `@media screen` block** (see §1) so
|
|
439
|
+
`open page.html` in a browser shows the same A4 sheet stack as the
|
|
440
|
+
PDF. If the browser preview is one wide horizontal page, the block
|
|
441
|
+
is missing — the agent and reviewer will both be misled by the
|
|
442
|
+
wrong geometry. Don't trust browser preview without it.
|
|
443
|
+
- [ ] No `⊃2;` / `&sup` / `&` artifacts in the output.
|
|
444
|
+
- [ ] No CJK full-width quotes / punctuation in HTML/CSS/JS syntax
|
|
445
|
+
(only `"` `'` `;` `:` `,` `()` allowed in code; full-width is
|
|
446
|
+
fine inside prose between tags).
|
|
447
|
+
- [ ] Each `<canvas>` parent has `.avoid-break`.
|
|
448
|
+
- [ ] `Chart.defaults.animation = false` is set.
|
|
449
|
+
- [ ] **Every page is ≥ 2/3 full** — flip through the whole PDF,
|
|
450
|
+
not just the last page. Any page with a > 1/3 blank gap below
|
|
451
|
+
the last element must be fixed (pull next-section content forward,
|
|
452
|
+
expand current content, or re-order — see §3.2). Don't ship
|
|
453
|
+
half-empty pages.
|
|
454
|
+
- [ ] Every multi-page PDF has clickable TOC/index navigation to the
|
|
455
|
+
corresponding pages (or, for official/source-faithful exceptions,
|
|
456
|
+
preserved/added outline navigation with the exception documented). Spot-
|
|
457
|
+
click at least 3 entries and confirm link annotations/outlines exist;
|
|
458
|
+
`pdftotext` alone does not prove navigation works.
|
|
459
|
+
- [ ] At most 3 data colors + 1 accent (re-skinned away from default blue).
|
|
460
|
+
- [ ] CJK source files use the SC → JP → KR → Latin font cascade.
|
|
461
|
+
|
|
462
|
+
## 12. Renderer reference
|
|
463
|
+
|
|
464
|
+
[`scripts/render_html.cjs`](../scripts/render_html.cjs):
|
|
465
|
+
|
|
466
|
+
```bash
|
|
467
|
+
node scripts/render_html.cjs \
|
|
468
|
+
--in page.html --out report.pdf \
|
|
469
|
+
[--wait 15000] # extra settle (ms); 15000+ for Chart.js
|
|
470
|
+
[--format A4|Letter]
|
|
471
|
+
[--margin "14mm 12mm"] # CSS margin shorthand (1/2/3/4 values)
|
|
472
|
+
[--landscape]
|
|
473
|
+
[--scale 1] # 0.1–2.0
|
|
474
|
+
[--no-print-background]
|
|
475
|
+
[--header <html>] # page-header template (uses Playwright tokens like {pageNumber})
|
|
476
|
+
[--footer <html>]
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
The renderer:
|
|
480
|
+
1. Loads `playwright` (local node_modules first, then global `npm root -g`).
|
|
481
|
+
2. `page.goto(url, { waitUntil: 'networkidle', timeout: 60000 })`.
|
|
482
|
+
3. `page.waitForFunction(() => document.fonts.ready)` (best-effort, 15 s cap).
|
|
483
|
+
4. `page.waitForTimeout(--wait)` for late JS / charts.
|
|
484
|
+
5. `page.pdf(opts)` then writes `--out`.
|
|
485
|
+
6. Sanity check: output > 5 KB, otherwise exits 3.
|
|
486
|
+
|
|
487
|
+
## 13. Anti-patterns
|
|
488
|
+
|
|
489
|
+
| Don't | Why |
|
|
490
|
+
| --- | --- |
|
|
491
|
+
| Use `pixels` for layout | Print at 96 DPI — your margins drift |
|
|
492
|
+
| Use `vw` / `vh` / `100vh` for cover height | Bound to viewport, not the printed page → cover shrinks to single screen |
|
|
493
|
+
| Set `@page { size: 8.5in 11in }` while renderer prints A4 | CSS thinks Letter, output is A4 → content overflows or massive empty bands |
|
|
494
|
+
| Design hero sections at 16:9 / 4:3 | A4 is 1:1.414 (taller) — 16:9 hero leaves the bottom 1/3 blank |
|
|
495
|
+
| Skip `Chart.defaults.animation = false` | Mid-frame snapshots → blank charts |
|
|
496
|
+
| Ship CDN webfonts without `document.fonts.ready` | Body text falls back to default sans |
|
|
497
|
+
| `display: none` instead of `visibility: hidden` for print-only hides | Chromium drops the element from layout calc, breaking page-break math |
|
|
498
|
+
| Force-fit a thin last page by shrinking margins | Looks cramped, wastes white space — extend the content instead |
|
|
499
|
+
| Default to blue (`#007AFF`) for every report | Reports look identical, defeats the point of HTML flexibility |
|
|
500
|
+
| Inline JSON content > 1 MB in the HTML | Chromium parse + GC cost exceeds your `--wait` budget |
|