Reproducing a consumer or rendering issue

A useful report pins the source, package artifacts and environment, then shows the smallest command that fails. Use the reproduction issue form and keep expected behavior separate from diagnostics and observed output. Public npm publication, showcase deployment and an outside SaaS consumer remain pending; local packed consumers are the currently reproducible distribution evidence.

Pin the input and installation

For a registry installation after publication, record exact @publisle/* versions in package.json, commit the package-manager lockfile, and reproduce with the lockfile's clean-install command. Avoid latest, version ranges and workspace links in a pinned reproduction. Include the framework/adapter versions too. Do not use the unreleased workspace 0.0.0 placeholder as a published version.

For current repository work, record the commit, relevant uncommitted patch/new files, Node/package-manager versions and the unchanged source document. A commit alone cannot identify an uncommitted fix. Retain contract locks/bundles and their digests when the failure involves portable contracts. Preserve block IDs, versions, metadata, locale/direction, assets and diagnostic codes that affect the result. Reduce unrelated content until the same failure remains.

git rev-parse HEAD
git status --short
node --version
pnpm --version

State whether the failure comes from workspace source imports, packed artifacts or installed registry packages. For rendering, identify native or publication artifact delivery and whether JavaScript was enabled. Include the command, expected output, actual output, exit status and full relevant diagnostics. A screenshot can explain appearance, but source and commands reproduce it.

Reproduce the packed Core boundary

From the repository root, create retained artifacts outside the workspace:

PUBLISLE_DISTRIBUTION_ARTIFACTS=/tmp/publisle-reproduction pnpm test:distribution

The command prints a fresh publisle-distribution-* directory containing all 23 package tarballs, a plain Node consumer/ and an astro-consumer/. Keep the whole parent directory: lockfiles reference the sibling tarballs/ directory. Inside its consumer/ directory, run:

npm ci --ignore-scripts --legacy-peer-deps
node consumer.ts
node node_modules/@publisle/cli/dist/bin.js validate source.json
node node_modules/@publisle/cli/dist/bin.js export source.json --to pdf

The static consumer must prepare/render readable HTML and validation must pass. The final export command must exit 2 with Research plugin installation guidance: that is expected Core-only behavior. Capture npm ls --all --json when reporting a dependency leak; the gate rejects Research/template/CLI-plugin packages, citeproc and fflate in this Core installation.

Inside the sibling astro-consumer/ directory, rebuild the packed framework host:

npm ci --ignore-scripts --legacy-peer-deps
node node_modules/astro/bin/astro.mjs build

The Distribution workflow uploads this layout without node_modules as packed-consumer-and-tarballs. Download and extract the artifact, keep its relative directory layout, then use the commands above. The release guide explains package build/packing and the checks. A local packed Astro build does not establish a public showcase deployment.

Research and PDF reports

For a Research failure, include the template ID/version, selected engine, compiler backend and generated package manifest. Record a container's exact image ID or registry manifest/platform digests plus architecture, or native engine/font versions. Include explicit source assets and template data. A Docker tag alone is not a reproducible compiler identity.

Retain source/PDF/log/report evidence by setting PUBLISLE_RESEARCH_ARTIFACTS:

PUBLISLE_RESEARCH_ARTIFACTS=/tmp/publisle-research-reproduction pnpm test:research
PUBLISLE_RESEARCH_ARTIFACTS=/tmp/publisle-research-reproduction pnpm test:pdf-ua

These commands require the selected compiler and PDF tooling; the PDF/UA gate also requires the checksum-pinned veraPDF installation described in the accessibility guide. Include validator version, requested UA-1/UA-2 flavour and the complete XML report, not only a success line. A missing compiler or unsupported template is a capability result; it does not certify accessible output. The Research evidence matrix states the currently verified fixture scope.

Conformance and feedback

For a portable-outcome disagreement, identify the claimed role/test ID, supported subset, source fixture and exact expected classification/diagnostic codes. Run the relevant gate against the pinned checkout:

pnpm test:conformance:renderer
pnpm test:conformance:p0

P0 needs Chromium and the independent Python implementation; missing/skipped results fail. A failure outside a declared subset should be reported as a requested capability, rather than silently extending an existing claim. The conformance matrix records limits and evidence. Include the retained artifact or workflow run link in the issue so maintainers can reproduce the same inputs and feed the result back into fixtures and documentation.