download

Integrity-checked approved artifact download

Install

docsloth component add @docsloth/download@1.0.0

Live package: sha256:f1a556413ebbbde3829eb8b1e88e2bf5d354bf7dfec13ee142f4a3c064d8a5ef with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

Props

The prop schema is normative in packages/contracts/component-props/download.schema.json.

Example props generated from this schema:

{
  "title": "example-title",
  "artifact_id": "00000000-0000-4000-8000-000000000000",
  "filename": "example-filename",
  "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "size_bytes": 1,
  "license_label": "example-license_label"
}

Required props: artifact_id, filename, sha256, size_bytes, license_label.

Example

Example document IR (the block the renderer consumes):

{
  "type": "download",
  "props": {
    "title": "example-title",
    "artifact_id": "00000000-0000-4000-8000-000000000000",
    "filename": "example-filename",
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "size_bytes": 1,
    "license_label": "example-license_label"
  }
}

Renderer HTML (entities decoded and wrapped for display):

<section class="ds-block ds-download" data-component="download" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<dl class="ds-facts">
<div>
<dt>File</dt>
<dd>
<code>example-filename</code>
</dd>
</div>
<div>
<dt>Size</dt>
<dd>1 byte</dd>
</div>
<div>
<dt>SHA-256</dt>
<dd>
<code>aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</code>
</dd>
</div>
<div>
<dt>License</dt>
<dd>example-license_label</dd>
</div>
</dl>
<p class="ds-live-note" role="note">Downloads are issued by the live documentation site after an entitlement check.</p>
</section>

Preview (interface-only; the markup above is the same output):

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

Specification

Generated from packages/contracts/component-specs/download.md.

Contract

Production props are normative in ../contracts/component-props/download.schema.json. The corresponding component-fixtures manifest is only a minimal protocol fixture; use the production props schema when building the published package. The packaged artifact ships exactly its generated component-package.json manifest plus props.schema.json (the production props schema, copied byte-for-byte) and spec.md (this spec, copied byte-for-byte); it contains no executable payload, fallback implementation, Storybook, test suite, SSR harness or README. Rendering behavior and the acceptance cases below belong to the renderer and the repository tests, not to the package. Installation pins the package version and the digest of every shipped byte.

Intended behavior

The React component uses production artifact_id, filename, sha256, size_bytes and license_label. A release-scoped ComponentContentProvider.downloads map supplies the host-issued binding for that artifact: access: available, href, filename, sha256 and size_bytes. Only an exact metadata match produces a native download link. Destinations must be root-relative paths on the publication origin; external, credential-bearing and script URLs refuse. Filenames must be bounded basenames without controls or bidirectional override characters. Native links work without JavaScript and supply a filename hint with no referrer. No execution endpoint, model, clipboard or implicit capability request is invoked.

Failure and fallback

restricted, expired and revoked bindings hide artifact details and provide no link; loading states that delivery is being prepared. Missing, invalid or mismatched bindings show unavailable delivery with the valid expected artifact metadata. The hash is explicitly labeled expected, not client-verified. The delivery server must independently validate the signed grant, current entitlement, response byte bounds/hash and Content-Disposition filename. The component cannot infer revocation from an opaque URL, inspect response bytes through native navigation, or prevent a server-side redirect; the host owns those guarantees. Hosts replace immutable bindings when access/release changes. Engine/cloud grant issuance and artifact delivery remain integration work; browser tests use an explicitly routed fixture and verify its actual downloaded bytes.

Required acceptance cases

No open redirect or content-disposition filename injection. Also test empty data, loading, denied access, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

Package manifest

Protocol fixture: packages/contracts/component-fixtures/download.json.

Sources