Repository navigation
Release/v1.3.0 - #32
Merged
Merged
Conversation
…cSpec Typography (layout.typography, keepWithNext, splittable, align justify), CMYK colour on every colour position, PDF/X-4 (pdfx, outputIntent), colour bars, a pinnable creationDate, six engine environment helpers, twelve lint rules (25 -> 37) carrying the engine's own messages, a third doctor probe, DOC_SPEC_FIELDS as the registry's fourth table, and the 1.2.0 baselines plus the additivity suites that prove nothing broke. Peer floor pdfnative ^1.7.0 -> ^1.8.0; version 1.3.0.
Ports the sibling repositories' hygiene: .gitattributes (LF everywhere, binaries, linguist-generated), .npmrc (ignore-scripts, fund, audit-level), .node-version, .editorconfig, opt-in git hooks, tsconfig.scripts.json, vitest under TZ=UTC with pool forks, packageManager, typesVersions for the client subpath, the gate scripts in package.json, dev-tree advisory overrides and vitest 4.1.11, the 1.3.0 keywords, dependabot ignores for the reconciler contract.
…e corpus and the PDF/X validator scripts/gate.ts (fast / ci / publish profiles, --require-all, inline dist-check, dist-probe, bundle-smoke and pack-check with publint and @arethetypeswrong/cli); generate-samples.ts runs every sample in its own process with the creation instant pinned under TZ=UTC; verify-samples.ts holds 38 samples to a chained byte baseline; the PDF/A corpus scripts move to TypeScript, the corpus grows to 16 files with three PDF/X-4 entries, validate-pdfx.ts checks them in-process; the two-time-zone proof over dist/index.js; visual-verify writes to the current directory like every sample.
…dows/macOS matrix ci.yml runs the gate with --require-all on Node 22 and 24 and, through the os job, on windows-latest and macos-latest; publish.yml pins the npm client, runs the publish gate with veraPDF, the consumer resolution smoke test, npm publish --provenance through Trusted Publishing, and an attest job with a CycloneDX SBOM and a build-provenance attestation; sample-regression.yml, verapdf.yml, docs.yml, codeql.yml, scorecard.yml, dependency-review.yml and audit.yml complete the set. Every action is SHA-pinned, every job starts with harden-runner, checks out with persist-credentials false and installs with --ignore-scripts; the rulesets require five status checks and make release tags immutable; the two CRLF workflow blobs are stored as LF. tests/tools/workflows.test.ts locks all of it.
Committed .claude/settings.json (no attribution trailer, Read denied on generated files, HITL commands denied for Bash and PowerShell), the fail-closed guard hook shared with the siblings, rules generated from .github/instructions (three new instruction files: testing, security, release), the release-audit skill with this renderer's blind spots, ai-governance.json with the claude_code block and a split sources / on_demand, the issue-draft template and the maintenance issue template. CLAUDE.md imports AGENTS.md, which is rewritten to the sibling shape under 120 lines.
…are and the release templates docs/assets/ecosystem.json is the single source of every count and version; scripts/verify-docs.ts holds 27 rules against it and the source tree (scripts/lib/react-surface.ts reads the registry tables, the error codes, the schema subjects and the sample index from text), including the React-specific registry-parity, lint-rule-parity, error-code-parity, sample-index-parity, engine-version-token and peer-pin-parity; scripts/release-prepare.ts applies the version bump in one pass and scaffolds the release note and the PR draft from the two new templates.
…ity snapshot tests/regression/engine-surface.json maps the 85 bullets of pdfnative 1.8.0's changelog (ids shared with pdfnative-mcp and pdfnative-cli) to the tests and samples that exercise them through the renderer, or to a waiver with a reason; the test holds every reference to the tree and fails when the peer pin moves without the matrix. tests/regression/compat/v1.2.0/ freezes the published 1.2.0 samples, compiled against the current src/ by npm run typecheck:compat.
… 27 scripts New samples text/typography-engine, text/typography-french (demo-language: fr), layout/print-pdfx4 (checked with the engine's validatePdfX), layout/cmyk, quality/reproducible and fonts/scripts-27; quality/diagnostics shows the nine diagnostic codes and a TYPOGRAPHY_FEATURE_INEFFECTIVE example; agent/compact-spec uses the new DocSpec fields; samples/README.md indexes every sample and documents the byte baseline.
… draft New guides docs/TYPOGRAPHY.md, docs/PRINT.md and docs/REPRODUCIBLE.md; README, llms.txt, the agent contract (reproducible output for agents, the grammar table, tier 5 validatePdfX), the knowledge base (reproducibility, module map, probes), LINTING (37 rules, 9 diagnostics), RECIPES (validatePdfX, the creation-date pin, the compressor seam), CHARTS, SERVER, AI_GOVERNANCE (the Claude Code layer), CONTRIBUTING (the gate, the baseline, PDF/A and PDF/X, release, branch protection), SECURITY (supported lines, reproducible builds, supply chain), SUPPORT, ROADMAP, the [1.3.0] changelog entry and ladder, release-notes/v1.3.0.md and release-notes/draft/PR-v1.3.0.md; the non-ASCII filename fixture is renamed to an English one.
…itories The overrides set is the siblings' (esbuild, js-yaml 4.3.2); nanoid and brace-expansion resolve to their fixed releases through the refreshed lockfile (npx [email protected] install, the command the sibling CLAUDE.md files prescribe under npm 10.9), like pdfnative 1.8.0, pdfnative-cli 1.5.0 and pdfnative-mcp 1.7.0. npm audit --audit-level=high: 0 vulnerabilities.
…embedding a value CodeQL (js/incomplete-sanitization) flagged the changelog-ladder rule, which escaped dots only. Every interpolated RegExp of scripts/verify-docs.ts and scripts/lib/react-surface.ts now goes through escapeRegExpLiteral(), which escapes the metacharacters and the backslash; a unit test pins the helper.
declared.tests in docs/assets/ecosystem.json, and every document quoting it (README, AGENTS.md, the release note, the PR draft), follow the count the gate measures.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
release: v1.3.0 — Typography, CMYK & PDF/X-4, reproducible output, and the hardened repository
Summary
For an author writing JSX, 1.3.0 exposes every authoring capability of pdfnative 1.8.0: the
typography engine as a
<Document typography>prop (twelve opt-in keys — paragraphs that splitunder widow and orphan rules, headings kept with what follows, justification with optical margins,
unit and short-word binding, French punctuation spacing, kerning, OpenType features, exact base-14
metrics) with
align="justify",keepWithNextandsplittableon the blocks; CMYK colours on everycolour position and colour bars on the printer's marks; the PDF/X-4 conformance claim
(
pdfx="pdfx4") with CMYK and Gray output intents; a pinnablecreationDatethat makes the samedocument render to the same bytes on every host; and 27 bundled Unicode scripts through
resolveFonts. Twelve new lint rules (37 in all, twenty pre-empting an engine throw with theengine's own message) turn every new constraint into a finding before it is a throw.
For an agent emitting a
DocSpec, the same four document-level fields (typography,pdfx,outputIntent,creationDate) and block options arrive through the JSON Schema andcapabilityManifest()(specFields, six new entry points), withE_INPUTclassification of theengine's input errors and a new agent-contract section on reproducible output. Nothing was removed
or narrowed: four superset proofs run on every push.
For the repository, this release adopts the engineering standard of pdfnative 1.8.0, pdfnative-cli
1.5.0 and pdfnative-mcp 1.7.0 without reinventing it: one gate (
scripts/gate.ts), a hermeticsample generator and a byte baseline held on Linux, Windows and macOS, an in-process PDF/X-4 gate
beside the blocking veraPDF gate, docs-as-code (
docs/assets/ecosystem.json+verify:docs, 27rules), nine hardened workflows with five required checks, Trusted Publishing with a CycloneDX SBOM
and a build-provenance attestation,
release-prepare, the engine-surface matrix, and the ClaudeCode layer. The one extension neither sibling needs — publint and
@arethetypeswrong/cliin thegate — exists because this is the package that ships a dual ESM + CJS
exportsmap withper-condition types.
Counts (
docs/assets/ecosystem.json): 19 components, 14 block kinds, 18 DocSpec fields (14 → 18),37 lint rules (25 → 37), 6 error codes (unchanged); samples in the baseline 0 → 38 (the baseline is
created by this release); conformance corpus 11 → 16 files; tests 292 → 811 across 43 files.
What changed
Authoring surface (
src/components.tsx,src/reconciler/serialize.ts,src/spec/,src/registry.ts)DocumentProps/DocSpec:typography(TypographyOptions, folded whole intolayout.typography),pdfx('pdfx4'),outputIntent(CustomOutputIntent, now CMYK/Gray too),creationDate(Date | stringin JSX, ISO string in JSON; an unparseable string isE_INPUT).resolveLayout()keeps returningundefinedwhen nothing is set.HeadingProps.keepWithNext;ParagraphProps.align: ParagraphAlign(Align | 'justify'),keepWithNext,splittable; DocSpec['h1', text, { keepWithNext }],['p', text, { align, keepWithNext, splittable }].Alignstays three-valued.Coloradmits the four-element CMYK tuple;PdfCmykTuple/PdfCmykStringand nine more types re-exported.src/registry.ts:DOC_SPEC_FIELDS(compile-time locked tokeyof DocSpec;validateSpecand the manifest derive from it), twelveLINT_RULESappended, Document summary updated.src/spec/schema.ts:$defs.color(hex, RGB tuple, CMYK tuple, operand string) at every colour site,$defs.typography(twelve keys with bounds and enums),$defs.outputIntent,pdfxconst,creationDateformat: date-time,colourBarsin marks,specFieldsin the manifest schema.TypographyPropsCoverTypographyOptions.Linting, diagnostics and errors (
src/lint.ts,src/errors.ts,src/doctor.ts,src/manifest.ts)L_OUTPUT_INTENT_PROFILE(ICC header read from the bytes),L_PDFX_TARGET,L_PDFX_TAGGED_CONFLICT,L_PDFX_ENCRYPTED,L_PDFX_OUTPUT_INTENT,L_PDFX_TRAPPED_UNKNOWN,L_PDFX_BOXES(the engine's six throws, same order, same wording — a parity test holds each),L_PDFX_NO_FONTS,L_PDFX_ANNOTATIONS,L_TYPOGRAPHY_INEFFECTIVE,L_PRINT_COLOUR_BARS,L_CMYK_INTENT_MISMATCH;L_OUTPUT_INTENT_IGNOREDsilent underpdfx.ENGINE_INPUT_ERROR_PREFIXES(exported):toErrorEnvelopeclassifies the engine's input errors asE_INPUT;ErrorCodeunchanged.doctor():REQUIRED_ENGINE = '1.8.0', probes newest-first (setDefaultCreationDate→validatePrintOptions→estimateChartHeight); a 1.7.x engine is named.capabilityManifest():contract.engine '^1.8.0', six entry points (setDeflateRawImpl,wrapZlib,setDefaultCreationDate,getDefaultCreationDate,setHyphenationProvider,getHyphenationProvider— the engine's own functions, identity-tested),specFields.src/core-bridge/index.ts: the six helpers andPDF_X_CONFORMANCE_TARGETS; nothing byte-level (golden rule 7:validatePdfXstays an engine import).Tooling (
scripts/)gate.ts— profiles--fast/--ci/--publish,--only,--from,--json,--require-all; inline stepsdist-check,dist-probe,bundle-smoke,pack-check(npm pack --dry-runfile list, publint,@arethetypeswrong/cli).generate-samples.ts(one child process per sample:node --import tsx --import helpers/pin-creation-date.mjs, cwd undertest-output/samples/,TZ=UTC, instant pinned),verify-samples.ts(chained baseline,--update/--strict/--json),lib/sample-plan.ts,lib/sample-fingerprint.ts.generate-pdfa-corpus.ts,validate-pdfa.ts,validate-pdfx.ts(TypeScript; the.mjspair removed),lib/pdfa-corpus.ts(16 entries, both doors, three negative canaries),lib/pdfx.ts,lib/verapdf.ts,lib/synthetic-icc.ts.verify-docs.tsoverlib/react-surface.ts(27 rules),release-prepare.ts,build-claude-rules.ts,install-git-hooks.mjs,helpers/hermetic.ts+helpers/tz.ts+helpers/io.ts,scripts/README.md.CI / repository (
.github/, root)ci.yml(cion Node 22/24 + theosjob on windows-latest and macos-latest, the same gate with--require-all,npm auditoutside it),publish.yml(tag = version, npm 11.19.1 pinned, veraPDF, the publish gate,npm pack --dry-run, the consumer resolution smoke test,npm publish --provenance, theattestjob with SBOM + provenance),sample-regression.yml,verapdf.yml,docs.yml,codeql.yml,scorecard.yml,dependency-review.yml,audit.yml— every action SHA-pinned, harden-runner first,persist-credentials: false,npm ci --ignore-scripts..github/actions/setup-verapdf+.github/checksums/,.github/rulesets/main.json(five required checks) andtags.json,dependabot.yml,pull_request_template.md(checklist verbatim from CONTRIBUTING),ISSUE_TEMPLATE/maintenance.md,bug_report.md(+doctor())..gitattributes(LF; the two CRLF workflow blobs renormalised),.npmrc,.node-version,.editorconfig,.githooks/,tsconfig.scripts.json,vitest.config.ts(TZ=UTC,pool: 'forks', timeouts, reporters),package.json(scripts,packageManager: [email protected]like the siblings,typesVersionsfor theclientsubpath, the siblingoverridesset —esbuild,js-yaml4.3.2 — with the lockfile refreshed for the nanoid and brace-expansion advisories, vitest 4.1.11, devDepstsx/esbuild/publint/@arethetypeswrong/cli, keywords),.gitignore.Agent layer
.claude/settings.json(attribution.commit: "", denies for both shells, Read denied on generated files),.claude/hooks/guard.mjs(+.d.mts),.claude/rules/*.md(generated),.claude/skills/release-audit/(five files, React blind spots),.github/ai-governance.json(sources/on_demandsplit,claude_codeblock),.github/instructions/(+ testing, security, release; descriptions on the existing three),.github/drafts/{README,TEMPLATE}.md,CLAUDE.md(@AGENTS.md+ addendum),AGENTS.md(≤ 120 lines),.github/copilot-instructions.md.Tests, samples and baselines
tests/{typography,color,pdfx,reproducible,fonts-27}.test.tsx,tests/doctor.test.ts,tests/{api-surface,schema-superset,manifest-superset}.test.ts,tests/regression/{samples,reproducible-build,engine-surface}.test.ts,tests/tools/{gate,workflows,hermetic-env,verify-docs,react-surface,release-prepare,guard,agent-config,build-claude-rules,markdown-anchors,pdfx,verapdf,json-schema-lite}.test.ts;tests/lint.test.tsxgains oneitper new rule plus its clean case and the engine-message parity.tests/regression/baselines/{api-surface,doc-spec.schema,manifest}.v1.2.0.json, eight fixture specs,tests/regression/compat/v1.2.0/samples/(typecheck:compat),tests/regression/engine-surface.json(85 items).tests/regression/baselines/samples.sha256.json— 38 entries, allsince: "1.3.0", provenance note recorded;fonts-prop/fonts-prop-syncidentical by design.text/typography-engine.tsx,text/typography-french.tsx(demo-language: fr),layout/print-pdfx4.tsx,layout/cmyk.tsx,quality/reproducible.tsx,fonts/scripts-27.tsx;quality/diagnostics.tsx,agent/compact-spec.ts,agent/visual-verify.tsxupdated.Documentation
docs/TYPOGRAPHY.md,docs/PRINT.md,docs/REPRODUCIBLE.md; README,llms.txt,docs/AGENT_CONTRACT.md(§8 reproducible output, the grammar table, tier 5validatePdfX),docs/KNOWLEDGE_BASE.md(§6a Reproducibility, module map, probes),docs/LINTING.md,docs/RECIPES.md(three recipes),docs/CHARTS.md,docs/SERVER.md,docs/AI_GOVERNANCE.md§8,CONTRIBUTING.md,SECURITY.md,SUPPORT.md,ROADMAP.md,samples/README.md,CHANGELOG.md([1.3.0]+ ladder, the[0.2.0]rung fixed),CITATION.cff,release-notes/{TEMPLATE,PR_TEMPLATE}.md, this draft.Verification
What actually ran on the release branch (Windows 11, Node 22.17.0, veraPDF greenfield 1.30.2 with JDK 13). Reproduce with:
Expected behavior: 14 steps PASS, 0 skipped, in about eight minutes.
npx tsx scripts/gate.ts --publish --require-alltypecheck:all46.9 s,lint,build,dist-check,dist-probe,bundle-smoke,pack-check7.1 s,test:generate58.3 s — 38 samples,test:coverage102.6 s — 811 tests,verify:docs,verify:samples,corpus:pdfa,validate:pdfx,validate:pdfa94.5 s)npm run test:coverage— testsnpm run test:coverage— coveragenpm run build && npm run test:generate && npm run verify:samplesnpm run corpus:pdfa && npm run validate:pdfanpm run validate:pdfxnpm run verify:docsnpm audit --audit-level=highpack-check(publint, @arethetypeswrong/cli).,./clientand./package.jsonresolve for node10, node16 (CJS and ESM) and bundlerIndependent audit:
/release-audit release-notes/v1.3.0.md v1.2.0— PENDING (the maintainer runs the skill; the ledger lands under.audit/1.3.0/).Zero-breaking-change audit
tests/api-surface.test.tsagainsttests/regression/baselines/api-surface.v1.2.0.json(captured from the untouched 1.2.0 tree before any edit)ENGINE_INPUT_ERROR_PREFIXES, eleven types,ParagraphAlign; the 1.3.0 surface snapshottednpm run typecheck:compat— the frozen v1.2.0 samples (git archive v1.2.0 samples, imports pointed at the currentsrc/) compiled against the 1.3.0 sourcetests/schema-superset.test.tsagainstdoc-spec.schema.v1.2.0.json; eight 1.2.0 fixture specs under both schemas andvalidateSpec$iddiffers by the version onlytests/manifest-superset.test.tsagainstmanifest.v1.2.0.jsoncontract.enginegit diff --stat v1.2.0 -- tests/__snapshots__/tests/agent.test.tsx,tests/manifest-superset.test.tsE_*andV_*unchanged/ID/ producer normalised (scratchpad/compare-1.2.0.mts)kitchen-sink.jsonandprint-tagged.jsondiffer — both drawprint.marks(the inherited 0.5 pt clearance fix, declared in Upgrade note 1)tests/manifest-superset.test.tsrunslintSpecover the 1.2.0 fixturesreport.okunchangedtests/version.test.ts,tests/doctor.test.ts^1.8.0is the one install-time change; a 1.7.x engine is reported by nameOutput changes and rebaseline
release-notes/v1.3.0.md.tests/regression/baselines/samples.sha256.json: created by this release — 38 entries anchored at 1.3.0 withnpx tsx scripts/verify-samples.ts --update; the provenance note records the double generation and the identical pair. No earlier baseline exists to rebaseline from.release-notes/v1.3.0.md.Out of scope (tracked in ROADMAP.md)
validatePdfXre-export (golden rule 7), apdfnative-reactMCP server (dropped), a React Native renderer, an external visual tier, PDF/X-1a / X-3 / X-4p / PDF/A-4 (engine "not yet"; upstream limitpdfx-single-target), a hyphenation-provider sample (upstream limitno-bundled-hyphenation), harden-runner block mode.Maintainer steps after merge
Agents stop at this draft; everything below is done by the maintainer (
.github/AGENT_RULES.md).git addunder the new.gitattributes); no separate renormalisation commit is needed —git ls-files --eolreports noi/crlf.ci (22),ci (24),os (windows-latest),os (macos-latest)andsample-regression(the first run on Windows and macOS), merge.v1.3.0on the merge commit and publish the GitHub Release (titlev1.3.0 - Typography, CMYK & PDF/X-4, reproducible output, pdfnative 1.8, body =release-notes/v1.3.0.md).npm-publishenvironment and bind the npm Trusted Publisher to it, then approve:publish.ymlre-runs the publish gate and publishes through npm Trusted Publishing, and attaches the SBOM and the attestation to the release. Confirm withnpm view pdfnative-react version..github/rulesets/main.json,.github/rulesets/tags.json) — CONTRIBUTING §Branch protection.pdfnative-reactentry ofdocs/assets/ecosystem.jsonin pdfnative, pdfnative-cli and pdfnative-mcp (1.3.0, peer^1.8.0), the React cells of pdfnative'sdocs/data/surfaces.jsonanddocs/guides/react.md./release-audit release-notes/v1.3.0.md v1.2.0before tagging if not already done; fix what it confirms.Checklist
npm run gatepasses — the CI profile in one command (npm run gate:fastfor a quick loop while iterating; PowerShell swallows a bare--, so callnpx tsx scripts/gate.ts --fastthere)npm run test)npm run typecheck:all— src, tests, samples, scripts and the v1.2.0 compatibility snapshot)npm run lint)vitest.config.tsmust not regress)anytypes introducedreact-reconcilerstays the only one;pdfnativeandreactstay peers)src/components.tsx,src/reconciler/serialize.ts,src/spec/{types,compile,schema}.ts,src/registry.ts,tests/(serialization, DocSpec parity, the golden snapshot read before-u),samples/andscripts/lib/sample-plan.ts,samples/README.md,llms.txt,README.md,docs/AGENT_CONTRACT.mdnpm run build && npm run test:generate && npm run verify:samples && npm run corpus:pdfa && npm run validate:pdfx && npm run validate:pdfapasses locally (veraPDF installed; new claiming corpus entries bumpdeclared.pdfaSamples/declared.pdfxSamples; an intended output change is rebaselined withnpx tsx scripts/verify-samples.ts --updateand declared in the release note).claude/changed:npm run verify:docspassestests/api-surface.test.ts,tests/schema-superset.test.ts,tests/manifest-superset.test.tsandnpm run typecheck:compatare green), or documented and versioned accordinglyCHANGELOG.mdupdated (Unreleased section) if user-facing changesrelease-notes/vX.Y.Z.mdand this draft written, andnpx tsx scripts/gate.ts --publish --require-allpasses locally, which runs every individual gate:typecheck:all,lint,build,dist-check,dist-probe,bundle-smoke,pack-check,test:generate,test:coverage,verify:docs,verify:samples,corpus:pdfa,validate:pdfx,validate:pdfarelease-notes/vX.Y.Z.mdand the CHANGELOG entry for X.Y.Z say the same things as this bodyCo-Authored-Bytrailer and no "generated with" footer anywhere on the branchCompliance report
no_new_runtime_dependency_confirmeddependenciesis stillreact-reconcileralone;tsx,esbuild,publint,@arethetypeswrong/cliare devDependenciesreproduction_commandnpx tsx scripts/gate.ts --publish --require-allreproduction_resultduplicate_search_performedaffected_packagesidentity_reminder_shown