pptx-ts 3.7.0 → 4.0.0

package/package.json

@@ -1,14 +1,14 @@
 {
 	"name": "pptx-ts",
-	"version": "3.7.0",
+	"version": "4.0.0",
 	"author": {
 		"name": "shbernal",
 		"url": "https://github.com/shbernal/"
 	},
 	"description": "Create PowerPoint presentations (.pptx) from TypeScript and modern JavaScript",
-	"homepage": "https://github.com/shbernal/ts-pptx#readme",
+	"homepage": "https://shbernal.github.io/ts-pptx/",
 	"license": "MIT",
-	"packageManager": "pnpm@11.3.0",
+	"packageManager": "pnpm@12.3.4",
 	"type": "module",
 	"engines": {
 		"node": ">=24"
@@ -57,6 +57,10 @@
 			"types": "./dist/html.d.ts",
 			"default": "./dist/html.js"
 		},
+		"./families": {
+			"types": "./dist/families.d.ts",
+			"default": "./dist/families.js"
+		},
 		"./node": {
 			"types": "./dist/node.d.ts",
 			"node": "./dist/node.js",
@@ -76,6 +80,88 @@
 		"skills"
 	],
 	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsdown",
+		"prepare": "node scripts/install-hooks.mjs && node scripts/ensure-dist.mjs --if-missing",
+		"start": "pnpm run watch",
+		"watch": "tsdown --watch",
+		"watch:dev": "tsdown --config tsdown.dev.config.ts --watch",
+		"ensure-dist": "node scripts/ensure-dist.mjs",
+		"verify": "node scripts/run-steps.mjs ensure-dist check:core test",
+		"verify:full": "node scripts/run-steps.mjs verify docs:build script:roundtrip:all package:lint test:package bundle-size:check bundle-tier:check",
+		"check:static": "node scripts/run-steps.mjs ensure-dist lint lint:chars format:check check:core",
+		"check:core": "node scripts/run-steps.mjs typecheck typecheck:scripts typecheck:test typecheck:site raw-xml:check ooxml-literals:check path-refs:check docs:check comparison:check",
+		"check:package": "node scripts/run-steps.mjs ensure-dist package:lint test:package bundle-size:check bundle-tier:check",
+		"test": "pnpm run ensure-dist && vitest run",
+		"test:unit": "pnpm run ensure-dist && vitest run test/regression",
+		"test:schema": "pnpm run ensure-dist && vitest run test/schema-validation.test.js",
+		"schema:versions": "pnpm run ensure-dist && node scripts/ooxml-version-probe.mjs",
+		"test:read": "pnpm run ensure-dist && vitest run test/read",
+		"test:oracles": "pnpm run ensure-dist && node scripts/font-oracle-probe.mjs && vitest run test/read/autofit-calibration-oracle.test.js test/read/cjk-line-breaking-oracle.test.js test/read/font-metrics-sidecar.test.js",
+		"font-metrics:build": "pnpm run ensure-dist && node test/read/fixtures/authoring/build-font-metrics.mjs",
+		"test:read:emit": "pnpm run ensure-dist && node scripts/read-emit-roundtrip.mjs",
+		"test:read:emit:edits": "pnpm run ensure-dist && node scripts/read-emit-edits.mjs",
+		"read:census": "pnpm run ensure-dist && node scripts/read-blindness-census.mjs",
+		"exports:reach": "pnpm run ensure-dist && node scripts/export-reach.mjs",
+		"read:append-ceiling": "pnpm run ensure-dist && node scripts/append-ceiling.mjs",
+		"script:roundtrip": "pnpm run ensure-dist && node scripts/script-roundtrip.mjs",
+		"script:roundtrip:a": "pnpm run ensure-dist && node scripts/script-roundtrip.mjs --tier a",
+		"script:roundtrip:all": "pnpm run script:roundtrip && pnpm run script:roundtrip:a",
+		"script:census": "pnpm run ensure-dist && node scripts/note-census.mjs",
+		"test:watch": "vitest --watch test/regression",
+		"test:coverage": "pnpm run ensure-dist && vitest run --coverage",
+		"coverage:probe": "pnpm run ensure-dist && vitest run --coverage --coverage.reportsDirectory=coverage/probe --coverage.reporter=json --coverage.reporter=json-summary --coverage.reporter=text-summary --coverage.thresholds.statements=0 --coverage.thresholds.branches=0 --coverage.thresholds.functions=0 --coverage.thresholds.lines=0",
+		"coverage:merge": "node scripts/coverage-merge.mjs",
+		"coverage:gate": "pnpm run coverage:merge && node scripts/coverage-gate.mjs",
+		"test:package": "node scripts/package-smoke.mjs",
+		"test:browser": "pnpm run docs:build && playwright test",
+		"demos:build": "pnpm run ensure-dist && pnpm --dir demos/showcases run build",
+		"test:com": "pnpm run ensure-dist && node scripts/powerpoint-com-smoke.mjs",
+		"test:lo": "pnpm run ensure-dist && node scripts/libreoffice-render-smoke.mjs",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck:scripts": "tsc -p tsconfig.scripts.json --noEmit",
+		"typecheck:test": "tsc -p tsconfig.test.json --noEmit",
+		"typecheck:site": "tsc -p docs/tsconfig.json --noEmit",
+		"lint": "oxlint . --deny-warnings --report-unused-disable-directives",
+		"lint:chars": "charcheck --max-warnings 0",
+		"lint:chars:fix": "charcheck --fix --max-warnings 0",
+		"format:run": "oxfmt \"src/**/*.ts\" package.json tools/api-docs/package.json .oxfmtrc.jsonc pnpm-workspace.yaml typedoc.docs.json tsconfig.base.json tsconfig.json tsconfig.scripts.json tsconfig.test.json docs/tsconfig.json docs/.vitepress/config.mts \"docs/.vitepress/theme/**/*.ts\" \"www/**/*.ts\" .oxlintrc.jsonc charcheck.config.js tsdown.config.ts tsdown.dev.config.ts vitest.config.ts playwright.config.ts \"scripts/**/*.mjs\" \"test/**/*.mjs\" \"test/**/*.js\" \".github/**/*.yml\"",
+		"format": "pnpm run format:run --write",
+		"format:check": "pnpm run format:run --check",
+		"package:lint": "node scripts/package-lint.mjs",
+		"bundle-size:check": "pnpm run ensure-dist && node scripts/bundle-size-ratchet.mjs",
+		"bundle-size:freeze": "pnpm run ensure-dist && node scripts/bundle-size-ratchet.mjs --freeze",
+		"bundle-size:list": "pnpm run ensure-dist && node scripts/bundle-size-ratchet.mjs --list",
+		"bundle-tier:check": "pnpm run ensure-dist && node scripts/bundle-tier-size.mjs",
+		"bundle-tier:freeze": "pnpm run ensure-dist && node scripts/bundle-tier-size.mjs --freeze",
+		"bundle-tier:list": "pnpm run ensure-dist && node scripts/bundle-tier-size.mjs --list",
+		"raw-xml:check": "node scripts/raw-xml-ratchet.mjs",
+		"ooxml-literals:check": "node scripts/ooxml-literal-gate.mjs",
+		"raw-xml:freeze": "node scripts/raw-xml-ratchet.mjs --freeze",
+		"raw-xml:list": "node scripts/raw-xml-ratchet.mjs --list",
+		"path-refs:check": "node scripts/path-refs.mjs",
+		"path-refs:list": "node scripts/path-refs.mjs --list",
+		"media:playbtn": "node scripts/gen-playbtn.mjs",
+		"byte-identity:baseline": "node scripts/byte-identity.mjs baseline",
+		"byte-identity:check": "node scripts/byte-identity.mjs check",
+		"prepack": "pnpm run build",
+		"version": "node scripts/sync-version.mjs --stage",
+		"version:sync": "node scripts/sync-version.mjs",
+		"version:check": "node scripts/sync-version.mjs --check",
+		"comparison:measure": "pnpm run ensure-dist && node scripts/comparison/measure.mjs",
+		"comparison:render": "node scripts/comparison/render.mjs",
+		"comparison:check": "node scripts/comparison/render.mjs --check",
+		"docs:list": "node scripts/docs-list.mjs",
+		"docs:new": "node scripts/docs-new.mjs",
+		"docs:api": "node scripts/docs-api.mjs",
+		"docs:llms": "node scripts/generate-llms-docs.mjs",
+		"docs:index": "node scripts/docs-index.mjs",
+		"docs:check": "pnpm run docs:api && pnpm run docs:index && node scripts/docs-check.mjs",
+		"docs:prepare": "pnpm run docs:api && pnpm run docs:index && pnpm run docs:llms",
+		"docs:dev": "pnpm run ensure-dist && pnpm run docs:prepare && vitepress dev docs",
+		"docs:build": "pnpm run ensure-dist && pnpm run docs:prepare && node scripts/docs-check.mjs && vitepress build docs && node scripts/docs-check.mjs --dist",
+		"docs:preview": "vitepress preview docs"
+	},
 	"dependencies": {
 		"@xmldom/xmldom": "^0.9.12",
 		"fflate": "^0.8.3",
@@ -98,39 +184,40 @@
 	},
 	"devDependencies": {
 		"@arethetypeswrong/cli": "^0.18.5",
-		"@playwright/test": "^1.62.1",
+		"@playwright/test": "^1.63.0",
 		"@types/istanbul-lib-coverage": "^2.0.6",
 		"@types/istanbul-lib-report": "^3.0.3",
 		"@types/istanbul-reports": "^3.0.4",
-		"@types/node": "^26.3.0",
+		"@types/node": "^26.6.1",
 		"@types/opentype.js": "^1.3.10",
-		"@vitest/coverage-v8": "^4.1.11",
-		"@vue/compiler-sfc": "^3.5.41",
-		"ast-v8-to-istanbul": "^1.0.5",
-		"charcheck": "0.2.5",
+		"@vitest/coverage-v8": "^5.0.1",
+		"@vue/compiler-sfc": "^3.5.42",
+		"ast-v8-to-istanbul": "^1.0.6",
+		"charcheck": "0.4.0",
 		"esbuild": "^0.28.2",
-		"happy-dom": "^20.11.6",
+		"happy-dom": "^20.14.5",
 		"istanbul-lib-coverage": "^3.2.2",
 		"istanbul-lib-report": "^3.0.1",
 		"istanbul-reports": "^3.2.0",
-		"jszip": "^3.10.1",
-		"lefthook": "^2.1.10",
+		"jszip": "^3.10.2",
+		"lefthook": "^2.1.14",
 		"mathml2omml": "^0.5.0",
+		"mermaid": "^12.0.0",
 		"micromark": "^4.0.2",
 		"ooxml-validate": "^0.0.3",
-		"oxfmt": "^0.65.0",
-		"oxlint": "^1.80.0",
+		"oxfmt": "^0.68.0",
+		"oxlint": "^1.83.0",
 		"oxlint-tsgolint": "7.0.2001",
-		"pptx-html": "^0.1.2",
+		"pptx-html": "^0.2.0",
 		"publint": "^0.3.24",
-		"temml": "^0.13.4",
+		"temml": "^0.13.5",
 		"ts-pptx-demos-showcases": "workspace:*",
-		"tsdown": "^0.22.14",
+		"tsdown": "^0.23.0",
 		"typescript": "^7.0.2",
 		"typescript-6": "npm:typescript@6.0.3",
 		"vitepress": "^1.6.4",
-		"vitest": "^4.1.11",
-		"vue": "^3.5.41"
+		"vitest": "^5.0.1",
+		"vue": "^3.5.42"
 	},
 	"repository": {
 		"type": "git",

package/skills/ts-pptx-upstream/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: ts-pptx-upstream
-description: Report a ts-pptx (@shbernal/ts-pptx) bug, gap, or wrong output to its GitHub tracker from a project that depends on it. Use when ts-pptx throws an InternalError or an error whose message points at the issue tracker, when it cannot read a .pptx that opens cleanly in PowerPoint, when it writes a deck PowerPoint repairs or renders wrong, when a construct does not survive a round trip, when its types block correct code, or whenever you are about to write a workaround for ts-pptx behaving incorrectly. Filing the bug is the fix; the workaround is the stopgap.
+description: Report a ts-pptx (pptx-ts) bug, gap, or wrong output to its GitHub tracker from a project that depends on it. Use when ts-pptx throws an InternalError or an error whose message points at the issue tracker, when it cannot read a .pptx that opens cleanly in PowerPoint, when it writes a deck PowerPoint repairs or renders wrong, when a construct does not survive a round trip, when its types block correct code, or whenever you are about to write a workaround for ts-pptx behaving incorrectly. Filing the bug is the fix; the workaround is the stopgap.
 ---
 
 # Reporting a ts-pptx problem upstream
 
-You are in a project that *uses* `@shbernal/ts-pptx`, not the project that builds it.
+You are in a project that *uses* `pptx-ts`, not the project that builds it.
 This skill is how a defect you hit here becomes a permanent regression test there.
 
 The library's maintainers turn reports with a minimal reproduction into fixtures and
-regression cases, which is the only mechanism that guarantees a bug is never
-reintroduced. A report without a reproduction is a wish; a report with one is a fix.
+regression cases, which is the only way to guarantee the bug never comes back. A report
+without a reproduction is a wish; a report with one is a fix.
 
 **The single most valuable thing you can do is reduce the failure to a script that
 builds its own deck.** Everything below is in service of that.
@@ -18,8 +18,8 @@ builds its own deck.** Everything below is in service of that.
 ## 1. Decide whether it is actually ours
 
 Every failure ts-pptx raises is a `TsPptxError` in one of five classes, and the class
-already answers *whose problem is this*. Catch it and read `err.name` and `err.code`
-— `code` is a stable `area/condition` string and is API; the message is not, so never
+already answers *whose problem is this*. Catch it and read `err.name` and `err.code`.
+`code` is a stable `area/condition` string and is API; the message is not, so never
 branch on its wording.
 
 | class                     | whose bug        | report it?                                                          |
@@ -41,10 +41,10 @@ Not every defect throws. These are ours too, and are worth reporting:
   renders differently than intended.
 - A **round trip that loses a construct**: read a deck, write it back, something is
   gone or changed. If the loss surfaced as a conversion fidelity note, the note has
-  already classified it for you — see below.
-- The **read side cannot see what the write side authors** — a property ts-pptx emits
-  but has no accessor to read back. This is the strongest case a gap can make, and it
-  has its own form (see step 5).
+  already classified it for you. See below.
+- The **read side cannot see what the write side authors**: ts-pptx emits the property
+  but has no accessor to read it back. This is the strongest case a gap can make, and
+  it has its own form (see step 5).
 - A `Diagnostic` that fires when it should not, does not fire when it should, or
   carries the wrong `code`.
 - Types that make correct code fail to compile, or admit code that throws at runtime.
@@ -52,15 +52,15 @@ Not every defect throws. These are ours too, and are worth reporting:
 
 ### If you are holding a fidelity note, it already told you
 
-Anything that converts a deck through `@shbernal/ts-pptx/script` gets `FidelityNote`s
+Anything that converts a deck through `pptx-ts/script` gets `FidelityNote`s
 back, and `cause` is the library's own verdict on whose gap the loss is. Read it
-before deciding whether to file — it answers the same question the error table above
+before deciding whether to file. It answers the same question the error table above
 answers for the throwing cases:
 
-| `cause`       | what it means                                              | report it?                                      |
-| ------------- | ---------------------------------------------------------- | ----------------------------------------------- |
-| `unread`      | nothing on the read side can see it — a missing reader      | **Yes**, and `api-gap.yml` is its form.          |
-| `unwritable`  | it is read fine, but no write option can author it back     | **Yes** — a missing option is a gap, not a limit.|
+| `cause`       | what it means                                              | report it?                                       |
+| ------------- | ---------------------------------------------------------- | ------------------------------------------------ |
+| `unread`      | nothing on the read side can see it, so no reader exists    | **Yes**, and `api-gap.yml` is its form.          |
+| `unwritable`  | it is read fine, but no write option can author it back     | **Yes**. A missing option is a gap, not a limit. |
 | `unsupported` | OOXML, or the tier you chose, cannot express it at all      | **No**. No amount of converter work closes it.   |
 
 So a `dropped`/`unread` note is a report waiting to be written, and an `unsupported`
@@ -70,9 +70,9 @@ the fastest thing a maintainer can search on.
 
 One more shape worth filing: a note that fires for a construct that **did** survive.
 A declared loss that does not happen is a stale note, and it is a defect in the same
-way a missing one is — it teaches every reader to discount the notes that are true.
+way a missing one is. It teaches every reader to discount the notes that are true.
 
-Two things are **out of active maintenance scope** and will usually be closed — check
+Two things are **out of active maintenance scope** and will usually be closed. Check
 before spending effort on a reproduction:
 
 - Live-DOM / browser-layout features, i.e. anything whose answer comes from a
@@ -86,17 +86,17 @@ Issues and pull requests in those two areas are still welcome; just say so in th
 report so nobody triages it as a regression.
 
 Also: ts-pptx is **ESM, Node-first**. Reports about `require()`, a CJS build, or an
-IIFE/global browser bundle will be closed — those are deliberately not supported.
+IIFE/global browser bundle will be closed. Those are deliberately not supported.
 
 ## 2. Collect the facts
 
 ```bash
-node -p "require('@shbernal/ts-pptx/package.json').version"   # exact installed version
-node -v                                                       # runtime (>=24 required)
+node -p "require('pptx-ts/package.json').version" # exact installed version
+node -v                                           # runtime (>=24 required)
 ```
 
 Capture, verbatim: `err.name`, `err.code`, the full message, `err.detail` if present,
-and the stack. Do not paraphrase the message — the throw site is often identifiable
+and the stack. Do not paraphrase the message. The throw site is often identifiable
 from its exact text, and `detail` is the structured context the site chose to attach.
 
 If the failure is about how the file *renders* or whether PowerPoint repairs it, note
@@ -108,14 +108,14 @@ for a render report it is load-bearing.
 **Never attach or paste the user's deck.** A presentation in a real project carries
 client names, unreleased strategy, pricing, and internal logos. Treat every `.pptx`
 in this repo as confidential unless the user tells you otherwise, and never upload one
-to a public tracker — including "just a screenshot of the slide". This is the same rule
+to a public tracker, not even "just a screenshot of the slide". This is the same rule
 the project already applies to its own filings: describe a downstream consumer's need
 anonymously, never its name, its deck or client names, or a path from its tree.
 
 Instead, write a self-contained script that *constructs* its input and fails:
 
 ```ts
-import TsPptx from '@shbernal/ts-pptx'
+import TsPptx from 'pptx-ts'
 
 // build the smallest deck that shows the problem
 const pptx = new TsPptx()
@@ -130,7 +130,7 @@ For a read-side or round-trip defect, generate the input with the write side fir
 the script still owns everything it touches:
 
 ```ts
-import { Presentation } from '@shbernal/ts-pptx/read'
+import { Presentation } from 'pptx-ts/read'
 
 const pres = await Presentation.load(bytes) // bytes built above, not the user's file
 // ...the accessor that returns the wrong thing, or throws
@@ -141,7 +141,7 @@ after each cut, until removing anything more makes the failure disappear. What i
 is the report.
 
 If the failure only reproduces with a *specific deck* you cannot share, do not ask for
-permission to share it — file without the file. Say exactly that in the report and
+permission to share it. File without the file. Say exactly that in the report and
 describe the structural feature you believe is responsible (a grouped shape, a chart
 part, a custom table style, a particular namespace prefix, a layout inherited from a
 master). A maintainer can usually author a fixture from that description in PowerPoint;
@@ -149,7 +149,7 @@ they can never unsee an attachment.
 
 If you need a file attached, build one: reproduce the *structure* you suspect in a deck
 you generate, with invented values. A synthesized file is always safe to attach. A
-redacted one is not yours to judge — redaction fails quietly, and a public tracker is
+redacted one is not yours to judge. Redaction fails quietly, and a public tracker is
 permanent.
 
 ## 4. Check it is not already fixed, or already filed
@@ -158,7 +158,7 @@ permanent.
 not necessarily the current one:
 
 ```bash
-npm view @shbernal/ts-pptx version   # latest published
+npm view pptx-ts version # latest published
 ```
 
 If that is ahead of the version you collected in step 2, bump the pin and re-run the
@@ -173,11 +173,11 @@ gh issue list --repo shbernal/ts-pptx --state all --limit 20 --search "<distinct
 ```
 
 Search the error `code` (`table/invalid-border`, `oxml/node-has-no-document`), the
-fidelity note's `construct` key, or the distinctive part of the message — not your
+fidelity note's `construct` key, or the distinctive part of the message, not your
 description of it. Codes and construct keys are stable and searchable in a way prose is
 not. If an open issue matches, add your reproduction as a comment instead of opening a
 duplicate; if a closed one matches, reopen the conversation there with your version and
-Node version — closed and unreleased is a real state, and so is closed and regressed.
+Node version. Closed and unreleased is a real state, and so is closed and regressed.
 
 ## 5. Pick the form, then file it
 
@@ -189,21 +189,21 @@ A bug that is never filed because the moment passed costs everyone, permanently.
 
 This rests entirely on step 3 holding: the reproduction constructs its own input, and no
 file from this project is attached. When you cannot manage a self-contained reproduction,
-the answer is a thinner report — the prose description from step 3 — not a question and
+the answer is a thinner report, the prose description from step 3. Not a question, and
 not an attachment.
 
 Three forms; pick by what you are reporting:
 
 | form               | for                                                                       |
 | ------------------ | ------------------------------------------------------------------------- |
-| `agent-report.yml` | you hit this while using the library in another project — start here       |
+| `agent-report.yml` | you hit this while using the library in another project. Start here.       |
 | `bug.yml`          | wrong output, a repair prompt, a regression, a fidelity limit              |
 | `api-gap.yml`      | the OOXML carries it but no accessor reaches it                            |
 
-If none fits, file a blank issue rather than bending one of them — blank issues are
+If none fits, file a blank issue rather than bending one of them. Blank issues are
 enabled deliberately.
 
-`gh` defaults to the *current* repository — which here is the consumer's, not ts-pptx's.
+`gh` defaults to the *current* repository, which here is the consumer's, not ts-pptx's.
 Always pass `--repo shbernal/ts-pptx` explicitly, or you will file the bug into the wrong
 tracker.
 
@@ -214,7 +214,7 @@ gh issue create --repo shbernal/ts-pptx \
   --body-file <a path your repo ignores>/ts-pptx-report.md
 ```
 
-Write the body somewhere the consumer's own `.gitignore` already covers — its scratch or
+Write the body somewhere the consumer's own `.gitignore` already covers: its scratch or
 temp directory, whatever that repo calls it. A report file committed by accident is a
 second copy of the reproduction living in someone else's history.
 
@@ -235,13 +235,13 @@ issue forms, so mirror its sections in the body file so both routes land the sam
 <only if the report depends on how PowerPoint renders or repairs the file>
 
 ### Error class and code
-<InternalError / oxml/node-has-no-document>   (or: no error thrown — wrong output)
+<InternalError / oxml/node-has-no-document>   (or: nothing threw, the output is wrong)
 
 ### What happened
 <observed>
 
 ### What should have happened
-<expected, and why you believe that — an ECMA-376 clause, what PowerPoint itself does
+<expected, and why you believe that: an ECMA-376 clause, what PowerPoint itself does
 with the same input, or what the docs promise>
 
 ### Minimal reproduction
@@ -255,10 +255,10 @@ with the same input, or what the docs promise>
 ```
 
 ### Attached file
-<none / synthesized — describe how it was generated>
+<none / synthesized, and how it was generated>
 ````
 
-Tell the user the issue number and URL once it exists — after the fact, as a result, not
+Tell the user the issue number and URL once it exists. After the fact, as a result, not
 as a request. They should be able to read what you filed and close it if they disagree.
 
 ## 6. Then, and only then, write the workaround
@@ -267,18 +267,18 @@ Filing does not unblock the user. Once the issue is open, implement the workarou
 this project and mark it, so that whoever bumps the pin later can find it and decide.
 
 An issue number alone is not enough of a mark. `remove once fixed upstream` does not say
-what *fixed* looks like, so at bump time it cannot be checked — it can only be
-re-investigated, which means re-reading the issue and re-deriving the reproduction
-someone already wrote. Write the comment so that verifying the fix is running one line:
+what *fixed* looks like, so at bump time it cannot be checked, only re-investigated,
+which means re-reading the issue and re-deriving the reproduction someone already wrote.
+Write the comment so that verifying the fix is running one line:
 
 ```ts
-// Workaround for ts-pptx#<N> — https://github.com/shbernal/ts-pptx/issues/<N>
+// Workaround for ts-pptx#<N>: https://github.com/shbernal/ts-pptx/issues/<N>
 //
 // <what the library does instead, as an observable: the XML it emits, the value the
 //  accessor returns, the option it ignores.>
 //
-// Remove when <the exact check — an accessor returning the right value, a written part
-// containing the right element> holds, and write <the code this becomes> instead.
+// Remove when <the exact check: an accessor returning the right value, or a written
+// part containing the right element> holds, and write <the code this becomes> instead.
 ```
 
 Keep `ts-pptx#` in that literal spelling wherever you mark one. It is the token that
@@ -287,18 +287,19 @@ the moment someone needs that list.
 
 ## 7. When the fix ships, delete the workaround
 
-The other half of the cycle, and the half that quietly does not happen: a stopgap nobody
-removes becomes indistinguishable from a design decision, and the next reader inherits it
-as one. Do this in one unit of work, on the release that carries the fix.
+This is the other half of the cycle, and the half that quietly does not happen. A
+stopgap nobody removes becomes indistinguishable from a design decision, and the next
+reader inherits it as one. Do this in one unit of work, on the release that carries the
+fix.
 
 ```bash
-npm view @shbernal/ts-pptx version                          # what is out
+npm view pptx-ts version                          # what is out
 gh issue list --repo shbernal/ts-pptx --state closed --limit 30
-rg 'ts-pptx#'                                               # every stopgap here
+rg 'ts-pptx#'                                     # every stopgap here
 ```
 
 **A closed issue is not a released fix.** A fix can sit merged and unreleased for weeks,
-so the published version is what to check, never the issue state — the repository's
+so check the published version, never the issue state. The repository's
 [`CHANGELOG.md`](https://github.com/shbernal/ts-pptx/blob/master/CHANGELOG.md) and the
 GitHub release notes name the issue numbers each version closes. Bump the pin, reinstall,
 and refresh the installed skill in the same commit. Then, per stopgap:
@@ -310,9 +311,9 @@ and refresh the installed skill in the same commit. Then, per stopgap:
    can hold it. The stopgap was the only thing keeping the defect from being visible; a
    deletion with nothing in its place means the same regression can return unnoticed.
 4. **Replace the comment rather than only deleting it** where the code still looks odd
-   without it. One sentence on why the shape it has is the shape it has — *this used to
-   be X because of Y, which release Z fixed* — is the difference between a reader
-   trusting the line and re-litigating it.
+   without it. Say in one sentence why the shape it has is the shape it has. *This used
+   to be X because of Y, which release Z fixed.* That sentence is the difference between
+   a reader trusting the line and re-litigating it.
 5. **Close the loop upstream**: comment on the issue with the check that now passes, in
    the same self-contained form as the original reproduction. A maintainer's own tests
    say the fix works; a consumer's say it works *where it was found*, which is the thing
@@ -327,14 +328,14 @@ Print the assembled report and this URL, and ask the user to paste it in:
 ## Keeping this skill current
 
 This file ships inside the package, so the copy in `node_modules` always matches the
-installed version — but the copy in an agent directory is a *copy*, and a version bump
-does not move it. Refresh it in the same commit as the bump, which is step 7's commit:
+installed version. The copy in an agent directory is a *copy*, and a version bump does
+not move it. Refresh it in the same commit as the bump, which is step 7's commit:
 
 ```bash
 npx skills update ts-pptx-upstream
 ```
 
 If that reports nothing to do but the skill is not loading, the runtime link is missing
-rather than the file — reinstall it with the command in the package README, which names
+rather than the file. Reinstall it with the command in the package README, which names
 the runtimes explicitly. `skills experimental_install` and `experimental_sync` restore
 the file from the lock and create no runtime links, so neither is the repair.