Repository navigation
feat(release): pdfnative-react 1.4.0 on pdfnative 1.9.0 - #36
Merged
Merged
Conversation
The engine-alignment release: right-to-left documents (direction), spot
colours (print.spotColours, { spot } / { inks }), the joint PDF/A-2 + PDF/X-4
claim, per-value chart colours and optional series labels, JPEG 2000 images,
32 Unicode scripts; four lint rules, thirteen diagnostic codes, the 1.9.0
doctor probe; compat:previous (the v1.3.0 suite replayed), frozen 1.3.0
captures, workflow lint, the four-job release pipeline, seven required checks.
Release note: release-notes/v1.4.0.md. Released 2026-11-01.
Audit corrections folded in (two auditors, one adversarial verifier; ledger
under .audit/1.4.0/, git-ignored):
- spec: $defs.processColor for outline bookmark colours (the engine refuses a
spot value there); minLength on a spot ink name; descriptions on title,
footerText, fontEntries and fieldType; the PNG and layout.colors limits.
- errors: nine prefixes join ENGINE_INPUT_ERROR_PREFIXES (the engine's colour
input, the image decoders, the PDF/A-1b watermark) — E_INPUT, not E_RUNTIME.
- compat: tests/agent.test.tsx of 1.3.0 replayed with three locks deselected;
an allow-list entry may cite several ledger entries.
- tests: the schema-superset walk enters $defs and every oneOf/anyOf branch;
one release date held across CITATION.cff, ecosystem.json and the note;
the obsolete api-surface snapshot key removed.
- tooling: one STAMPED_FILES list for verify:docs and release-prepare, now
covering PRINT, REPRODUCIBLE and TYPOGRAPHY.
- docs: tagged: true documented as the engine's default PDF/A-2b claim;
layout.colors no longer listed as a colour position; SECURITY.md describes
the release jobs as they are and states the engine-peer and type-widening
rules; Upgrade steps 7 and 8; the RECIPES entries the note named.
- ci: Dependabot covers .github/actions/*; issue chooser with the private
advisory link; stale comments.
|
You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool. What Enabling Code Scanning Means:
For more information about GitHub Code Scanning, check out the documentation. |
Two renders of the same unpinned document, launched together by the ETag and the streamed-vs-buffered tests, can straddle a second boundary on a slow runner — the macOS leg of ci did on 2026-11-01 — and differ in /CreationDate and the trailer /ID, so the derived ETag differed. The fixtures now carry a pinned creationDate; the determinism the tests assert is real, not timing.
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.4.0 — Right-to-left text, spot colours, the joint PDF/A + PDF/X claim, JPEG 2000, 32 scripts
Summary
For an author writing JSX:
<Document direction="auto">sets Arabic, Hebrew, Persian or Urdu paragraphs from the rightmargin (per-paragraph
directionoverride,/ActualTexton every right-to-left run);print.spotColoursdeclares namedinks and
{ spot, tint }/{ inks }paint with them on every colour position, including one ink per bar throughChartSeries.colors;tagged="pdfa2b"combines withpdfx="pdfx4"in one file;<Image>andwatermark.imagetakeJPEG 2000; a chart series may go unlabelled; five more Indic scripts (32 in all) load through
resolveFonts. Everychange is opt-in and reaches both doors through
src/registry.ts.For an agent emitting a DocSpec: the 19th top-level field
direction, the paragraph optdirection,print.spotColoursand the two colour object forms in
$defs.color, seriescolorswithlabeloptional,imgbytes that may be JP2 —all described in the schema; four lint rules that are the engine's throws one tier earlier (
L_SPOT_UNDECLARED,L_SPOT_INK_MIX,L_CHART_SERIES_COLORS,L_PDFA_JPX_IMAGE),L_PDFX_TAGGED_CONFLICTnarrowed to the two levels theengine still refuses, 13 diagnostic codes documented (
TEXT_GLYPH_NOT_COVEREDsurfaces what used to be a silent box),doctor()at the 1.9.0 floor,toErrorEnvelopetotal on hostile thrown values.For the repository: the v1.3.0 test suite replayed against the current sources (
compat:previous, a required check),frozen v1.3.0 captures beside the v1.2.0 ones, a
workflow lintcheck (zizmor + actionlint), a guard → build → publish →attest release pipeline with blocked egress and a content-pinned npm client, CodeQL on the workflows, a Node 26 advisory
job, Dependabot cooldowns, fast-check property tests, every dev-tree advisory cleared, the Scorecard and CodeQL findings
triaged, the engine-surface matrix rebuilt for 1.9.0 (72 bullets). ROADMAP items delivered: the engine-surface matrix
kept per release (now a shipped process),
harden-runnerblock mode on the release pipeline.Counts (
docs/assets/ecosystem.json): 19 components, 14 block kinds, 19 DocSpec fields (18 → 19), 41 lint rules(37 → 41), 6 error codes unchanged; samples in the baseline 38 → 42; conformance corpus 16 → 20 files (16 PDF/A,
5 PDF/X, one file claims both); tests 811 → 949 across 50 files (43 → 50); 27 → 32 Unicode scripts;
9 → 13 diagnostic codes.
What changed
Authoring surface (
src/components.tsx,src/reconciler/serialize.ts,src/spec/,src/registry.ts)DocumentProps.direction/ParagraphProps.direction(engineTextDirection);resolveLayout()foldsdirectionwhole; the paragraph
directionreaches the block only when set;DocSpec.direction(appended toDOC_SPEC_FIELDS),specToElementforwards it; schemadirectionat both levels with the engine enum.ColoradmitsPdfSpotColorandPdfInkMix;$defs.colorgains the two object branches;print.spotColoursdescribedin the schema;
TextDirection,PdfSpotColor,PdfInkMix,SpotColourDefre-exported (core-bridge→types.ts→ barrel).required: ['values'],colorsarray;ChartProps.seriesJSDoc; the engine type passes through.<Image>/['img']/assets.tsdocument JPEG 2000 (JP2 or J2K,/JPXDecode, PDF 1.5);BLOCK_REGISTRY.image.summary.tagged/pdfxJSDoc and schema descriptions: the joint PDF/A-2 + PDF/X-4 claim;Documentsummary namesdirection.Linting, diagnostics and errors (
src/lint.ts,src/errors.ts,src/doctor.ts,src/manifest.ts)L_CHART_SERIES_COLORS,L_SPOT_UNDECLARED,L_SPOT_INK_MIX(errors; the engine messages verbatim),L_PDFA_JPX_IMAGE(warning; channel facts from the engine's
parseJPX, bridge-internal);L_PDFX_TAGGED_CONFLICTfires forpdfa1b/pdfa3bonly with the two engine messages;L_PRINT_BOXEScarries thespotColoursdeclaration errors;L_CMYK_INTENT_MISMATCHcounts CMYK-alternate inks;colourPositions()walksseries.colors;seriesName()names anunlabelled series
Series Nin every message. 41 rules: 23 pre-empt a throw, 6 mirror a diagnostic.ENGINE_INPUT_ERROR_PREFIXES+=Spot colour,Ink mix;toErrorEnvelopetotal (object tag whenString()throws).doctor():REQUIRED_ENGINE1.9.0, proberesolveBidiLevelsnewest-first (1.8.x graded down);contract.engine^1.9.0.Tooling (
scripts/)scripts/run-compat.ts(npm run compat:previous): the v1.3.0 suite as tagged against the currentsrc/, driven bytests/regression/compat/allow-v1.3.0.json(15 exclusions with reasons; C6 and C14 for the behaviour changes); gatestep
compat:previous(publish profile) aftertest:coverage.scripts/lib/jpx-fixture.ts(minimal JP2 / J2K codestreams, shared by tests, the sample and the corpus);scripts/lib/pdfa-corpus.tsClaimgains'both'(claimsPdfA/claimsPdfX); four corpus entries (jpx-pdfa1b.pdfis a tracked validator gap: ISO 19005-1 forbids JPXDecode, the engine reports
PDFA1_JPX_IMAGE, veraPDF 1.30.2 accepts);generate-pdfa-corpus.tsandreact-surface.tscount the dual claim under both standards.scripts/verify-docs.ts:node-pin-parityexemptsnode-current.ymlwhile its Node major exceeds.nvmrc.CI / repository (
.github/, root)publish.ymlrewritten as guard → build → publish → attest (blocked egress on guard / publish / attest, npm client bySHA-512 integrity, consumer smoke test with lockfile-pinned peers in
build, CycloneDX + SPDX SBOMs, fetch-back and digestcomparison,
attest-build-provenance,gh release upload --clobber);ci.ymlgainscompat-previousandworkflow lint(zizmor 1.30.1, actionlint 1.7.12 SHA-256-verified), drops
paths-ignoreand the macOS harden-runner carve-out;codeql.ymlanalysesactions+javascript-typescriptwith job-level permissions and no path filter;node-current.yml(Node 26, advisory);
scorecard.ymlv2.4.4; every audit-mode harden-runner carries a dated reason; checkout v7.0.1 /setup-node v7.0.0 / download-artifact v8.0.2;
setup-verapdfhands its directory back as thehomeoutput..github/rulesets/main.json: seven required contexts;.github/dependabot.yml: 7-day cooldowns, grouped action bumps,versioning-strategy: increase-if-necessary,@eslint/jsmajors andreact-reconciler/@types/react-reconcilerminors ignored;
CONTRIBUTING.md,.github/pull_request_template.md,release-notes/PR_TEMPLATE.mdname the new stepand the seven checks.
package.json: version 1.4.0, peer + devpdfnative^1.9.0, vitest /@vitest/coverage-v8^4.1.12, jsdom^29.1.1,@testing-library/domdeclared, fast-check added (dev); description and keywords refreshed (103 keywords);CITATION.cff1.4.0 + keywords;SECURITY.md(advisory URL, contact, timeline, supported runtimes, compatibilitypromise, accepted Scorecard findings);
ROADMAP.md1.4.0 section and refreshed Later list.Agent layer
AGENTS.md/CLAUDE.md(counts, engine 1.9.0, both frozen captures,compat:previous, Windows notes under the16 KiB budget),
.github/instructions/*(direction sugar, spot colour forms, both snapshots, property tier, the sevenchecks, the four-job pipeline, the compat ledger rule) →
.claude/rules/*regenerated;.claude/skills/release-auditblind spots (subset tag, spot declaration, the joint claim proven twice,
TEXT_GLYPH_NOT_COVEREDunder strict, thecompat allow-list as a ledger);
docs/AGENT_CONTRACT.md(1.9.0 floor and probe, 19 fields, 41 rules, 13 codes, thespot-colour
E_INPUTclassification);llms.txt.Tests, samples and baselines
direction,spot-colours,chart-series,jpx-image(+tests/helpers/jpx-fixture.ts),layout-190,diagnostics,fonts-32(renamed fromfonts-27),property-validate;pdfxgains the dual claim and the per-levelrefusals;
compile-snapshotgains thesinceOneNinefixture (one snapshot added, the 1.2.0 and 1.3.0 ones unchanged);registry,schema,color,agent,doctor,version,lint,pdfuaupdated;api-surface,schema-superset,manifest-supersetrun over the 1.2.0 and 1.3.0 captures;tests/tools/workflows,gate,verify-docs,react-surfacefollow the tooling;tests/regression/engine-surface.jsonrebuilt for 1.9.0.text/rtl-direction,media/image-jpx,layout/print-spot-colours,layout/print-dual-pdfa2b-pdfx4,fonts/scripts-32(replacingscripts-27);charts/charts-v2andquality/diagnosticsextended;samples/README.md.samples.sha256.jsonre-anchored (15 entries at 1.4.0, 27 carried forward; provenance rewritten);api-surface.v1.3.0.json,doc-spec.schema.v1.3.0.json,manifest.v1.3.0.json,tests/regression/compat/v1.3.0/.Documentation
Engineering, Ecosystem with zipnative / pkinative),
llms.txt,docs/AGENT_CONTRACT.md,docs/KNOWLEDGE_BASE.md,docs/LINTING.md,docs/PRINT.md(§Spot colours, the joint claim),docs/CHARTS.md,docs/RECIPES.md(link annotations,extractText+onStreamError,composeLtvData,decodePdfTextString),docs/REPRODUCIBLE.md,docs/TYPOGRAPHY.md,SECURITY.md,CONTRIBUTING.md,ROADMAP.md,CHANGELOG.md,CITATION.cff,release-notes/v1.4.0.md.Verification
What actually ran on the release branch (Windows 11, Node 22.23.2, veraPDF 1.30.2):
npx tsx scripts/gate.ts --publish --require-allnpm 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:pdfxpdfx4-nofonts.pdf)npm run compat:previousnpm run verify:docsnpm audit --audit-level=high[email protected]under eslint 9, no fixed 3.x release)pack-check(publint, @arethetypeswrong/cli)Independent audit (2026-11-01, the release-audit protocol run at the maintainer's request: Auditor A — claims vs code,
46 rows; Auditor B — docs, agent surfaces, engine 1.9.0 coverage, posture, autonomy pass, 57 rows; one adversarial
verifier re-deriving every row): 0 blockers, 4 majors, 25 minors, 3 notes confirmed; 2 rows rejected (figures the
orchestrator reproduces itself), 6 duplicates. Every confirmed finding is fixed on this branch — the four majors: a spot
colour on an outline bookmark passed the schema and lint and surfaced as
E_RUNTIME(now$defs.processColor+E_INPUT);layout.colorswas listed as a colour position the block-flow renderer never reads (documented, the sampleline dropped without moving a byte);
tagged: trueis the engine's default PDF/A-2b claim and was described as plaintagging (documented; the lint widening is a declared 1.4.1 item); an alpha-channel PNG was refused as
E_RUNTIMEwithno surface naming the limit (now
E_INPUTand stated everywhere). Verdict GO; ledger and verdict under.audit/1.4.0/(git-ignored); a previous-day verifier pass (verifier-final.md, 14 criteria, GO) sits beside them.Zero-breaking-change audit
tests/api-surface.test.tsagainstapi-surface.v1.2.0.jsonandapi-surface.v1.3.0.json— 0removed; 4 type names added (
TextDirection,PdfSpotColor,PdfInkMix,SpotColourDef), 0 runtime exports added.npm run typecheck:compatcompiles the frozen v1.2.0 and v1.3.0 samples against the currentsrc/— 0 errors.tests/schema-superset.test.tsover both captures — every property, enum member and block branch kept;nothing became required. The walk now enters
$defsand everyoneOf/anyOfbranch, so the chart seriesrequiredchange (labelbecame optional — a widening) and the newoutline[].colordefinition ($defs.processColor,the 1.3.0 forms exactly: hex, RGB, CMYK) are inside the proof.
tests/manifest-superset.test.tsover both captures — every component, entry point, error code andlint rule kept with the same severity; the one accepted contract delta is
engine^1.8.0→^1.9.0.npm run compat:previous— the v1.3.0 suite passes against 1.4.0; the four entries that carry a ledger nameC6 (lean subsets: byte-size assertions in
fonts-27andpdfua) and C14 (the joint claim:L_PDFX_TAGGED_CONFLICTno longer fires for
pdfa2b, inpdfxandlint;pdfxcites both);tests/agent.test.tsxis replayed with onlyits three inventory locks deselected (the audit found it excluded whole).
git diff --stat v1.3.0 -- tests/__snapshots__/— additions only (one compile-snapshot fixture, theapi-surface snapshot key moved into its describe; the obsolete copy removed).
E_INPUTprefixes: the engine's colour input (Spot colour,Ink mix,Invalid ink mix,Invalid tint,Invalid spot colour,An outline colour), the image decoders (parseImage:,parsePNG:,parseJPEG:,parseJPX:) andWatermark transparency; alayout.strictescalation staysE_RUNTIME, as documented.Color,ChartSeries.label, theLintRuleCode/DocSpecFieldunions —SECURITY.mdnow states the rule (engine types re-exported may widen; the peer floor followsthe engine minor).
Output changes and rebaseline
carries no translucent watermark. Otherwise they move once, inherited from the engine (ledger C1–C3, C5, C6, C8, C9,
C11, C14, C20–C22, C25–C28): lean, compact, six-letter-tagged subsets; one text object per line;
/ActualTextspans;UAX chore(deps-dev): bump @eslint/js from 9.39.4 to 10.0.1 #9; deeper rows for deep descenders; paginated tables of contents; the page transparency group.
tests/regression/baselines/samples.sha256.json: 10 entries re-anchored at 1.4.0 withnpx tsx scripts/verify-samples.ts --update(charts/charts-v2— sample edit;fonts/fonts-prop,fonts/fonts-prop-sync,layout/page-setup,layout/print-pdfx4,layout/watermark-header-footer,text/math,text/typography-engine,text/typography-french— subsets, C6/C21/C25/C28;layout/cmyk— transparency group, C11), 1 renamed(
fonts/scripts-27→fonts/scripts-32), 4 new, 27 unchanged (15 entries atsince: 1.4.0, 38 → 42) — reason inthe manifest's
provenancenote.samples/layout/cmyk.tsxdrops itslayout.colorsline without moving a byte, whichis the proof that the block-flow renderer never read it.
release-notes/v1.4.0.md.Out of scope (tracked in ROADMAP.md)
pdfx-single-target); a hyphenation dictionary(
no-bundled-hyphenation); PDF/UA-1 basics (pdfnative 1.9.1).runtimesjob (Deno / Bun / Chromium), ClusterFuzzLite,docs/assets/api.json,llms-full.txt, the eslint 10 migration.docs/RECIPES.md.Dependabot pull requests and security alerts (maintainer disposition)
Every open Dependabot pull request is superseded on this branch; close them after merge: #1 (codeql-action v4 — main
already pins v4.36.0), #7 and #30 (react-reconciler 0.33 / 0.34 — React 19 binding, KB §4; minors now ignored), #8 (jsdom
29 — done here), #9 (@eslint/js 10 — major now ignored), #17 (superseded in 1.3.0), #19 (checkout v7.0.1 — pinned here),
#20 (upload-artifact v7.0.1 — already on main), #21 (scorecard-action v2.4.4 — pinned here), #22 (setup-node v7.0.0 —
pinned here), #34 (dev group — applied here without narrowing the
reactpeer), #35 (source-map-js 1.2.2 — done here).Dependabot alerts #12–#20 are fixed by the lockfile. Code-scanning: #26 fixed (
verify-docs.test.ts); #18 fixed(codeql job-level permissions); #23 and #24 fixed structurally (publish pipeline); #25 fixed (
SECURITY.md); #15 clearson the next Scorecard run; #13 addressed by the fast-check tier; #22 (attest
contents: write) and #12 (single-maintainercode review) are documented accepted findings — dismiss as "won't fix"; #11 (OpenSSF badge) and #1 (branch-protection
policy: reviews, admin bypass, linear history) are maintainer decisions.
Maintainer steps after merge
Agents stop at this draft; everything below is done by the maintainer (
.github/AGENT_RULES.md)..claude/settings.jsonadditions the session could not make itself (see the hand-over note): read-onlynpm view|ls|auditandgh pr view|diff|list/gh api repos/*inpermissions.allow..github/rulesets/main.jsonfirst (thecompat-previousandworkflow lintcontexts are new); wait forci (22),ci (24),os (windows-latest),os (macos-latest),compat-previous,workflow lintandsample-regression, merge.v1.4.0on the merge commit and publish the GitHub Release (titlev1.4.0 - Right-to-left text, spot colours, the joint PDF/A + PDF/X claim, JPEG 2000, 32 scripts, body =release-notes/v1.4.0.md).npm-publishenvironment:publish.ymlguard → build (the publish gate, the smoke test) → publish (npmTrusted Publishing) → attest (SBOMs and the attestation on the release). Confirm with
npm view pdfnative-react version.description and topics (see the hand-over note); optionally register at bestpractices.dev.
pdfnative-reactentry ofdocs/assets/ecosystem.jsonin the sibling repositories (pdfnative,pdfnative-cli, pdfnative-mcp — the engine's copy still says 1.3.0 /
^1.8.0); in the engine'sdocs/data/surfaces.jsonmarkspot-colours,images-jpeg2000andrtl-directionas supported by pdfnative-reactfrom 1.4.0, add the spot forms to the
cmyk-colourReact call andcolors/ optionallabelto thechartsReactnote, and add a row for the joint PDF/A-2 + PDF/X-4 claim. Two engine observations to raise there: the block-flow
renderer never reads
layout.colors, andparsePNGrefuses colour types 4 and 6 while the images guide describes an/SMasksplit.codeqlanddependency-reviewjoin the required contexts (ROADMAP)..audit/1.4.0/); re-run/release-audit release-notes/v1.4.0.md v1.3.0before tagging if anything changed since.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 and v1.3.0 compatibility snapshots)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/v1.4.0.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,compat:previous,verify:docs,verify:samples,corpus:pdfa,validate:pdfx,validate:pdfarelease-notes/v1.4.0.mdand the CHANGELOG entry for 1.4.0 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;fast-check,@testing-library/domand the bumps are devDependenciesreproduction_commandnpx tsx scripts/gate.ts --publish --require-allreproduction_resultduplicate_search_performedaffected_packagesidentity_reminder_shown