tutorial

Verified multistep task tutorial

Install

docsloth component add @docsloth/tutorial@1.0.0

Live package: sha256:d8935cd3b71884c7b5704305752a4a464fcd43a97e37e08aaeefbed5bc7897d2 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/tutorial.schema.json.

Example props generated from this schema:

{
  "title": "example-title",
  "workflow_id": "example-workflow_id",
  "steps": [
    {
      "id": "example-id",
      "title": "example-title",
      "block_ids": [
        "00000000-0000-4000-8000-000000000000"
      ],
      "check_id": "example-check_id",
      "required": true
    }
  ],
  "resource": {
    "resource_id": "00000000-0000-4000-8000-000000000000",
    "operation": "example-operation",
    "environment": "test"
  },
  "persist_progress": true
}

Required props: workflow_id, steps, persist_progress.

Example

Example document IR (the block the renderer consumes):

{
  "type": "tutorial",
  "props": {
    "title": "example-title",
    "workflow_id": "example-workflow_id",
    "steps": [
      {
        "id": "example-id",
        "title": "example-title",
        "block_ids": [
          "00000000-0000-4000-8000-000000000000"
        ],
        "check_id": "example-check_id",
        "required": true
      }
    ],
    "resource": {
      "resource_id": "00000000-0000-4000-8000-000000000000",
      "operation": "example-operation",
      "environment": "test"
    },
    "persist_progress": true
  }
}

Renderer HTML (entities decoded and wrapped for display):

<section class="ds-block ds-tutorial" data-component="tutorial" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<ol class="ds-list">
<li>
<strong>example-title</strong> (required) — verified by <code>example-check_id</code>
</li>
</ol>
<dl class="ds-facts">
<div>
<dt>Workflow</dt>
<dd>
<code>example-workflow_id</code>
</dd>
</div>
<div>
<dt>Progress</dt>
<dd>Saved between visits</dd>
</div>
<div>
<dt>Runs</dt>
<dd>
<code>example-operation</code> in the test environment</dd>
</div>
</dl>
<p class="ds-live-note" role="note">Step checks and saved progress need the live documentation site.</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/tutorial.md.

Contract

Production props are normative in ../contracts/component-props/tutorial.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

Durable scoped progress tied to publication/version; completion depends on actual configured checks.

Failure and fallback

Blocked step permits viewing next content but not false completion.

Required acceptance cases

Failed check remains failed after refresh; reset scoped session only. 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.

React tutorial adapter

Production workflow_id, steps, persist_progress and optional resource select a host binding from ComponentContentProvider.tutorials, keyed with tutorialKey(workflow_id, resource) from @docsloth/official-components/host. Step block_ids resolve only through this provider's already authorized blocks. All instructions and native step links work without JavaScript. Browsing later steps after failure is allowed and never changes check results. There are at most 100 steps, 50 block references per step and 1,000 references overall; duplicate step IDs and invalid inputs refuse. Missing content is labelled rather than fabricated.

An available adapter names the exact release ID, workflow ID/version, actor session ID, persistence mode (durable or session), and a progress snapshot. Snapshots include the same scope, a revision and a map keyed by step ID. Each result names the configured check_id and has not_run, passed, failed or blocked status, plus an optional public-safe message. Only matching configured passed checks count toward required completion. Missing, restricted, loading, wrong-scope or malformed progress never becomes success. Persisted failures are rendered on reload; persist_progress: true requires the host's durable mode, rather than silently using local storage.

Optional verify and reset callbacks receive the exact scope, expected progress revision, persistence choice and abort signal; verify additionally receives the selected step/check IDs. They return typed ok progress, permission_required, unsupported or failed. HTTP success or stdout is not a check result. Reset affects the bound tutorial session only and must return cleared checks. Failed or invalid replies retain previous results. Replacing workflow/release/session or host progress invalidates outstanding results; stopping aborts the adapter and discards late responses. The UI does not claim an already-started remote mutation was rolled back.

The host must independently authorize capability and audience, validate published steps/checks, reserve approved execution budget, compare revisions and persist results/reset atomically. Its durable declaration is a contract, not evidence that browser storage is durable. This component does not dispatch arbitrary /v1/executions requests, store proofs in localStorage, create grants, or manufacture passed outcomes. Actual core/cloud transport, durable storage and constrained agent-tool wiring remain host integration work; the browser acceptance fixture exercises the adapter over HTTP with scoped server state across reloads, not a production database deployment.

Package manifest

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

Sources