pageship 0.6.0 → 0.6.1

package/dist/cli.mjs

@@ -957,7 +957,21 @@ function isGitHubAccountId(value) {
 	return typeof value === "string" && /^[1-9][0-9]{0,19}(?![\s\S])/u.test(value);
 }
 function validViewer(value) {
-	return record(value) && isGitHubAccountId(value.githubAccountId) && isGitHubLogin(value.login) && (value.name === null || typeof value.name === "string") && typeof value.addedAt === "number" && Number.isSafeInteger(value.addedAt) && value.addedAt >= 0;
+	return record(value) && isGitHubAccountId(value.githubAccountId) && isGitHubLogin(value.login) && (value.name === null || typeof value.name === "string") && typeof value.addedAt === "number" && Number.isSafeInteger(value.addedAt) && value.addedAt >= 0 && typeof value.viewCount === "number" && Number.isSafeInteger(value.viewCount) && value.viewCount >= 0 && (value.lastViewedAt === null || typeof value.lastViewedAt === "number" && Number.isSafeInteger(value.lastViewedAt) && value.lastViewedAt >= 0);
+}
+function normalizeViewer(value) {
+	if (!record(value)) return;
+	const normalized = {
+		...value,
+		...value.viewCount === void 0 ? { viewCount: 0 } : {},
+		...value.lastViewedAt === void 0 ? { lastViewedAt: null } : {}
+	};
+	return validViewer(normalized) ? normalized : void 0;
+}
+function normalizeViewers(value) {
+	if (!Array.isArray(value)) return;
+	const viewers = value.map(normalizeViewer);
+	return viewers.every((viewer) => viewer !== void 0) ? viewers : void 0;
 }
 function validUserMatch(value) {
 	return record(value) && isGitHubAccountId(value.githubAccountId) && isGitHubLogin(value.login);
@@ -997,7 +1011,11 @@ async function getDocumentViewers(baseUrl, id, options = {}) {
 		path: { id }
 	});
 	if (!response?.ok) viewerFailed(response, error);
-	if (data?.status === "listed" && Array.isArray(data.viewers) && data.viewers.every(validViewer)) return data;
+	const viewers = data?.status === "listed" ? normalizeViewers(data.viewers) : void 0;
+	if (data && viewers) return {
+		...data,
+		viewers
+	};
 	throw new Error("Invalid document viewer listing response.");
 }
 /**
@@ -1019,14 +1037,17 @@ async function updateDocumentSharing(baseUrl, id, change, options = {}) {
 		body: change
 	});
 	if (!response?.ok) viewerFailed(response, error);
-	const document = data?.status === "sharing_updated" ? normalizeDocument(data.document) : void 0;
-	if (data && document && (change.visibility === void 0 || document.visibility === change.visibility) && [
-		data.viewers,
-		data.added,
-		data.removed
-	].every((list) => Array.isArray(list) && list.every(validViewer))) return {
-		...data,
-		document
+	const updated = data?.status === "sharing_updated" ? data : void 0;
+	const document = updated && normalizeDocument(updated.document);
+	const viewers = updated && normalizeViewers(updated.viewers);
+	const added = updated && normalizeViewers(updated.added);
+	const removed = updated && normalizeViewers(updated.removed);
+	if (updated && document && viewers && added && removed && (change.visibility === void 0 || document.visibility === change.visibility)) return {
+		...updated,
+		document,
+		viewers,
+		added,
+		removed
 	};
 	throw new Error("Invalid document sharing response.");
 }
@@ -1530,7 +1551,7 @@ function commandLine(command, args) {
 }
 //#endregion
 //#region package.json
-var version = "0.6.0";
+var version = "0.6.1";
 //#endregion
 //#region src/publish.ts
 const execute = promisify(execFile);

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 or viewers, 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.6.0"
+  version: "0.6.1"
 ---
 
 # Pageship

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

@@ -3,7 +3,7 @@ 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.6.0"
+  version: "0.6.1"
 ---
 
 # Chart

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.6.0"
+  version: "0.6.1"
 ---
 
 # 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.6.0"
+  version: "0.6.1"
 ---
 
 # Decision record

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.6.0"
+  version: "0.6.1"
 ---
 
 # Diagram

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

@@ -3,7 +3,7 @@ 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.6.0"
+  version: "0.6.1"
 ---
 
 # Pageship documents

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

@@ -12,7 +12,7 @@ Run the linter, html-validate with the config and rules in this folder:
 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.
+It reports HTML errors, accessibility problems such as a missing `lang` or `alt` or a skipped heading level, and breaks of four rules: [one standalone file](file.md#one-standalone-file), [trusted libraries only](file.md#trusted-libraries-only) and [link previews](file.md#link-previews) 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 four rules by reading it, and say in the hand-over that the linter didn't run.
 
 Then:
 
@@ -51,7 +51,7 @@ Then use every control by keyboard and confirm it works and shows focus. Done wh
 
 ## Claims
 
-Read the file sentence by sentence beside the source, captions, labels and tooltips included. Keep each claim the source states. A claim one step past it goes, or becomes an open question: a cause, when something starts or ends, a count, how far a rule reaches, or a new name for something the source names. A caption claims only what its figure draws. Done when you can point to the source's words behind every sentence.
+Read the file sentence by sentence beside the source, captions, labels, tooltips and the link preview's description included. Keep each claim the source states. A claim one step past it goes, or becomes an open question: a cause, when something starts or ends, a count, how far a rule reaches, or a new name for something the source names. A caption claims only what its figure draws. Done when you can point to the source's words behind every sentence.
 
 ## The structure you added
 

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

@@ -32,6 +32,39 @@ Mermaid, only when a pattern skill calls for it:
 
 Hosted fonts from `https://fonts.googleapis.com/css2?...` through a `<link rel="stylesheet">`, which can't carry `integrity`.
 
+## Link previews
+
+Chat apps and social sites show a card for a shared link, built from tags in the file's `<head>`. Every file carries them, after `<meta charset>`, the viewport and `<title>`:
+
+```html
+<title>Q3 support report</title>
+<meta
+  name="description"
+  content="Ticket volume rose 18% in Q3 while first-reply time held at 2 hours."
+/>
+<meta property="og:type" content="article" />
+<meta property="og:title" content="Q3 support report" />
+<meta
+  property="og:description"
+  content="Ticket volume rose 18% in Q3 while first-reply time held at 2 hours."
+/>
+<meta property="og:image" content="https://example.com/q3/tickets-by-week.png" />
+<meta property="og:image:alt" content="Tickets by week, July to September" />
+<meta property="og:image:width" content="1200" />
+<meta property="og:image:height" content="630" />
+<meta name="twitter:card" content="summary_large_image" />
+<meta name="twitter:image:alt" content="Tickets by week, July to September" />
+```
+
+- **Title.** `<title>` and `og:title` hold the same text: the document's title, as its `h1` gives it.
+- **Description.** `description` and `og:description` hold the same one or two sentences, up to about 160 characters, that state the document's main point as its first lines do. It follows the [content rules](content.md) like any other text in the file.
+- **Type.** `og:type` is `article`.
+- **Image.** The card's image is the first of these that is a PNG, JPEG or GIF file at an `https://` URL: the image or chart that leads the page, then the first image in the page with alt text. Its `alt` becomes `og:image:alt` and `twitter:image:alt`. Its size in pixels, when you measured the image file itself, becomes `og:image:width` and `og:image:height`; a size the page displays it at is not that size, so without a measured size leave those two out. Sites can't show an inline SVG or a `data:` URL, so a page whose images and charts are only those leaves out every image tag.
+- **Card.** `twitter:card` is `summary_large_image` with an image and `summary` without. X reads the title, description and image from the `og:` tags, so the only other `twitter:` tag is `twitter:image:alt`.
+- **No address.** Leave out `og:url` and `<link rel="canonical">`: the file doesn't know where it will be published, and sites use the address they fetched.
+
+An edit that changes the title, the main point or the image updates these tags to match.
+
 ## The Pageship sandbox
 
 A published file runs with scripts allowed and everything else blocked, so it works without these:

package/dist/skills/pageship-docs/references/html-validate-rules.mjs

@@ -316,11 +316,105 @@ class NoViewportHeight extends Rule {
   }
 }
 
+const entities = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+
+/** Text with its character references decoded and its runs of white space as single spaces. */
+const plainText = (text) =>
+  text
+    .replace(/&(?:#(\d+)|#x([\da-f]+)|(\w+));/giu, (match, decimal, hex, name) =>
+      decimal || hex
+        ? String.fromCodePoint(Number.parseInt(decimal ?? hex, decimal ? 10 : 16))
+        : (entities[name.toLowerCase()] ?? match),
+    )
+    .replace(/\s+/gu, " ")
+    .trim();
+
+/** The tags a link preview reads. Others, such as one `theme-color` per colour scheme, may repeat. */
+const previewTags = /^(?:description|og:.+|twitter:.+)$/u;
+
+/** An `https://` URL whose path doesn't end in `.svg`, which link previews don't show. */
+const previewImage = /^https:\/\/(?![^?#]*\.svg(?:[?#]|$))/iu;
+
+class LinkPreview extends Rule {
+  documentation() {
+    return {
+      description:
+        "Give the file the link preview tags in the file rules (references/file.md): a description, og:type, og:title and og:description matching the title and description, twitter:card, and an og:image only at an https:// URL to an image that isn't SVG, with og:image:alt and twitter:image:alt.",
+    };
+  }
+
+  setup() {
+    this.on("dom:ready", ({ document }) => {
+      const head = document.querySelector("head");
+      if (!head) return;
+      /** Each `<meta>` content by its `name` or `property`, with the element that has it. */
+      const metas = new Map();
+      for (const element of document.querySelectorAll("meta")) {
+        const key = attributeValue(element, "property") ?? attributeValue(element, "name");
+        if (!previewTags.test(key ?? "")) continue;
+        if (metas.has(key)) {
+          this.report(element, `The file has a second ${key} tag: keep one`);
+          continue;
+        }
+        metas.set(key, { element, content: plainText(attributeValue(element, "content") ?? "") });
+      }
+      const content = (key) => metas.get(key)?.content ?? "";
+      const at = (key) => metas.get(key)?.element ?? head;
+
+      for (const key of ["description", "og:type", "og:title", "og:description", "twitter:card"]) {
+        if (!content(key)) {
+          this.report(
+            at(key),
+            `The file needs the ${key} tag with content, as the file rules give`,
+          );
+        }
+      }
+      const title = document.querySelector("title");
+      if (title && content("og:title") && content("og:title") !== plainText(title.textContent)) {
+        this.report(at("og:title"), "og:title must hold the same text as <title>");
+      }
+      if (content("og:description") && content("og:description") !== content("description")) {
+        this.report(at("og:description"), "og:description must hold the same text as description");
+      }
+
+      const image = content("og:image");
+      if (metas.has("og:image") && !image) {
+        this.report(
+          at("og:image"),
+          "og:image is empty: give the image's URL, or leave out the image tags",
+        );
+      }
+      if (image && !previewImage.test(image)) {
+        this.report(
+          at("og:image"),
+          `og:image "${image}" is not an https:// URL to an image a link preview shows, such as a PNG or JPEG file: use one, or leave out the image tags`,
+        );
+      }
+      for (const key of ["og:image:alt", "twitter:image:alt"]) {
+        if (image && !content(key)) {
+          this.report(at("og:image"), `og:image needs ${key}, the image's alt text`);
+        }
+      }
+      if (!image && (metas.has("og:image:alt") || metas.has("twitter:image:alt"))) {
+        this.report(head, "The file has image alt tags but no og:image: leave them out too");
+      }
+      const card = image ? "summary_large_image" : "summary";
+      if (content("twitter:card") && content("twitter:card") !== card) {
+        this.report(
+          at("twitter:card"),
+          `twitter:card must be "${card}" for a file ${image ? "with" : "without"} og:image`,
+        );
+      }
+    });
+  }
+}
+
 export default {
   name: "pageship",
   rules: {
     "pageship/trusted-libraries": TrustedLibraries,
     "pageship/no-relative-paths": NoRelativePaths,
     "pageship/no-viewport-height": NoViewportHeight,
+    "pageship/link-preview": LinkPreview,
   },
 };

package/dist/skills/pageship-docs/references/html-validate.json

@@ -8,6 +8,7 @@
     "heading-level": ["error", { "allowMultipleH1": false }],
     "pageship/trusted-libraries": "error",
     "pageship/no-relative-paths": "error",
-    "pageship/no-viewport-height": "error"
+    "pageship/no-viewport-height": "error",
+    "pageship/link-preview": "error"
   }
 }

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

@@ -3,7 +3,7 @@ name: pageship-explainer
 description: HTML explainers, as the second step of pageship-docs. For any request to explain how something works, or to write, regenerate, edit or move an explainer, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.6.0"
+  version: "0.6.1"
 ---
 
 # Explainer

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

@@ -3,7 +3,7 @@ name: pageship-interaction
 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 controls in a Pageship HTML document, such as stepping through stages, tracing a path, tabs, filters, revealing detail and pointer states on charts and diagrams, loaded by a pageship- kind skill before it adds any control."
 license: MIT
 metadata:
-  version: "0.6.0"
+  version: "0.6.1"
 ---
 
 # Interaction

package/dist/skills/pageship-key-figures/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-key-figures
 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 the few numbers and callouts a Pageship HTML document opens with, loaded by a pageship- kind skill before it writes key figures."
 license: MIT
 metadata:
-  version: "0.6.0"
+  version: "0.6.1"
 ---
 
 # Key figures

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

@@ -3,7 +3,7 @@ name: pageship-media
 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 images, video and audio in a Pageship HTML document, loaded by a pageship- kind skill before it shows media."
 license: MIT
 metadata:
-  version: "0.6.0"
+  version: "0.6.1"
 ---
 
 # Media

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

@@ -3,7 +3,7 @@ name: pageship-motion
 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 animation and transitions in a Pageship HTML document, such as a chart that grows into view, a sequence that plays through a diagram, or a marker moving along a path, loaded by a pageship- kind skill before it draws a chart, a graphic or a sequence, or before anything else on the page moves."
 license: MIT
 metadata:
-  version: "0.6.0"
+  version: "0.6.1"
 ---
 
 # Motion

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

@@ -3,7 +3,7 @@ name: pageship-plan
 description: HTML plans, as the second step of pageship-docs. For any request to write, regenerate, edit or move a plan, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.6.0"
+  version: "0.6.1"
 ---
 
 # Plan

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

@@ -3,7 +3,7 @@ name: pageship-report
 description: HTML reports, as the second step of pageship-docs. For any request to write, regenerate, edit or move a report, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.6.0"
+  version: "0.6.1"
 ---
 
 # Report

package/dist/skills/pageship-review-report/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-review-report
 description: HTML review reports, as the second step of pageship-docs. For any request to review a change or a plan and write up the findings, or to write, regenerate, edit or move a review report, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.6.0"
+  version: "0.6.1"
 ---
 
 # Review report

package/dist/skills/pageship-slide-deck/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-slide-deck
 description: HTML slide decks, as the second step of pageship-docs. For any request to make slides or a presentation, or to regenerate, edit or move a deck, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.6.0"
+  version: "0.6.1"
 ---
 
 # Slide deck

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

@@ -3,7 +3,7 @@ name: pageship-spec
 description: HTML specs, as the second step of pageship-docs. For any request to write, regenerate, edit or move a spec, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.6.0"
+  version: "0.6.1"
 ---
 
 # Spec

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

@@ -3,7 +3,7 @@ name: pageship-table
 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 tables in a Pageship HTML document, loaded by a pageship- kind skill before it writes a table."
 license: MIT
 metadata:
-  version: "0.6.0"
+  version: "0.6.1"
 ---
 
 # Table

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pageship",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Pageship CLI for checking server API compatibility.",
   "license": "UNLICENSED",
   "repository": {