pageship 0.2.0 → 0.4.0

package/dist/cli.mjs

@@ -705,7 +705,7 @@ async function updateWorkspaceAddress(baseUrl, action, options = {}) {
 		credentials: options.token ? "omit" : "include",
 		headers: options.token ? { Authorization: `Bearer ${options.token}` } : void 0,
 		redirect: "error",
-		cache: "no-store",
+		cache: "default",
 		throwOnError: false,
 		signal: options.signal ? AbortSignal.any([timeout, options.signal]) : timeout
 	});
@@ -724,7 +724,7 @@ function isRevisionId(value) {
 	return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}(?![\s\S])/iu.test(value);
 }
 /** Same readable normalized Git remote grammar as the Effect contract. */
-function isProject(value) {
+function isRepository(value) {
 	return typeof value === "string" && value.length <= 512 && /^[a-z0-9._-]+(?::[0-9]{1,5})?(?:\/(?!\.{1,2}(?:\/|$))[^\x00-\x20\x7f/\\?#]+)+(?![\s\S])/u.test(value);
 }
 function isCliVersion(value) {
@@ -742,6 +742,16 @@ function requestOptions(baseUrl, options) {
 		throwOnError: false
 	};
 }
+/**
+* A change keeps the browser's default cache mode. Chromium skips its preflight cache for a
+* `no-store` request, and no browser caches a change's response anyway.
+*/
+function changeOptions(baseUrl, options) {
+	return {
+		...requestOptions(baseUrl, options),
+		cache: "default"
+	};
+}
 function record(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -757,7 +767,7 @@ function normalizeDocument(value) {
 	return validDocument(normalized) ? normalized : void 0;
 }
 function validDocument(value) {
-	return record(value) && isDocumentId(value.id) && typeof value.slug === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*(?![\s\S])/u.test(value.slug) && validTitle(value.title) && typeof value.sourcePath === "string" && value.sourcePath.length <= 1024 && /^(?!\/)(?!.*(?:^|\/)\.{1,2}(?:\/|$))(?!.*\/\/)[^\x00-\x1f\x7f\\:]*\.[hH][tT][mM][lL]?(?![\s\S])/u.test(value.sourcePath) && (value.project === null || isProject(value.project)) && (value.visibility === "private" || value.visibility === "public") && isRevisionId(value.revisionId) && typeof value.byteLength === "number" && Number.isSafeInteger(value.byteLength) && value.byteLength > 0 && typeof value.createdAt === "number" && Number.isSafeInteger(value.createdAt) && value.createdAt >= 0 && typeof value.publishedAt === "number" && Number.isSafeInteger(value.publishedAt) && value.publishedAt >= 0 && typeof value.url === "string" && new RegExp(`^https://[a-z0-9-]+\\.${workspaceDomainPattern}/d/${value.id}-${value.slug}$`, "u").test(value.url);
+	return record(value) && isDocumentId(value.id) && typeof value.slug === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*(?![\s\S])/u.test(value.slug) && validTitle(value.title) && typeof value.sourcePath === "string" && value.sourcePath.length <= 1024 && /^(?!\/)(?!.*(?:^|\/)\.{1,2}(?:\/|$))(?!.*\/\/)[^\x00-\x1f\x7f\\:]*\.[hH][tT][mM][lL]?(?![\s\S])/u.test(value.sourcePath) && (value.repository === null || isRepository(value.repository)) && (value.visibility === "private" || value.visibility === "public") && isRevisionId(value.revisionId) && typeof value.byteLength === "number" && Number.isSafeInteger(value.byteLength) && value.byteLength > 0 && typeof value.createdAt === "number" && Number.isSafeInteger(value.createdAt) && value.createdAt >= 0 && typeof value.publishedAt === "number" && Number.isSafeInteger(value.publishedAt) && value.publishedAt >= 0 && typeof value.url === "string" && new RegExp(`^https://[a-z0-9-]+\\.${workspaceDomainPattern}/d/${value.id}-${value.slug}$`, "u").test(value.url);
 }
 function validRevision(value, documentId) {
 	return record(value) && isRevisionId(value.id) && typeof value.createdAt === "number" && Number.isSafeInteger(value.createdAt) && value.createdAt >= 0 && typeof value.byteLength === "number" && Number.isSafeInteger(value.byteLength) && value.byteLength > 0 && typeof value.isCurrent === "boolean" && (value.cliVersion === null || isCliVersion(value.cliVersion)) && typeof value.url === "string" && new RegExp(`^https://[a-z0-9-]+\\.${workspaceDomainPattern}/d/${documentId}-[a-z0-9]+(?:-[a-z0-9]+)*/revisions/${value.id}$`, "u").test(value.url);
@@ -861,7 +871,7 @@ async function getDocumentContent(baseUrl, id, options = {}) {
 	throw new Error("Invalid document content response.");
 }
 async function restoreDocumentRevision(baseUrl, id, input, options = {}) {
-	const request = requestOptions(baseUrl, options);
+	const request = changeOptions(baseUrl, options);
 	const { data: received, response, error } = await documentsRestore({
 		...request,
 		path: { id },
@@ -891,7 +901,7 @@ async function restoreDocumentRevision(baseUrl, id, input, options = {}) {
 }
 async function updateDocumentVisibility(baseUrl, id, visibility, options = {}) {
 	const { data: received, response, error } = await documentsUpdateVisibility({
-		...requestOptions(baseUrl, options),
+		...changeOptions(baseUrl, options),
 		path: { id },
 		body: { visibility }
 	});
@@ -913,7 +923,7 @@ async function publishDocument(baseUrl, input, options = {}) {
 	if (input.action) {
 		if (!(await getDocumentLimits(baseUrl, options)).publicationActions.includes(input.action)) throw new DocumentRequestError("publication_action_unsupported", "This server does not support explicit publication actions. Ask the operator to update the server. No HTML was uploaded.", 400);
 	}
-	const request = requestOptions(baseUrl, options);
+	const request = changeOptions(baseUrl, options);
 	const { data: received, response, error } = await documentsCreate({
 		...request,
 		headers: {
@@ -923,7 +933,7 @@ async function publishDocument(baseUrl, input, options = {}) {
 		body: new Blob([new Uint8Array(input.bytes)], { type: "text/html" }),
 		query: {
 			sourcePath: input.sourcePath,
-			project: input.project,
+			repository: input.repository,
 			cliVersion: input.cliVersion,
 			action: input.action,
 			documentId: input.documentId,
@@ -962,7 +972,7 @@ async function getWorkspace(baseUrl, options = {}) {
 	});
 	if (!response?.ok) throw new Error("Could not load your workspace.", { cause: error });
 	if (data?.status === "signed_out" || data?.status === "uninvited") return { status: data.status };
-	if (data?.status === "admitted" && typeof data.user?.id === "string" && data.user.id.length > 0 && typeof data.user?.name === "string" && (data.user.login === void 0 || typeof data.user.login === "string") && typeof data.workspace?.id === "string" && data.workspace.id.length > 0 && (data.address === void 0 || data.address === null || isWorkspaceAddress(data.address))) return data;
+	if (data?.status === "admitted" && typeof data.user?.id === "string" && data.user.id.length > 0 && typeof data.user?.name === "string" && (data.user.login === void 0 || typeof data.user.login === "string") && (data.user.githubAccountId === void 0 || typeof data.user.githubAccountId === "string" && /^[1-9]\d*$/u.test(data.user.githubAccountId)) && typeof data.workspace?.id === "string" && data.workspace.id.length > 0 && (data.address === void 0 || data.address === null || isWorkspaceAddress(data.address))) return data;
 	throw new Error("Invalid workspace response.");
 }
 function validateCompatibility(value) {
@@ -1323,7 +1333,7 @@ const outcomes = {
 	choice_required: "pending",
 	address_required: "pending",
 	source_collision: "pending",
-	project_mismatch: "pending",
+	repository_mismatch: "pending",
 	marker_unavailable: "pending",
 	revision_conflict: "pending",
 	cancelled: "pending",
@@ -1412,7 +1422,7 @@ function commandLine(command, args) {
 }
 //#endregion
 //#region package.json
-var version = "0.2.0";
+var version = "0.4.0";
 //#endregion
 //#region src/publish.ts
 const execute = promisify(execFile);
@@ -1424,7 +1434,7 @@ async function sourceMetadata(file) {
 	const path = await realpath(resolve(file));
 	const cwd = await realpath(process.cwd());
 	let root = contained(cwd, path) ? cwd : dirname(path);
-	let project;
+	let repository;
 	try {
 		const git = async (...args) => (await execute("git", [
 			"-C",
@@ -1445,8 +1455,8 @@ async function sourceMetadata(file) {
 				"ssh:",
 				"git:"
 			].includes(url.protocol) && url.hostname) {
-				const repository = `${url.hostname.toLowerCase()}${url.port ? `:${url.port}` : ""}/${url.pathname.replace(/^\/+|\/+$/gu, "").replace(/\.git$/u, "")}`;
-				if (isProject(repository)) project = repository;
+				const normalized = `${url.hostname.toLowerCase()}${url.port ? `:${url.port}` : ""}/${url.pathname.replace(/^\/+|\/+$/gu, "").replace(/\.git$/u, "")}`;
+				if (isRepository(normalized)) repository = normalized;
 			}
 		}
 	} catch {}
@@ -1455,7 +1465,7 @@ async function sourceMetadata(file) {
 	return {
 		path,
 		sourcePath,
-		project
+		repository
 	};
 }
 async function fileBytes(path, limit) {
@@ -1653,7 +1663,7 @@ async function publish(options) {
 					expectedRevisionId: entry.revisionId
 				};
 				automatic = "manifest";
-			} else if (target.project === (source.project ?? null)) {
+			} else if (target.repository === (source.repository ?? null)) {
 				action = {
 					action: "revise",
 					documentId: target.id,
@@ -1661,9 +1671,9 @@ async function publish(options) {
 				};
 				automatic = "marker";
 			} else return {
-				status: "project_mismatch",
+				status: "repository_mismatch",
 				document: target,
-				message: `This file's marker names ${target.url}, a document from ${target.project ?? "a loose file"}, but this file ${source.project ? `belongs to ${source.project}` : "is a loose file"}. No document changed. To revise that document anyway, publish with --revise ${target.id} --expected-revision ${target.revisionId}, or use --new for a separate document. Use --json for complete follow-up arguments.`,
+				message: `This file's marker names ${target.url}, a document from ${target.repository ?? "a loose file"}, but this file ${source.repository ? `belongs to ${source.repository}` : "is a loose file"}. No document changed. To revise that document anyway, publish with --revise ${target.id} --expected-revision ${target.revisionId}, or use --new for a separate document. Use --json for complete follow-up arguments.`,
 				resolutions: resolutions(options.file, contextArgs, [target])
 			};
 		} else if (detect) {
@@ -1691,7 +1701,7 @@ async function publish(options) {
 				const result = await publishDocument(server, {
 					bytes: uploaded,
 					sourcePath: source.sourcePath,
-					...source.project ? { project: source.project } : {},
+					...source.repository ? { repository: source.repository } : {},
 					cliVersion: version,
 					idempotencyKey,
 					...proposal
@@ -2191,7 +2201,7 @@ function listDocuments(options) {
 			...next ? { next } : {},
 			message: [
 				page.documents.length ? "Documents:" : options.cursor ? "No more documents." : "No documents.",
-				...page.documents.map((document) => `${document.id}  ${document.visibility}  ${document.title}\n` + (document.project ? `  project ${document.project}\n` : "") + `  source ${document.sourcePath}\n  current revision ${document.revisionId}\n  ${document.url}`),
+				...page.documents.map((document) => `${document.id}  ${document.visibility}  ${document.title}\n` + (document.repository ? `  repository ${document.repository}\n` : "") + `  source ${document.sourcePath}\n  current revision ${document.revisionId}\n  ${document.url}`),
 				...next ? [`More documents: run ${commandLine(next.command, next.args)}`] : []
 			].join("\n")
 		};
@@ -2346,7 +2356,7 @@ const isSkillName = (name) => /^pageship(?:-[a-z0-9-]+)?$/u.test(name);
 const recommendedSkills = ["frontend-design", "design-taste-frontend"];
 /** The oldest Node major that runs the authoring skills' scripts. */
 const authoringNodeMajor = 20;
-const setupGuide = "https://pageship.dev/setup-guide";
+const setupGuide = "https://pageship.dev/setup-guide.md";
 const installNext = {
 	command: "skills",
 	args: ["install"]
@@ -2457,7 +2467,7 @@ async function findMissing(environment) {
 function notFound(missing) {
 	if (missing.length === 0) return void 0;
 	const named = missing.map((entry) => entry === "node" ? `Node ${authoringNodeMajor} or later` : entry);
-	return `${named.length > 1 ? `${named.slice(0, -1).join(", ")} and ${named.at(-1)}` : named[0]} ${named.length > 1 ? "were" : "was"} not found. The setup guide at ${setupGuide} covers them.`;
+	return `${named.length > 1 ? `${named.slice(0, -1).join(", ")} and ${named.at(-1)}` : named[0]} ${named.length > 1 ? "were" : "was"} not found. The setup guide covers them: download ${setupGuide} and read all of it.`;
 }
 /**
 * Whether the Pageship skills in ~/.agents/skills are missing, current, or older than this

package/dist/skills/pageship/SKILL.md

@@ -3,7 +3,7 @@ name: pageship
 description: Publish an HTML file to Pageship and manage what is published. Use when the user asks to publish, share or get a link to a document, update its published copy, change its visibility, list, inspect history, download or restore published documents, or sign in to Pageship. To write, edit, rename or move a document, load pageship-docs instead.
 license: MIT
 metadata:
-  version: "0.2.0"
+  version: "0.4.0"
 ---
 
 # Pageship
@@ -18,7 +18,7 @@ A document marker in a file (`<!-- pageship:v1 document=<id> -->`) records that
 
 ## Write or change a document
 
-When the user asks to write, change, rename or move a document, load `pageship-docs` and follow it, even when the same request asks you to publish. When it hands over the file, publish it if the user asked. If `pageship-docs` isn't installed, say so and offer the setup guide at https://pageship.dev/setup-guide, which installs it. If the user declines, write the document without the authoring skills, then publish it if the user asked.
+When the user asks to write, change, rename or move a document, load `pageship-docs` and follow it, even when the same request asks you to publish. When it hands over the file, publish it if the user asked. If `pageship-docs` isn't installed, say so and offer the setup guide, which installs it. Get it as [Install the CLI](#install-the-cli) describes. If the user declines, write the document without the authoring skills, then publish it if the user asked.
 
 ## Reading a result
 
@@ -38,7 +38,7 @@ A follow-up has a `command` and an `args` array. Run it as `pageship --json <com
 
 ## Install the CLI
 
-If the shell can't find `pageship`, tell the user the Pageship CLI isn't installed and offer to install it. Only with their consent, follow the setup guide at https://pageship.dev/setup-guide. It asks before it changes their environment.
+If the shell can't find `pageship`, tell the user the Pageship CLI isn't installed and offer to install it. Only with their consent, follow the setup guide. Download https://pageship.dev/setup-guide.md with curl or a similar command and read all of it, since a fetch tool may hand you only a summary. The guide asks before it changes their environment.
 
 ## Check readiness
 
@@ -62,7 +62,7 @@ pageship --json skills install
 
 On `skills_installed`, they are in `~/.agents/skills`, and linked from `~/.claude/skills` when Claude Code is set up. On `skills_modified`, nothing was written: the folders in `folders` were changed after the CLI installed them, or the CLI has no record of them. Show the user those folders. Run `resolutions.force` only if they agree to replace them and lose those changes.
 
-Both results, and `status`, list in `missing` what the CLI looked for and did not find: the recommended skills `frontend-design` and `design-taste-frontend`, and `node`, Node 20 or later, which the authoring skills' scripts need. The CLI never installs them, and they never change the outcome. Mention them, and offer the setup guide at https://pageship.dev/setup-guide.
+Both results, and `status`, list in `missing` what the CLI looked for and did not find: the recommended skills `frontend-design` and `design-taste-frontend`, and `node`, Node 20 or later, which the authoring skills' scripts need. The CLI never installs them, and they never change the outcome. Mention them, and offer the setup guide. Get it as [Install the CLI](#install-the-cli) describes.
 
 ## Sign in
 
@@ -88,9 +88,9 @@ Set the shell placeholder `PAGESHIP_FILE` to one nonempty `.html` or `.htm` file
 pageship --json publish "$PAGESHIP_FILE"
 ```
 
-The CLI records each published file's real path in its publish manifest on this machine, so running the same command again for that file revises its document without a choice, and a fresh session needs no remembered document ID. Inside a Git checkout with an origin remote, the file belongs to a project. A project file without a manifest entry, such as one in another checkout, is looked up by its project and repository-relative path on the server. `document.project` shows the readable remote, and it is `null` for a loose file outside any project.
+The CLI records each published file's real path in its publish manifest on this machine, so running the same command again for that file revises its document without a choice, and a fresh session needs no remembered document ID. Inside a Git checkout with an origin remote, the file belongs to a repository. A file in a repository without a manifest entry, such as one in another checkout, is looked up by its repository and repository-relative path on the server. `document.repository` shows the readable remote, and it is `null` for a loose file outside any repository.
 
-After a successful upload the CLI adds the document marker to the end of the local file, so the file and the published revision match. The marker lets the file find its document after a rename or a move, and on another machine in a checkout of the same project. Keep the marker when you edit or regenerate the file, and do not write or change it yourself. To publish a file exactly as it is, add `--no-marker`.
+After a successful upload the CLI adds the document marker to the end of the local file, so the file and the published revision match. The marker lets the file find its document after a rename or a move, and on another machine in a checkout of the same repository. Keep the marker when you edit or regenerate the file, and do not write or change it yourself. To publish a file exactly as it is, add `--no-marker`.
 
 ### Report the publish
 
@@ -104,7 +104,7 @@ Keep `idempotencyKey` only while you resolve an uncertain attempt.
 
 ### When the publish stops for a decision
 
-On `project_mismatch`, the file's marker names a document from another project, for example a fork. Nothing changed. Show the user the returned `document` and ask whether to revise it with the `resolutions.revise` entry or create a separate document with `resolutions.new`.
+On `repository_mismatch`, the file's marker names a document from another repository, for example a fork. Nothing changed. Show the user the returned `document` and ask whether to revise it with the `resolutions.revise` entry or create a separate document with `resolutions.new`.
 
 On `marker_unavailable`, the marker names a document that was not found or is not the user's, and nothing was uploaded. Ask before running the returned `next`, which creates a separate document.
 
@@ -120,7 +120,7 @@ An unmarked loose file is not matched by path, so on another machine, or from an
 pageship --json publish "$PAGESHIP_FILE" --revise "$PAGESHIP_DOCUMENT" --expected-revision "$PAGESHIP_REVISION"
 ```
 
-This works for any document the user owns, even when the file moved or belongs to another project. Another account's document returns `unavailable`. Later plain publishes of this file revise the named document, and its marker names it. After `--new`, they revise the new one.
+This works for any document the user owns, even when the file moved or belongs to another repository. Another account's document returns `unavailable`. Later plain publishes of this file revise the named document, and its marker names it. After `--new`, they revise the new one.
 
 ## Share a document
 

package/dist/skills/pageship-chart/SKILL.md

@@ -3,12 +3,12 @@ name: pageship-chart
 description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for charts in a Pageship HTML document, loaded by a pageship- kind skill before it draws a chart.
 license: MIT
 metadata:
-  version: "0.2.0"
+  version: "0.4.0"
 ---
 
 # Chart
 
-A chart answers one question about the source's numbers at a glance. You draw it as inline SVG on an honest scale, with every value the reader needs printed on the page, never with a chart library or Mermaid.
+A chart answers one question about the source's numbers at a glance. You draw it as inline SVG on an honest scale, with every value the reader needs printed on the page, never with a chart library or Mermaid, and it plays once from its initial state to its values when it scrolls into view.
 
 Unless another pageship- skill loaded this one, start as [pageship-docs says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill).
 
@@ -85,6 +85,22 @@ Write static SVG markup with the coordinates computed as you write. For each val
 
 Buttons that highlight or filter series show every series by default.
 
+## 5. Play the entrance
+
+Load `pageship-motion` before the first chart: [its playback rules](../pageship-motion/SKILL.md#2-build-it-so-the-still-page-tells-the-whole-story) own when a chart plays, its pace, its controls and reduced motion. The markup you wrote in step 4 is the end state; the entrance starts from each mark's initial state and ends on that markup.
+
+| Form                             | Entrance                                                                                                                      |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Vertical bars, histogram bins    | Bars grow up from the baseline to their height; each printed value fades in with its bar.                                     |
+| Horizontal bars                  | Bars grow from the left axis to their length, top to bottom.                                                                  |
+| Line chart                       | Each line draws from left to right; a point and its value appear as the line reaches it; the direct label appears at the end. |
+| Share bar                        | The parts fill in from left to right, one after the next, each to its share.                                                  |
+| Scatter plot, dot plot           | Dots appear in order of the horizontal axis, left to right.                                                                   |
+| Small multiples                  | Every small chart plays its own form's entrance at the same time, on the same clock.                                          |
+| Target, forecast and other lines | Appear in full when the series they belong to finishes.                                                                       |
+
+[The reference script](../pageship-motion/references/figure-motion.md) shows bars that grow and a line that draws; the other forms scale each mark's size or opacity the same way.
+
 ## Colours
 
 Colour the chart in the stylesheet, with `fill` and `stroke`, from [the look's colour variables](../pageship-docs/references/design.md#the-looks-colour-variables) and no other colour:

package/dist/skills/pageship-code-block/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-code-block
 description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for code in a Pageship HTML document, such as source code, commands, configuration or logs, loaded by a pageship- kind skill before the first code block.
 license: MIT
 metadata:
-  version: "0.2.0"
+  version: "0.4.0"
 ---
 
 # Code block

package/dist/skills/pageship-decision-record/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-decision-record
 description: HTML decision records, as the second step of pageship-docs. For any request to record, write, regenerate, edit or move a decision, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.2.0"
+  version: "0.4.0"
 ---
 
 # Decision record
@@ -29,6 +29,10 @@ Build one comparison of the options:
 - Every option gets a value on every point: what the source says about that option on that point, in its units and wording. Where the source says nothing, write "Not stated", never a value you would have to infer, such as "low" for an option whose cost the source never gives.
 - Keep the source's order of options, and mark the chosen one in words.
 
+## Figures
+
+Beyond the comparison table, a decision record's figures come from the numbers behind the context and from the consequences, such as a table of the consequences when most share fields such as standing and who acts. When the source gives a number for every option on one point, such as cost, a chart of that point beside the table is a candidate figure.
+
 ## Order
 
 1. **Title and decision.** An `h1` naming what was decided, then at once the decision in one or two sentences in the source's words, and a line with its status and the date, owner and scope the source gives.

package/dist/skills/pageship-diagram/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-diagram
 description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for diagrams in a Pageship HTML document, such as a process, a timeline, a system map or states, loaded by a pageship- kind skill before it draws a diagram.
 license: MIT
 metadata:
-  version: "0.2.0"
+  version: "0.4.0"
 ---
 
 # Diagram
@@ -16,16 +16,16 @@ Unless another pageship- skill loaded this one, start as [pageship-docs says](..
 
 Write down the reader's question the figure answers, in a few words, and take the row closest to it.
 
-| The reader asks                                 | Diagram                                 | Drawn with                         |
-| ----------------------------------------------- | --------------------------------------- | ---------------------------------- |
-| What happens next, and where does it branch?    | Flowchart, top to bottom                | SVG, with a [step-through][steps]  |
-| Who hands what to whom, in what order?          | Swimlane or sequence                    | SVG, with a [step-through][steps]  |
-| When did each thing happen, and how far apart?  | [Timeline](references/svg.md#timelines) | SVG, always                        |
-| What states can it be in, and what moves it on? | State diagram                           | SVG, [computed][layout] when large |
-| What connects to what?                          | System map or dependency graph          | SVG, [computed][layout] when large |
-| What is part of what?                           | Tree or nested boxes                    | SVG                                |
+| The reader asks                                 | Diagram                                 | Drawn with                          |
+| ----------------------------------------------- | --------------------------------------- | ----------------------------------- |
+| What happens next, and where does it branch?    | Flowchart, top to bottom                | SVG, played as a [sequence][motion] |
+| Who hands what to whom, in what order?          | Swimlane or sequence                    | SVG, played as a [sequence][motion] |
+| When did each thing happen, and how far apart?  | [Timeline](references/svg.md#timelines) | SVG, played as a [sequence][motion] |
+| What states can it be in, and what moves it on? | State diagram                           | SVG, [computed][layout] when large  |
+| What connects to what?                          | System map or dependency graph          | SVG, [computed][layout] when large  |
+| What is part of what?                           | Tree or nested boxes                    | SVG                                 |
 
-A process or a change over time of three to eight steps gets the [step-through][steps], unless its layout is computed.
+Every diagram plays once when it scrolls into view, by `pageship-motion`. A process, a path or events in time play as a [sequence][motion]: a marker travels the path, or the stages or events appear in order, and the reader has the controls. Every other diagram, a computed layout included, is a graphic that builds in: its nodes appear, then its connectors draw. A Mermaid figure, which Mermaid draws at load, holds still.
 
 ## 2. Fit the limits
 
@@ -52,7 +52,7 @@ Content you merge or move stays in the document, in a figure or the text beside
 - With SVG, follow [the SVG rules](references/svg.md).
 - With a computed layout, follow [the computed layout steps][layout].
 - With Mermaid, follow [the Mermaid rules][mermaid].
-- For a process or change over time laid out by hand, add [the step-through][steps].
+- Load `pageship-motion` before the first SVG figure. A process, a path or events in time laid out by hand plays as a [sequence][motion]: each node and connector carries the `data-step` that brings it in, and an ordered list of the steps with their values follows the drawing. Any other SVG figure builds in as a graphic: the nodes appear, then the connectors draw.
 
 Every figure, however drawn:
 
@@ -78,8 +78,10 @@ When the source sorts the nodes into two to four named groups, such as the team
 
 ## Check
 
-- In a browser, run [check-diagram.js](references/check-diagram.js) in the page at 1280px and at 390px wide, for example `agent-browser eval "$(cat <this skill's folder>/references/check-diagram.js)"`. It returns a list of problems with every SVG you drew or computed. Fix each one and run it again until the list is empty. A line starting with "note" is a crossing to remove if you can.
-- For a step-through, run [its check](../pageship-interaction/references/step-through.md#check).
+Run the browser steps with [the check's browser tool](../pageship-docs/references/check.md#checks-in-a-browser).
+
+- Run [check-diagram.js](references/check-diagram.js) in the page at 1280px and at 390px wide. In `html_preview`, the copy's `load` listener runs `const problems = <the file's text>` and logs `JSON.stringify(problems)`. In agent-browser, run `agent-browser eval "$(cat <this skill's folder>/references/check-diagram.js)"`. It returns a list of problems with every SVG you drew or computed. Fix each one and run it again until the list is empty. A line starting with "note" is a crossing to remove if you can.
+- For every SVG figure, run [the motion check](../pageship-motion/SKILL.md#check).
 - For Mermaid, look at the screenshot at both widths and confirm every node and label is readable, no two lines run together, and no line runs through a node or a label.
 - Without a browser, check your layout plan by arithmetic as [the SVG rules](references/svg.md#plan-the-layout) say.
 
@@ -87,6 +89,6 @@ When the source sorts the nodes into two to four named groups, such as the team
 
 The structure you introduced includes the form you chose for each figure and why, and any merges, splits or overviews. When a graph over the hand-drawn limits went to Mermaid instead of a computed layout, say why.
 
-[steps]: ../pageship-interaction/references/step-through.md
+[motion]: ../pageship-motion/SKILL.md
 [mermaid]: references/mermaid.md
 [layout]: references/computed-layout.md

package/dist/skills/pageship-diagram/references/check-diagram.js

@@ -1,6 +1,7 @@
 // Checks every hand-drawn diagram in the open page against the pageship-diagram rules.
-// Run the whole file in the page, for example with `agent-browser eval "$(cat check-diagram.js)"`
-// or Playwright's `page.evaluate`. It returns a list of problems; an empty list passes.
+// Run the whole file in the page, for example with `agent-browser eval "$(cat check-diagram.js)"`,
+// or in html_preview as `const problems = <this file>` in a load listener that logs them.
+// It returns a list of problems; an empty list passes.
 // Mermaid diagrams are skipped: Mermaid lays them out itself.
 (() => {
   const problems = [];

package/dist/skills/pageship-docs/SKILL.md

@@ -3,13 +3,15 @@ name: pageship-docs
 description: First step for any document people read, such as a report, plan, spec, explainer, review, decision record or slide deck, in HTML or Markdown. Load it before any other pageship- skill. Use when the user asks for one of these documents, asks to regenerate, redesign, edit, rename, move or copy an HTML source file, or asks to record whether they want HTML or Markdown.
 license: MIT
 metadata:
-  version: "0.2.0"
+  version: "0.4.0"
 ---
 
 # Pageship documents
 
 The result is Markdown or one standalone HTML source file. You never publish yourself; you hand the file to the `pageship` skill, which does.
 
+When your task says you write the file for `pageship-docs`, you are the subagent of [step 4 in a subagent](#step-4-in-a-subagent): start at step 4 with the format, kind and path it gives. Otherwise, when you can start a subagent, as in Claude Code, Codex and T3 Code, run steps 1 to 3 yourself and send step 4 to one subagent, for a new file and an edit alike. The sources, skill text and check output then stay in its context, not yours. Without subagents, run every step yourself.
+
 ## 1. Settle the format
 
 Take the first rule that applies.
@@ -35,7 +37,7 @@ For Markdown, go to step 3.
 | Decision record | What was decided, the options and the consequences        | `pageship-decision-record` |
 | Slide deck      | Slides to present from a browser                          | `pageship-slide-deck`      |
 
-Load the skill of the kind that fits. When none fits exactly, or its skill is not installed, use the closest installed kind and tell the user which.
+Pick the kind that fits. Step 4 loads its skill. When none fits exactly, or its skill is not installed, use the closest installed kind and tell the user which.
 
 ## 3. Choose the path
 
@@ -43,25 +45,47 @@ A new file goes at the path the user names, or else where the project keeps such
 
 ## 4. Write the file
 
+When you send this step to a subagent, follow [step 4 in a subagent](#step-4-in-a-subagent).
+
 For Markdown, write one file by the [content rules](references/content.md) alone, then hand over.
 
-For HTML, the kind skill gives the parts, the order and its own rules, which win over this skeleton:
+For HTML, load the kind skill. It gives the parts, the order and its own rules, which win over this skeleton:
 
 1. **Gather.** Read the request, every file it points to and the project's glossary. Where the kind asks for an **inventory**, list every item of the source in its order and words, until an item covers every sentence of the source. Done when you can point to where each fact you plan to write comes from.
 2. **Sort.** Put every statement of the source into exactly one of the kind's parts.
-3. **Write.** One file by the [content rules](references/content.md), the [file rules](references/file.md) and the [design rules](references/design.md), in the kind's order, under its headings or the closest glossary terms. A part the source leaves empty keeps its heading and one line saying the source gives none. Done when every sorted statement, or every inventory item, is in the file.
-4. **Check.** Run [the check](references/check.md), with the checks the kind and pattern skills add.
+3. **Figures.** For each section, ask whether a figure carries its point better than prose: a chart, a table, a diagram or key figures. Wherever one does, use it, in the form [the design rules](references/design.md#the-form-of-each-figure) give. Technical or complex content, such as a mechanism, a set of numbers or a comparison of several items, gets a figure and prose. The prose beside each figure says what it shows and why it matters, as the source puts it. Before drawing the first chart, graphic or sequence diagram, load `pageship-motion`, which plays each one as it scrolls into view. Done when you can name, for each section, the figures it gets, or that prose carries its point better.
+4. **Write.** One file by the [content rules](references/content.md), the [file rules](references/file.md) and the [design rules](references/design.md), in the kind's order, under its headings or the closest glossary terms. A part the source leaves empty keeps its heading and one line saying the source gives none. Done when every sorted statement, or every inventory item, is in the file.
+5. **Check.** Run [the check](references/check.md), with the checks the kind and pattern skills add.
 
 Then hand over. Your final message lists, however briefly you otherwise reply:
 
 - the file's path;
 - the structure you added that the source didn't have, as [the check lists it](references/check.md#the-structure-you-added);
 - the open questions, marking the ones you added;
-- the checks that ran and the ones you skipped;
+- the checks that ran and the ones you skipped, and which tool ran [the browser checks](references/check.md#checks-in-a-browser), or that none did;
 - what the kind and pattern skills add to this list.
 
-For an HTML file, end the hand-over with the next step for publishing. When the user asked in this conversation to publish this document, or accepted an offer to, load `pageship` and publish it. Otherwise, when the `pageship` skill is installed, offer to publish the file through it; for a file with a document marker, offer to publish the change as a new revision of its document.
+As the subagent, end at the list. Otherwise, for an HTML file, end the hand-over with the next step for publishing. When the user asked in this conversation to publish this document, or accepted an offer to, load `pageship` and publish it. Otherwise, when the `pageship` skill is installed, offer to publish the file through it; for a file with a document marker, offer to publish the change as a new revision of its document.
+
+## Step 4 in a subagent
+
+Start one subagent and give it:
+
+- the user's request, word for word, and every source that lives only in this conversation, such as pasted text or an answer the user gave, quoted in full;
+- each source file by absolute path, the file being edited, renamed, moved or copied included. The subagent reads them;
+- the format and the path from steps 1 to 3 and, for HTML, the kind or lone pattern skill;
+- this instruction: "You write the file for `pageship-docs`. Load it and the skill named here, and follow step 4 and its hand-over. The format, kind and path are settled. Put each question you would ask the user into the open questions. Your final message is the full hand-over list; I handle publishing."
+
+Wait for its final message. When it lacks the hand-over list, ask the subagent for the list.
+
+When the list has "Fresh reading still to run", the subagent couldn't start a reader of its own:
+
+1. Start a new subagent that has not seen this conversation and give it only the reader task the list gives, word for word. Wait for its answer.
+2. Bring its quotes to the writer. When you can continue the writing subagent, send it the quotes in full. Otherwise start a new subagent with the file's path, each source file by absolute path, the kind skill, the quotes in full and this instruction: "You write the file for `pageship-docs`. Load it and the skill named here. The file is written; the quotes below are its fresh reading. Fix each one as the skill's check says, then run the rest of the check again. Your final message is the full hand-over list; I handle publishing."
+3. Its new list replaces the first. Done when the list you relay has no "Fresh reading still to run".
+
+Relay the list to the user in full, open questions included, then, for an HTML file, end with the next step for publishing as step 4 says.
 
 ## Starting at a kind or pattern skill
 
-When the user named a kind skill, or named a pattern skill and asked for just that pattern, write HTML unless the request names another format, and start at step 3. A lone pattern is the file's main content, under an `h1`, with no parts to sort. In every other case, start at step 1.
+The subagent always starts at step 4. Otherwise, when the user named a kind skill, or named a pattern skill and asked for just that pattern, write HTML unless the request names another format, and start at step 3. A lone pattern is the file's main content, under an `h1`, with no parts to sort. In every other case, start at step 1.

package/dist/skills/pageship-docs/references/axe.js

@@ -0,0 +1,34 @@
+// Runs axe-core's WCAG 2 A and AA rules on the page and logs one line per problem, with the
+// element and how to fix it. Run with `agent-browser eval --stdin < axe.js`, which also prints the
+// lines, or paste into a <script> at the end of <body> for html_preview, which shows the log.
+// The promise stays the script's value, which agent-browser eval waits for and prints.
+// oxlint-disable-next-line typescript/no-floating-promises
+(async () => {
+  // Added before the page's load event, the script delays it, so html_preview waits for axe-core.
+  if (!window.axe) {
+    const script = document.createElement("script");
+    script.src = "https://cdn.jsdelivr.net/npm/axe-core@4.14.0/axe.min.js";
+    script.integrity = "sha384-lFUXB8tI4BaTE1bqxH9eeAXON2NH1qsdAhs7S5L++nUNP5QOy+hwr0C3TYEJUEl0";
+    script.crossOrigin = "anonymous";
+    document.head.append(script);
+    await new Promise((resolve, reject) => {
+      script.onload = resolve;
+      script.onerror = () => reject(new Error("axe-core didn't load"));
+    });
+  }
+  if (document.readyState !== "complete") {
+    await new Promise((resolve) => addEventListener("load", resolve, { once: true }));
+  }
+  const { violations } = await window.axe.run(document, {
+    runOnly: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"],
+  });
+  const problems = violations.flatMap((violation) =>
+    violation.nodes.map(
+      (node) =>
+        `axe ${violation.id}: ${node.target.join(" ")}: ${node.failureSummary.replace(/\s+/g, " ")}`,
+    ),
+  );
+  for (const problem of problems) console.log(problem);
+  console.log(`axe: ${problems.length} problems`);
+  return problems;
+})();

package/dist/skills/pageship-docs/references/check.md

@@ -2,25 +2,52 @@
 
 Run these checks on the finished file and fix what they find.
 
-The files a check makes, such as screenshots, PDFs and scripts, are scratch: save them by absolute path in the system temporary folder, never in the project, and delete them, wherever they landed, once the check is done.
+The files a check makes, such as screenshots, PDFs, scripts and edited copies of the file, are scratch: save them by absolute path in the system temporary folder, never in the project, and delete them, wherever they landed, once the check is done.
 
 ## Checks that need no browser
 
-- Every `<script src>` and `<link rel="stylesheet">` tag matches a tag in the [file rules](file.md) exactly: the same URL, `integrity` and `crossorigin="anonymous"`. A script or stylesheet inside the file as a `data:` URL matches none. A hosted font matches by its address instead: a stylesheet link to `https://fonts.googleapis.com/css2?family=...`, with no `integrity`. A font preload (`rel="preload" as="font"`) needs no match.
-- No relative paths load anything: search for `src="` and `url(` and confirm each one is `https://`, `data:` or a `#fragment`.
+Run the linter, html-validate with the config and rules in this folder:
+
+```sh
+npx --yes html-validate@11.17.0 --config <pageship-docs folder>/references/html-validate.json <file>
+```
+
+It reports HTML errors, accessibility problems such as a missing `lang` or `alt` or a skipped heading level, and breaks of three rules: [one standalone file](file.md#one-standalone-file) and [trusted libraries only](file.md#trusted-libraries-only) in the file rules, and **Height** in [the design rules](design.md#base-rules-every-file-meets). Fix each problem it reports and run it again. Done when it reports nothing. When `npx` can't run, such as without Node or network, check the file against those three rules by reading it, and say in the hand-over that the linter didn't run.
+
+Then:
+
 - The file uses nothing on the sandbox list in the file rules.
 - The marker is as the file rules say: the same last line as before, or none at all.
 - Every number, name and date in the file appears in the source. Each gap is an open question.
-- Light and dark each set every variable in [the design rules](design.md#the-looks-colour-variables), each colour clears its floor, `--accent-2` sits as far from `--accent` as the table says, and both accents colour something on screen.
+- Light and dark each set every variable in [the design rules](design.md#the-looks-colour-variables), and each colour clears its floor: `node <pageship-docs folder>/references/palette.mjs --check <file>` lists each one that doesn't. Without Node, compare each value with its floor yourself. Both accents colour something on screen.
 
 ## Checks in a browser
 
-Use a browser tool when you have one, such as `agent-browser` or Playwright; without one, skip this section. Open the file from disk and:
+These checks, and the browser steps of the kind and pattern skills, are required whenever you have a browser tool. Use the first one you have:
+
+1. **`html_preview`**, in T3 Code. Pass the file's text as `html`, with a `width` and an `appearance`. It returns a screenshot of the whole page and the console output. A file over 512 KB is too large for it: use agent-browser.
+2. **agent-browser**, in every other harness. `agent-browser open file://<the file's absolute path>`, then `set viewport <width> 800`, `set media light` or `set media dark`, `screenshot <path>`, `console` and `errors`. A step's input uses `click`, `press` and `focus`, and a step's script runs with `eval`.
+3. **Neither.** Skip this section and the skills' browser steps, and take the step a skill gives for a missing browser, where it gives one.
 
-- At 1280px and at 390px wide, confirm the page doesn't scroll sideways: `document.documentElement.scrollWidth` is no larger than `clientWidth`.
-- Look at a screenshot at each width, in light and in dark. Fix overlapping, clipped or unreadable content.
+Some states take an edited copy of the file:
+
+- **axe-core in `html_preview`**: at the end of `<body>`, add a `<script>` holding the text of `<pageship-docs folder>/references/axe.js`. Every preview of the file uses a copy with it.
+- **Dark in `html_preview`**, which doesn't set the colour scheme: change every `prefers-color-scheme: dark` to `prefers-color-scheme: light`, add `<style>:root { color-scheme: dark }</style>` at the end of `<head>`, and pass `appearance: "dark"`.
+- **Reduced motion in `html_preview`**: swap `prefers-reduced-motion: reduce` and `prefers-reduced-motion: no-preference` everywhere. In agent-browser, `set media light reduced-motion`.
+- **Print, in both tools**, which can't emulate it: swap `print` and `screen` in every media query, in `@media` rules and `matchMedia` calls alike, so `@media print` reads `@media screen`.
+- **Input and scripts in `html_preview`**: at the end of `<body>`, add a `<script>` with a `load` listener that takes the steps and logs each result with `console.log`. Click with `element.click()`, which also stands for Enter or Space on a button; press a key with `element.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true, cancelable: true }))`; hover with a `pointerover` event the same way. A script can't press Tab: log each control's `tabIndex`, which is `0` for every control in the tab order, then focus each one in document order with `element.focus()` and log `document.activeElement`. The screenshot shows the page after the listener ran.
+- **A fragment in `html_preview`**, such as `#slide-3`: the copy's first script runs `history.replaceState(null, "", "#slide-3")`.
+
+`html_preview` takes its screenshot right after the page loads, before timers and animations run their course, so a figure that plays in view at load may show its initial state or part of its playback; `pageship-motion`'s check covers its end state. A step that waits, such as letting playback run, takes the skill's step for a missing browser, or is skipped where the skill gives none.
+
+At 1280px and at 390px wide, each in light and in dark:
+
+- Confirm the page doesn't scroll sideways: `document.documentElement.scrollWidth` is no larger than `clientWidth`.
+- Look at the screenshot. Fix overlapping, clipped or unreadable content.
 - Read the console. Fix every error, including failed integrity checks.
-- Use every control by keyboard and confirm it works and shows focus.
+- Run axe-core, which checks accessibility in the rendered page, such as the contrast of each piece of text against what is really behind it. In agent-browser, run `agent-browser eval --stdin < <pageship-docs folder>/references/axe.js`; in `html_preview`, read the lines the copy's script logs. Fix each problem it lists.
+
+Then use every control by keyboard and confirm it works and shows focus. Done when, at both widths in both colour schemes, the page doesn't scroll sideways, the screenshot shows nothing overlapping, clipped or unreadable, the console shows no error, and axe-core lists no problem, and every control works by keyboard and shows focus.
 
 ## Claims