@foldspace_npm/harness 0.1.36 → 0.1.38

package/CLAUDE.md

@@ -516,6 +516,14 @@ save or publish:**
 <committed_paths, comma-separated>`, so your own save is not taken for
 someone else's.
 
+**None of this is said to the human.** No develop, lines of work, pulling,
+merging, conflicts, commits or branches - not in a status line, not when
+something goes wrong. When nobody else saved, say nothing. When someone did,
+one line: *"I brought in changes a teammate saved."* When a file had changes
+both here and in theirs, name the experience in their words: *"A teammate
+also changed the patient table; I kept theirs and put my change on top."*
+Updating the harness is *"updating the Foldspace tools"*, never pulling it.
+
 ## Done, and what you say at the end
 
 A first session is done when the customer has seen one experience answer from
@@ -551,15 +559,27 @@ you offer the second wave:
    again. If it works, invite them to try it in that window (a reload takes
    it off dev), and run `npx foldspace attach --daemon` before you build
    anything else. If `published` says this window cannot show dev, say so in
-   one sentence, attach again, and stop at step 1.
+   one sentence, attach again, and do not offer production yourself - but
+   publish it when the human asks (below).
 3. Once the dev check passed, ask before publishing for their users:
    *"Shall I publish it for your users?"* On a yes, publish to production. On a not yet, it stays on dev:
    say so in one line and carry on.
 
-Steps 2 and 3 need a site that loads this agent by itself. If you attached
-with `--bootstrap` or `--replace`, it does not yet: do step 1, keep attach
-running, and give the answer below for the rest - their site loading the agent
-is the step the Foldspace team does with them.
+**Publishing for their users is the human's call, not a step they earn.**
+When they ask for it - at any point, whether or not the dev check ran or
+could run - that is the yes: publish to production the way `repo_read`
+command `instructions` says, in that turn. Do not ask them to confirm again,
+and do not explain the process. When dev was not checked, one line as you
+publish: *"I couldn't check it on dev here, so it goes out as you tried it
+in the test window."* Only a refusal from the Foldspace tools stops it (below).
+
+Step 2 needs a site that loads this agent by itself. If you attached with
+`--bootstrap` or `--replace`, it does not yet: do step 1, keep attach
+running, and do not offer production yourself - their site loading the agent
+is the step the Foldspace team does with them. When the human asks for
+production anyway, publish it (above), and add one line: *"Your users will
+see it once your site loads the agent - that's the step the Foldspace team
+does with you."*
 
 A save refused because someone saved after you read is not final: pull again
 (**Several builders, one agent**), put your change on top and save. Any other refusal from the Foldspace tools

package/bin/share.mjs

@@ -1,15 +1,26 @@
 #!/usr/bin/env node
-// foldspace share <inspect|upload> [<video.mp4>] [--poster <file.jpg>] [--targets '<json>']
+// foldspace share <inspect|upload> [<video.mp4>] [--poster <file.jpg>] [--title '<title>'] [--card <file.jpg>]
+//                                 [--targets '<json>' | --targets-file <path>]
 //
 //   inspect - sizes and checks the MP4 and its poster here; uploads nothing.
-//             Its video.bytes and poster.bytes go into the MCP tool
-//             create_video_share.
-//   upload  - sends both files to Foldspace's video storage with the one-time
-//             targets create_video_share returned (its upload command), then
-//             the agent calls publish_video_share for the link.
+//             With --title (the title the human chose) it also draws the
+//             link's 1200x630 preview card next to the MP4 (<name>.card.jpg)
+//             in a hidden Chrome; --card uses a card someone made instead.
+//             Its video.bytes, poster.bytes and card.bytes go into the MCP
+//             tool create_video_share (card_bytes, with the same title).
+//             No Chrome, or the card fails: `card: null` and `cardReason`,
+//             and the share goes ahead without a card.
+//   upload  - sends the files to Foldspace's video storage with the one-time
+//             targets create_video_share returned (its upload command): the
+//             MP4, the poster, then the card when there is a card target.
+//             Then the agent calls publish_video_share for the link.
+//             --targets-file reads the same JSON from a file, for shells that
+//             break a quoted JSON argument (Windows PowerShell and cmd).
 //
 // The CLI holds no Foldspace sign-in: creating and publishing a share are MCP
-// tools, only the bytes go through here. The targets are never printed.
+// tools, only the bytes go through here. The targets are never printed, and a
+// targets file is never deleted: it holds one-time upload targets, the
+// human's to delete.
 // Sharing is always the human's call: run upload only after they said yes.
 
 import path from "node:path";
@@ -17,38 +28,71 @@ import path from "node:path";
 import { parseArgs, printJson } from "../src/cdp-client.mjs";
 import { recordEvent } from "../src/session-events.mjs";
 import { resolveProjectDir } from "../src/upgrade.mjs";
-import { ShareError, defaultVideo, inspectForShare, parseTargets, posterFor, resumableUpload } from "../src/video/share.mjs";
+import { renderCard } from "../src/video/card.mjs";
+import {
+  ShareError,
+  cardFor,
+  defaultVideo,
+  inspectCard,
+  inspectForShare,
+  parseTargets,
+  posterFor,
+  readTargets,
+  resumableUpload,
+} from "../src/video/share.mjs";
 
-const { flags, rest } = parseArgs(process.argv.slice(2), ["poster", "targets"]);
+const USAGE =
+  "Usage: foldspace share <inspect|upload> [<video.mp4>] [--poster <file.jpg>] [--title \"<title>\"] [--card <file.jpg>] [--targets '<json>' | --targets-file <path>]";
+
+const { flags, rest } = parseArgs(process.argv.slice(2), ["poster", "targets", "targets-file", "title", "card"]);
 const [action, videoArg] = rest;
 const projectDir = path.resolve(resolveProjectDir());
 
 try {
-  if (action !== "inspect" && action !== "upload") {
-    throw new ShareError("USAGE", "Usage: foldspace share <inspect|upload> [<video.mp4>] [--poster <file.jpg>] [--targets '<json>']");
-  }
+  if (action !== "inspect" && action !== "upload") throw new ShareError("USAGE", USAGE);
   const videoPath = videoArg ? path.resolve(projectDir, videoArg) : defaultVideo(projectDir);
   const posterPath = flags.poster ? path.resolve(projectDir, String(flags.poster)) : posterFor(videoPath);
+  const cardPath = typeof flags.card === "string" ? path.resolve(projectDir, flags.card) : cardFor(videoPath);
   const files = inspectForShare({ videoPath, posterPath });
 
   if (action === "inspect") {
+    const { card, reason } = await previewCard(files.video.durationS, cardPath);
     printJson({
       ok: true,
       video: { path: path.relative(projectDir, files.video.path), bytes: files.video.bytes, durationS: round(files.video.durationS) },
       poster: { path: path.relative(projectDir, files.poster.path), bytes: files.poster.bytes },
-      next: "Only if the human agreed to share it: call create_video_share with a title, video_bytes and poster_bytes, then run the upload command it returns.",
+      card: card ? { path: path.relative(projectDir, card.path), bytes: card.bytes } : null,
+      ...(card ? {} : { cardReason: reason }),
+      next: card
+        ? "Only if the human agreed to share it: call create_video_share with the same title, a description if they gave one (up to 500 characters), video_bytes, poster_bytes and card_bytes, then run the upload command it returns."
+        : "Only if the human agreed to share it: call create_video_share with a title, a description if they gave one (up to 500 characters), video_bytes and poster_bytes, then run the upload command it returns.",
     });
   } else {
-    if (!flags.targets) throw new ShareError("BAD_TARGETS", "--targets is required: run the upload command create_video_share returned.");
-    const targets = parseTargets(flags.targets);
+    const { text, source } = readTargets({ targets: flags.targets, targetsFile: flags["targets-file"] }, projectDir);
+    const targets = parseTargets(text, source);
+    // Checked before anything is sent: a card target with no card would fail publish after the whole upload.
+    let card = null;
+    if (targets.card) {
+      try {
+        card = inspectCard(cardPath);
+      } catch (error) {
+        if (!(error instanceof ShareError) || error.code !== "NO_CARD") throw error;
+        throw new ShareError(
+          "NO_CARD",
+          `create_video_share returned a card target, but there is no preview card at ${path.relative(projectDir, cardPath)}. Run \`npx foldspace share inspect --title '<the same title>'\` again (pass upload the same --card if you gave inspect one), or call create_video_share again without card_bytes.`,
+        );
+      }
+    }
     await resumableUpload(targets.video, files.video.path, { label: "video" });
     await resumableUpload(targets.poster, files.poster.path, { label: "poster" });
-    recordEvent(projectDir, "share-upload", { videoBytes: files.video.bytes });
+    if (card) await resumableUpload(targets.card, card.path, { label: "preview card" });
+    recordEvent(projectDir, "share-upload", { videoBytes: files.video.bytes, card: Boolean(card) });
     printJson({
       ok: true,
       status: "uploaded",
       videoBytes: files.video.bytes,
       posterBytes: files.poster.bytes,
+      ...(card ? { cardBytes: card.bytes } : {}),
       next: "Call publish_video_share with the share_id from create_video_share; it returns the public link.",
     });
   }
@@ -58,6 +102,20 @@ try {
   process.exitCode = 1;
 }
 
+/**
+ * The preview card for inspect: the one given with --card (checked, and a bad
+ * one refused - it was asked for), else one drawn for --title at `cardPath`.
+ * Drawing never fails the share: no card, and the reason.
+ */
+async function previewCard(durationS, cardPath) {
+  if (typeof flags.card === "string") return { card: inspectCard(cardPath) };
+  const title = typeof flags.title === "string" ? flags.title.trim() : "";
+  if (!title) {
+    return { card: null, reason: "No --title, so no preview card: run inspect again with --title '<the title the human chose>' for one." };
+  }
+  return renderCard({ title, durationS, outPath: cardPath });
+}
+
 function round(seconds) {
   return Math.round(seconds * 10) / 10;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/src/cli-registry.mjs

@@ -540,18 +540,19 @@ export const CLI_COMMANDS = Object.freeze([
     name: "share",
     entry: "share.mjs",
     group: "share",
-    summary: "Size and check a video for a Foldspace share link, then upload it with the targets create_video_share returned",
-    usage: "foldspace share <inspect|upload> [<video.mp4>] [--poster <file.jpg>] [--targets '<json>']",
+    summary: "Size and check a video for a Foldspace share link and draw its preview card, then upload them with the targets create_video_share returned",
+    usage:
+      "foldspace share <inspect|upload> [<video.mp4>] [--poster <file.jpg>] [--title \"<title>\"] [--card <file.jpg>] [--targets '<json>' | --targets-file <path>]",
     risk: "remote-upload",
     environment: "node",
-    environmentVariables: ["FOLDSPACE_PROJECT_DIR"],
-    capabilities: ["video.upload"],
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CHROME_PATH"],
+    capabilities: ["video.upload", "browser.launch"],
     positionals: [
       Object.freeze({
         name: "action",
         required: true,
         description:
-          "inspect: size and check the MP4 and its poster here, uploading nothing | upload: send both to Foldspace's video storage with the targets create_video_share returned",
+          "inspect: size and check the MP4 and its poster here, and draw the preview card for --title, uploading nothing | upload: send them to Foldspace's video storage with the targets create_video_share returned",
       }),
       Object.freeze({
         name: "video",
@@ -561,20 +562,34 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     options: [
       value("--poster", "file.jpg", "The JPEG poster", { default: "the MP4's name with .jpg" }),
+      value(
+        "--title",
+        "title",
+        "inspect only: the title the human chose (the same one goes to create_video_share); draws the link's 1200x630 preview card as the MP4's name with .card.jpg",
+      ),
+      value("--card", "file.jpg", "A 1200x630 JPEG preview card to use instead of drawing one (at most 1 MiB)", {
+        default: "the MP4's name with .card.jpg",
+      }),
       value("--targets", "json", "upload only: the targets JSON exactly as the upload command from create_video_share has it"),
+      value(
+        "--targets-file",
+        "path",
+        "upload only, instead of --targets: a file holding that JSON, for shells that break a quoted JSON argument (Windows PowerShell, cmd). It holds one-time upload targets: never commit it; the human may delete it after",
+      ),
     ],
     prerequisites: [
-      "An H.264 MP4 with its moov box first (what `record` makes) and a JPEG poster",
+      "An H.264 MP4 with its moov box first (what `record` makes), at most 10 minutes, and a JPEG poster",
+      "inspect --title: Google Chrome to draw the preview card; without it inspect still succeeds, with no card",
       "upload: the human said yes to a public link, and the Foldspace MCP tool create_video_share returned the upload command (its targets last 30 minutes)",
     ],
     effects: [
-      "inspect reads the two files and nothing else",
-      "upload sends the MP4 and the poster to Foldspace's video storage, and only there; it reads no Foldspace sign-in",
-      "Never prints the upload targets: each is a one-time credential for one file",
+      "inspect reads the two files; with --title it draws the preview card in a hidden Chrome and writes it next to the MP4. A card that cannot be drawn gives `card: null` and `cardReason`, never a failure",
+      "upload sends the MP4, the poster and - when create_video_share returned a card target - the preview card to Foldspace's video storage, and only there; it reads no Foldspace sign-in",
+      "Never prints the upload targets: each is a one-time credential for one file. A --targets-file is read, never deleted",
       "Anyone with the link publish_video_share returns can watch the video, which shows real data from the account",
     ],
     next: [
-      "After inspect, with the human's yes: create_video_share with a title, video_bytes and poster_bytes, then run its upload command",
+      "After inspect, with the human's yes: create_video_share with the same title, an optional description, video_bytes, poster_bytes and card_bytes (when inspect made a card), then run its upload command",
       "After upload: publish_video_share with the share_id; give the human the link",
     ],
   }),

package/src/video/README.md

@@ -1,4 +1,4 @@
-# src/video - what `foldspace record` is made of
+# src/video - what `foldspace record` and `foldspace share` are made of
 
 | File | What it is |
 |---|---|
@@ -6,11 +6,13 @@
 | `timeline.mjs` | Pure timing and layout: shortened waits, caption fades, dissolves, the caption card (its rows, the line wrapped evenly in two, the `*highlights*`), where the logo goes, colour contrast. Runs in Node (tests) and in the composer page |
 | `scenes.mjs` | `video/scenes.json`: checking it, the five capability names (one list: renaming a pill is a one-line change), each caption's "2 of 4", the file name |
 | `compose.mjs` | The plan, a short-lived 127.0.0.1 server and a hidden Chrome that makes the MP4 |
-| `composer/` | The page that draws each frame on a canvas, encodes H.264 with WebCodecs and muxes |
+| `composer/` | The page that draws each frame on a canvas, encodes H.264 with WebCodecs and muxes; and `card.html`, the page that draws a share link's preview card |
+| `share.mjs` | `foldspace share`: the checks `inspect` runs before anything leaves the machine (the server's caps: 500 MB, 10 minutes, fast-start MP4, JPEG poster and card), the upload targets (`--targets` or `--targets-file`, Google Cloud Storage only) and the resumable upload |
+| `card.mjs` | The share link's 1200 x 630 preview card (og:image) for `inspect --title`: drawn in a hidden Chrome as `compose.mjs` starts one, a JPEG under 300 KB (WhatsApp shows no bigger preview), next to the MP4 as `<name>.card.jpg`. Optional: without Chrome there is no card and the link shows the poster |
 | `brand.mjs` | Foldspace's brand, as its product video's storyboard draws it - its one blue on black, white, one muted grey - the caption card's fill and edge, and the logo files. Never the app's colours |
 
-Nothing is installed and nothing native runs: the video is encoded by the
-Google Chrome that is already there.
+Nothing is installed and nothing native runs: the video is encoded, and the
+preview card drawn, by the Google Chrome that is already there.
 
 ## Vendored, with their licences
 

package/src/video/card.mjs

@@ -0,0 +1,57 @@
+// The preview card of a share link: what WhatsApp, Slack, LinkedIn or X show
+// for the link (the share page's og:image). Without one the page offers the
+// poster, which is a frame of the video at its own size, so the card is
+// optional end to end: making it never stops a share.
+//
+// Drawn by composer/card.mjs in a hidden Chrome, started the way the video's
+// composer is (compose.mjs: a throwaway profile, a 127.0.0.1 server under a
+// random token), and written next to the video as <name>.card.jpg.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { findChrome } from "../chrome-binary.mjs";
+import { renderPage } from "./compose.mjs";
+import { CARD_HEIGHT, CARD_WIDTH, formatLength } from "./share.mjs";
+
+/** WhatsApp shows no preview image over 300 KB, so a card we draw stays under it. */
+export const CARD_TARGET_BYTES = 300 * 1000;
+// The first quality under CARD_TARGET_BYTES is kept; a dark card with one
+// title is about 60 KB at the first.
+const CARD_QUALITIES = Object.freeze([0.9, 0.82, 0.74, 0.66, 0.58, 0.5]);
+const CARD_TIMEOUT_MS = 60_000;
+
+/**
+ * Draw the card for `title` and a video `durationS` long into `outPath`.
+ * Never throws: { card: { path, bytes } }, or { card: null, reason } when it
+ * could not be made (no Chrome, Chrome failed, too big) - the share then goes
+ * ahead without one.
+ */
+export async function renderCard({ title, durationS, outPath, chromePath = findChrome(), timeoutMs = CARD_TIMEOUT_MS }) {
+  const without = "the share page shows the poster instead";
+  if (!chromePath) {
+    return { card: null, reason: `No Google Chrome here to draw the preview card (set CHROME_PATH to one); ${without}.` };
+  }
+  try {
+    const plan = {
+      width: CARD_WIDTH,
+      height: CARD_HEIGHT,
+      title: String(title).replace(/\s+/g, " ").trim(),
+      length: formatLength(durationS),
+      maxBytes: CARD_TARGET_BYTES,
+      qualities: CARD_QUALITIES,
+    };
+    const result = await renderPage({ plan, page: "composer/card.html", chromePath, what: "the preview card", timeoutMs });
+    const jpeg = result.card;
+    if (!jpeg || jpeg.length > CARD_TARGET_BYTES || !(jpeg[0] === 0xff && jpeg[1] === 0xd8 && jpeg[2] === 0xff)) {
+      return { card: null, reason: `The preview card did not come out as a JPEG under ${CARD_TARGET_BYTES / 1000} KB; ${without}.` };
+    }
+    // Written whole or not at all: a half-written card would be uploaded as it is.
+    const partial = `${outPath}.partial`;
+    fs.writeFileSync(partial, jpeg);
+    fs.renameSync(partial, outPath);
+    return { card: { path: path.resolve(outPath), bytes: jpeg.length } };
+  } catch (error) {
+    return { card: null, reason: `The preview card was not made (${error instanceof Error ? error.message : String(error)}); ${without}.` };
+  }
+}

package/src/video/compose.mjs

@@ -288,10 +288,11 @@ function inside(root, relative) {
  * The page's server: 127.0.0.1 only, every path under a random token, so no
  * other page or process on the machine can guess its way to the recorded
  * pictures (they show the customer's real data). Resolves `done` when the
- * page has posted the video, or fails with what the page reported.
+ * page has posted what it made, or fails with what the page reported.
+ * Without a `recordDir` (the share card) no recording is served.
  */
-function startServer({ plan, recordDir: givenDir, onProgress }) {
-  const recordDir = path.resolve(givenDir);
+function startServer({ plan, recordDir: givenDir, page, onProgress }) {
+  const recordDir = givenDir ? path.resolve(givenDir) : null;
   const token = crypto.randomBytes(16).toString("hex");
   const posted = {};
   let settle;
@@ -344,7 +345,7 @@ function startServer({ plan, recordDir: givenDir, onProgress }) {
       response.end(JSON.stringify(plan));
       return;
     }
-    if (rest.startsWith("rec/")) file = inside(recordDir, rest.slice(4));
+    if (rest.startsWith("rec/")) file = recordDir ? inside(recordDir, rest.slice(4)) : null;
     else if (STATIC_FILES.includes(rest) || STATIC_ROOTS.includes(rest.split("/")[0])) file = inside(videoRoot, rest);
     if (!file || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
       response.writeHead(404).end();
@@ -360,7 +361,7 @@ function startServer({ plan, recordDir: givenDir, onProgress }) {
     server.listen(0, "127.0.0.1", () => {
       const { port } = server.address();
       resolve({
-        url: `http://127.0.0.1:${port}/${token}/composer/index.html`,
+        url: `http://127.0.0.1:${port}/${token}/${page}`,
         finished,
         close: () => new Promise((done) => server.close(() => done())),
         fail: (error) => settle.reject(error),
@@ -369,15 +370,19 @@ function startServer({ plan, recordDir: givenDir, onProgress }) {
   });
 }
 
-/** Run the composer page in a hidden Chrome; returns { mp4, poster, done }. */
-export async function renderInChrome({ plan, recordDir, chromePath, onProgress, timeoutMs = 15 * 60 * 1000 }) {
-  const server = await startServer({ plan, recordDir, onProgress });
+/**
+ * Run one of the composer's pages (`page`, under src/video/) in a hidden
+ * Chrome; returns every file it posted, by name, and its `done` report.
+ * `what` names what it makes, for the errors: "the video", "the preview card".
+ */
+export async function renderPage({ plan, recordDir = null, page, chromePath, onProgress, what, timeoutMs }) {
+  const server = await startServer({ plan, recordDir, page, onProgress });
   const chrome = launchHeadless(chromePath, server.url);
   chrome.child.on("exit", (code, signal) =>
     server.fail(
       new VideoError(
         "chrome_exited",
-        `The hidden Chrome closed before the video was made (${signal ? `stopped by ${signal}` : `exit code ${code}`}).`,
+        `The hidden Chrome closed before ${what} was made (${signal ? `stopped by ${signal}` : `exit code ${code}`}).`,
       ),
     ),
   );
@@ -385,13 +390,11 @@ export async function renderInChrome({ plan, recordDir, chromePath, onProgress,
     server.fail(new VideoError("chrome_failed", `Could not start Chrome at ${chromePath}: ${error.message}`)),
   );
   const timer = setTimeout(
-    () => server.fail(new VideoError("timeout", `The video was not made within ${Math.round(timeoutMs / 60000)} minutes.`)),
+    () => server.fail(new VideoError("timeout", `${capitalized(what)} was not made within ${minutes(timeoutMs)}.`)),
     timeoutMs,
   );
   try {
-    const result = await server.finished;
-    if (!result.out) throw new VideoError("page_error", "The composer page finished without a video.");
-    return { mp4: result.out, poster: result.poster || null, done: result.done };
+    return await server.finished;
   } finally {
     clearTimeout(timer);
     await chrome.close();
@@ -399,6 +402,22 @@ export async function renderInChrome({ plan, recordDir, chromePath, onProgress,
   }
 }
 
+/** Run the composer page in a hidden Chrome; returns { mp4, poster, done }. */
+export async function renderInChrome({ plan, recordDir, chromePath, onProgress, timeoutMs = 15 * 60 * 1000 }) {
+  const result = await renderPage({ plan, recordDir, page: "composer/index.html", chromePath, onProgress, what: "the video", timeoutMs });
+  if (!result.out) throw new VideoError("page_error", "The composer page finished without a video.");
+  return { mp4: result.out, poster: result.poster || null, done: result.done };
+}
+
+function capitalized(text) {
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+function minutes(ms) {
+  const count = Math.max(1, Math.round(ms / 60000));
+  return count === 1 ? "a minute" : `${count} minutes`;
+}
+
 const PROBE_PAGE = `<!doctype html><meta charset="utf-8"><script type="module">
 const configs = ["avc1.640028", "avc1.4d0028", "avc1.42e028"].map((codec) => ({
   codec, width: 1920, height: 1080, bitrate: 8000000, framerate: 30, avc: { format: "avc" } }));

package/src/video/composer/card.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>foldspace share - preview card</title>
+<style>html, body { margin: 0; background: #000000; }</style>
+</head>
+<body>
+<!-- Loaded in a hidden Chrome by `foldspace share inspect`. It draws the
+     share link's preview card and hands the JPEG back; nothing here is ever
+     shown. -->
+<script type="module" src="card.mjs"></script>
+</body>
+</html>

package/src/video/composer/card.mjs

@@ -0,0 +1,166 @@
+// The share link's preview card: runs in a hidden Chrome that `foldspace
+// share inspect` launches. It reads the plan (the title, the length, the size
+// cap), draws the card on a canvas - what a chat or a feed shows for the link
+// (og:image) - and posts it back as a JPEG under the cap.
+//
+// 1200 x 630, in Foldspace's brand as the video's own cards draw it: black,
+// the title in white Poppins ExtraBold, a big play button in the brand blue,
+// the length in a small pill, the official white wordmark. The play button
+// and the title are centred, so a chat that crops the card square still
+// shows both.
+
+import { BRAND, LOGO_FILES, WORDMARK_RATIO } from "../brand.mjs";
+import { parseHex, wrapWords } from "../timeline.mjs";
+
+const FONT = "Poppins, Roboto, sans-serif";
+const rgba = (hex, alpha) => `rgba(${parseHex(hex).join(", ")}, ${alpha})`;
+const font = (weight, size) => `${weight} ${size}px ${FONT}`;
+
+const post = (name, body, type = "application/json") =>
+  fetch(`../${name}`, { method: "POST", body, headers: { "content-type": type } });
+const fail = (code, message) => post("fail", JSON.stringify({ code, message: String(message || code) }));
+
+window.addEventListener("error", (event) => fail("page_error", event.message));
+window.addEventListener("unhandledrejection", (event) => fail("page_error", event.reason?.message || event.reason));
+
+// On the 1200 x 630 card. A title stays on one line down to `titleOneLine`,
+// then takes two down to `titleMin`; past that its end gives way to "...".
+const CARD = {
+  side: 64, // the logo's and the pill's distance from the edges
+  logo: 28, // the wordmark's height
+  play: 86, // the play button's radius
+  glow: 250, // the radius of the blue glow behind it
+  gap: 46, // between the play button and the title
+  title: 60,
+  titleOneLine: 50,
+  titleMin: 40,
+  titleLines: 2,
+  titleWidth: 1000,
+  lineHeight: 1.18,
+  pill: 26, // the length's text size
+  pillPadX: 16,
+  pillPadY: 7,
+};
+
+async function loadFonts() {
+  for (const [file, weight] of [
+    ["Poppins-SemiBold.woff2", "600"],
+    ["Poppins-ExtraBold.woff2", "800"],
+  ]) {
+    const face = new FontFace("Poppins", `url(../fonts/${file})`, { weight });
+    await face.load();
+    document.fonts.add(face);
+  }
+}
+
+async function loadImage(url) {
+  const image = new Image();
+  image.src = url;
+  await image.decode();
+  return image;
+}
+
+/** One line if it fits big enough, else the largest size for two lines; at the smallest, cut with "...". */
+function fitTitle(ctx, title) {
+  const measure = (value) => ctx.measureText(value).width;
+  for (const [count, min] of [
+    [1, CARD.titleOneLine],
+    [CARD.titleLines, CARD.titleMin],
+  ]) {
+    for (let size = CARD.title; size >= min; size -= 2) {
+      ctx.font = font(800, size);
+      const lines = wrapWords(title, CARD.titleWidth, measure);
+      if (lines.length <= count && lines.every((line) => measure(line) <= CARD.titleWidth)) return { size, lines };
+    }
+  }
+  ctx.font = font(800, CARD.titleMin);
+  const lines = wrapWords(title, CARD.titleWidth, measure).slice(0, CARD.titleLines);
+  const last = lines.length - 1;
+  // The last line always ends in "..." here: either more words follow it, or it is one word too wide.
+  let cut = lines[last];
+  while (cut && measure(`${cut}...`) > CARD.titleWidth) cut = cut.slice(0, -1);
+  lines[last] = `${cut.trimEnd()}...`;
+  for (let index = 0; index < last; index++) {
+    while (measure(lines[index]) > CARD.titleWidth) lines[index] = lines[index].slice(0, -1);
+  }
+  return { size: CARD.titleMin, lines };
+}
+
+function drawCard(ctx, plan, logo) {
+  const { width, height } = plan;
+  ctx.fillStyle = BRAND.black;
+  ctx.fillRect(0, 0, width, height);
+
+  const title = fitTitle(ctx, plan.title);
+  const step = title.size * CARD.lineHeight;
+  const block = CARD.play * 2 + CARD.gap + title.lines.length * step;
+  const cx = width / 2;
+  const top = Math.round((height - block) / 2);
+  const cy = top + CARD.play;
+
+  // The play button: the brand blue on a soft glow of itself, a white triangle
+  // nudged right so it looks centred (a triangle's middle is not its box's).
+  const glow = ctx.createRadialGradient(cx, cy, CARD.play * 0.6, cx, cy, CARD.glow);
+  glow.addColorStop(0, rgba(BRAND.blue, 0.38));
+  glow.addColorStop(1, rgba(BRAND.blue, 0));
+  ctx.fillStyle = glow;
+  ctx.fillRect(cx - CARD.glow, cy - CARD.glow, CARD.glow * 2, CARD.glow * 2);
+  ctx.fillStyle = BRAND.blue;
+  ctx.beginPath();
+  ctx.arc(cx, cy, CARD.play, 0, Math.PI * 2);
+  ctx.fill();
+  const side = CARD.play * 0.78;
+  const nudge = CARD.play * 0.1;
+  ctx.fillStyle = BRAND.white;
+  ctx.beginPath();
+  ctx.moveTo(cx - side / 2 + nudge, cy - side / 2);
+  ctx.lineTo(cx + side / 2 + nudge, cy);
+  ctx.lineTo(cx - side / 2 + nudge, cy + side / 2);
+  ctx.closePath();
+  ctx.fill();
+
+  ctx.fillStyle = BRAND.white;
+  ctx.font = font(800, title.size);
+  ctx.textAlign = "center";
+  ctx.textBaseline = "top";
+  title.lines.forEach((line, index) => ctx.fillText(line, cx, top + CARD.play * 2 + CARD.gap + index * step));
+
+  // The white wordmark, top-left.
+  ctx.drawImage(logo, CARD.side, CARD.side, CARD.logo * WORDMARK_RATIO, CARD.logo);
+
+  // The length, bottom-right, as a video thumbnail has it.
+  ctx.font = font(600, CARD.pill);
+  ctx.textAlign = "left";
+  ctx.textBaseline = "middle";
+  const textW = ctx.measureText(plan.length).width;
+  const pillW = textW + CARD.pillPadX * 2;
+  const pillH = CARD.pill + CARD.pillPadY * 2;
+  const pillX = width - CARD.side - pillW;
+  const pillY = height - CARD.side - pillH;
+  ctx.fillStyle = rgba(BRAND.white, 0.14);
+  ctx.beginPath();
+  ctx.roundRect(pillX, pillY, pillW, pillH, pillH / 2);
+  ctx.fill();
+  ctx.fillStyle = BRAND.white;
+  ctx.fillText(plan.length, pillX + CARD.pillPadX, pillY + pillH / 2 + 1);
+}
+
+async function main() {
+  const plan = await (await fetch("../plan.json")).json();
+  await loadFonts();
+  const logo = await loadImage(`../assets/${LOGO_FILES.onDark}`);
+  const canvas = new OffscreenCanvas(plan.width, plan.height);
+  drawCard(canvas.getContext("2d"), plan, logo);
+  // The best quality that stays under the cap.
+  for (const quality of plan.qualities) {
+    const jpeg = await canvas.convertToBlob({ type: "image/jpeg", quality });
+    if (jpeg.size <= plan.maxBytes) {
+      await post("card", jpeg, "image/jpeg");
+      await post("done", JSON.stringify({ quality, bytes: jpeg.size }));
+      return;
+    }
+  }
+  await fail("too_large", `The preview card is over ${Math.round(plan.maxBytes / 1000)} KB at every quality.`);
+}
+
+main().catch((error) => fail("page_error", error?.message || error));

package/src/video/share.mjs

@@ -2,10 +2,12 @@
 //
 // The CLI holds no Foldspace sign-in (the editor's MCP does), so sharing is
 // three steps the agent takes, only after the human said yes:
-//   1. `npx foldspace share inspect` - sizes and checks the MP4 and poster here
+//   1. `npx foldspace share inspect --title '...'` - sizes and checks the MP4
+//      and poster here, and draws the link's preview card (card.mjs)
 //   2. MCP `create_video_share` - returns one-time signed upload targets
 //      (`upload_command`), then `npx foldspace share upload` sends the files
-//      straight to Foldspace's video storage with them
+//      straight to Foldspace's video storage with them (the card only when
+//      create_video_share was given card_bytes and so returned a card target)
 //   3. MCP `publish_video_share` - the server checks the files and returns
 //      the public link
 // Nothing here talks to Foldspace except the upload targets the MCP issued,
@@ -38,6 +40,14 @@ export function isAllowedUploadUrl(value) {
 /** Mirrors the server's caps (share-service SHARE_MAX_*): checked here so a too-big file fails before any upload. */
 export const MAX_VIDEO_BYTES = 500 * 1024 * 1024;
 export const MAX_POSTER_BYTES = 5 * 1024 * 1024;
+export const MAX_CARD_BYTES = 1024 * 1024;
+/** share-service SHARE_MAX_DURATION_SECONDS: publish refuses a longer video, after the whole upload. */
+export const MAX_VIDEO_SECONDS = 600;
+/** The preview card's size (share-service: the 1200x630 og:image). */
+export const CARD_WIDTH = 1200;
+export const CARD_HEIGHT = 630;
+/** A targets file holds three small JSON objects; anything this big is not one. */
+const MAX_TARGETS_FILE_BYTES = 64 * 1024;
 
 export class ShareError extends Error {
   constructor(code, message) {
@@ -68,6 +78,11 @@ export function posterFor(videoPath) {
   return videoPath.replace(/\.mp4$/i, ".jpg");
 }
 
+/** Where `inspect --title` writes the preview card, and where `upload` looks for it. */
+export function cardFor(videoPath) {
+  return videoPath.replace(/\.mp4$/i, ".card.jpg");
+}
+
 /**
  * Sizes the two files and runs the same structural checks the server's publish
  * check runs (MP4 with ftyp, moov before mdat; JPEG poster), so the agent hears
@@ -84,9 +99,58 @@ export function inspectForShare({ videoPath, posterPath }) {
     throw new ShareError("NOT_JPEG", "The poster must be a JPEG image.");
   }
   const durationS = readMp4Duration(videoPath, video.bytes);
+  if (durationS > MAX_VIDEO_SECONDS) {
+    throw new ShareError("TOO_LONG", `The video is ${formatLength(Math.ceil(durationS))} long; a share link takes at most ${formatLength(MAX_VIDEO_SECONDS)} (10 minutes). Send the file instead, or share a shorter cut.`);
+  }
   return { video: { ...video, durationS }, poster };
 }
 
+/**
+ * A preview card someone made (`--card`), or the one `inspect` drew: a JPEG
+ * of 1200x630, read from its frame header (SOF), at most 1 MiB.
+ */
+export function inspectCard(cardPath) {
+  const card = statFile(cardPath, "NO_CARD", "preview card");
+  if (card.bytes > MAX_CARD_BYTES) throw new ShareError("TOO_LARGE", `The preview card is ${Math.round(card.bytes / 1024)} KB; the limit is ${MAX_CARD_BYTES / 1024} KB.`);
+  const size = jpegSize(readSlice(cardPath, 0, Math.min(card.bytes, 256 * 1024)));
+  if (!size) throw new ShareError("NOT_JPEG", "The preview card must be a JPEG image.");
+  if (size.width !== CARD_WIDTH || size.height !== CARD_HEIGHT) {
+    throw new ShareError("BAD_CARD", `The preview card is ${size.width}x${size.height}; it must be ${CARD_WIDTH}x${CARD_HEIGHT}.`);
+  }
+  return card;
+}
+
+/**
+ * A JPEG's width and height, from the first SOF marker; null when the bytes
+ * are not a JPEG or end before one. Walks the segments from SOI: every one
+ * but the standalone markers carries its length.
+ */
+export function jpegSize(bytes) {
+  if (!(bytes.length >= 4 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)) return null;
+  let offset = 2;
+  while (offset + 4 <= bytes.length) {
+    if (bytes[offset] !== 0xff) return null;
+    const marker = bytes[offset + 1];
+    if (marker === 0xff) {
+      offset += 1; // fill byte
+      continue;
+    }
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) {
+      offset += 2; // TEM, RSTn, SOI: no length
+      continue;
+    }
+    if (marker === 0xd9 || marker === 0xda) return null; // EOI or SOS before any frame header
+    const length = bytes.readUInt16BE(offset + 2);
+    // SOF0-SOF15, except DHT (C4), JPG (C8) and DAC (CC), which share the range.
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      if (offset + 9 > bytes.length) return null;
+      return { height: bytes.readUInt16BE(offset + 5), width: bytes.readUInt16BE(offset + 7) };
+    }
+    offset += 2 + length;
+  }
+  return null;
+}
+
 /** Walks top-level boxes: ftyp first, moov before mdat; returns mvhd duration in seconds. */
 function readMp4Duration(file, size) {
   const first = boxAt(file, 0, size);
@@ -139,20 +203,56 @@ function boxAt(file, offset, fileSize) {
 }
 
 /**
- * Parses the `--targets` JSON that `create_video_share` put in the upload
- * command: { video: {url, method, headers}, poster: {...} }.
+ * The targets JSON, from exactly one of `--targets '<json>'` and
+ * `--targets-file <path>` (for shells that break a quoted JSON argument:
+ * Windows PowerShell and cmd). The file is read, never printed and never
+ * deleted: it holds one-time upload targets, the human's to delete.
  */
-export function parseTargets(text) {
+export function readTargets({ targets, targetsFile }, projectDir) {
+  if (targets !== undefined && targetsFile !== undefined) {
+    throw new ShareError("BAD_TARGETS", "Give --targets or --targets-file, not both.");
+  }
+  if (targetsFile === undefined) {
+    if (typeof targets !== "string" || !targets) {
+      throw new ShareError("BAD_TARGETS", "--targets (or --targets-file) is required: run the upload command create_video_share returned.");
+    }
+    return { text: targets, source: "--targets" };
+  }
+  if (typeof targetsFile !== "string" || !targetsFile) throw new ShareError("BAD_TARGETS", "--targets-file needs the path of the file that holds the targets JSON.");
+  const file = path.resolve(projectDir, targetsFile);
+  let bytes;
+  try {
+    if (fs.statSync(file).size > MAX_TARGETS_FILE_BYTES) throw new ShareError("BAD_TARGETS", "The --targets-file is too big to be the targets JSON.");
+    bytes = fs.readFileSync(file);
+  } catch (error) {
+    if (error instanceof ShareError) throw error;
+    throw new ShareError("BAD_TARGETS", `No targets file at ${file}.`);
+  }
+  // PowerShell writes UTF-16 with `>` and a UTF-8 byte-order mark with Out-File in some versions.
+  let text;
+  if (bytes[0] === 0xff && bytes[1] === 0xfe) text = bytes.subarray(2).toString("utf16le");
+  else text = bytes.toString("utf8").replace(/^\uFEFF/, "");
+  return { text, source: "--targets-file" };
+}
+
+/**
+ * Parses the targets JSON that `create_video_share` put in the upload
+ * command: { video: {url, method, headers}, poster: {...}, card?: {...} }.
+ * `card` is there only when create_video_share was given card_bytes.
+ * `source` names the flag it came from, for the errors.
+ */
+export function parseTargets(text, source = "--targets") {
   let parsed;
   try {
     parsed = JSON.parse(String(text || ""));
   } catch {
-    throw new ShareError("BAD_TARGETS", "--targets is not valid JSON. Copy the upload command from create_video_share exactly.");
+    throw new ShareError("BAD_TARGETS", `${source} is not valid JSON. Copy the targets from the upload command create_video_share returned exactly.`);
   }
-  for (const name of ["video", "poster"]) {
+  const names = ["video", "poster", ...(parsed?.card != null ? ["card"] : [])];
+  for (const name of names) {
     const target = parsed?.[name];
     if (!target || typeof target.url !== "string" || target.method !== "POST" || typeof target.headers !== "object") {
-      throw new ShareError("BAD_TARGETS", `--targets has no valid ${name} target. Copy the upload command from create_video_share exactly.`);
+      throw new ShareError("BAD_TARGETS", `${source} has no valid ${name} target. Copy the targets from the upload command create_video_share returned exactly.`);
     }
     if (!isAllowedUploadUrl(target.url)) {
       throw new ShareError("BAD_TARGETS", `The ${name} upload target is not Foldspace's video storage (https://storage.googleapis.com). Use only the command create_video_share returned.`);
@@ -282,3 +382,9 @@ function readSlice(file, offset, length) {
 function mb(bytes) {
   return Math.round(bytes / (1024 * 1024));
 }
+
+/** "0:42", "10:00": a length as the card and the errors show it. */
+export function formatLength(seconds) {
+  const whole = Math.max(0, Math.round(Number(seconds) || 0));
+  return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+}

package/templates/agent-starter/skills/share-a-video/SKILL.md

@@ -214,27 +214,44 @@ anything leaves this computer, ask once, as a choice: *"A share link is public
 to anyone who has it, and the video shows [what is on screen]. Create one?"*
 Only on a yes:
 
-1. `npx foldspace share inspect` (the newest `video/*.mp4` and its poster, or
-   pass the path). It uploads nothing. If it says the MP4 is not fast-start,
-   that file did not come from `record`: say so and stop.
-2. The Foldspace tool `create_video_share` with a title in their words (the
-   product and what the agent does, up to 200 characters), and `video_bytes`
-   and `poster_bytes` from step 1.
-3. Run the upload command it returns, exactly - it carries one-time upload
-   targets for 30 minutes. Pass `upload` the same video path and `--poster`
-   you gave `inspect`, if any, so it uploads the files `inspect` sized. Never
-   paste the targets into chat, a file or a commit. In Codex (or any editor
-   that runs commands in a sandbox), this command needs the network: run it
-   outside the sandbox through the editor's own approval, with one plain line
-   on why.
-4. When it prints `"status": "uploaded"`, the tool `publish_video_share` with
+1. Ask for the title - in their words, the product and what the agent does,
+   up to 200 characters - and, optionally, a line or two of description (up
+   to 500 characters). The title goes on the link's preview card, so agree it
+   first.
+2. `npx foldspace share inspect --title '<the title>'` (the newest
+   `video/*.mp4` and its poster, or pass the path). Keep the title in single
+   quotes so the shell expands nothing in it, escaping any single quote it
+   contains the way your shell needs. It uploads nothing. It
+   checks the files and draws the link's preview card next to the MP4 - what
+   WhatsApp, Slack or LinkedIn show for the link. If it says the MP4 is not
+   fast-start, that file did not come from `record`: say so and stop. If it
+   is over 10 minutes, a share link cannot take it: offer the file instead.
+   `card: null` with a `cardReason` (no Google Chrome, say) is not a
+   failure: the link shows the poster instead - carry on without a card.
+3. The Foldspace tool `create_video_share` with the same `title`, the
+   `description` if they gave one, `video_bytes` and `poster_bytes`, and
+   `card_bytes` from `card.bytes` when step 2 made a card (none when `card`
+   is null).
+4. Run the upload command it returns, exactly - it carries one-time upload
+   targets for 30 minutes. Pass `upload` the same video path, `--poster` and
+   `--card` you gave `inspect`, if any, so it uploads the files `inspect`
+   sized. Never paste the targets into chat or a commit. On Windows
+   (PowerShell or cmd), where a quoted JSON argument breaks: write the
+   targets JSON from that command, exactly, to a file outside the project
+   (for example in the temp folder), and run
+   `npx foldspace share upload --targets-file <that file>` with the same
+   video path and flags; once it is uploaded, delete the file or tell them
+   they may. In Codex (or any editor that runs commands in a sandbox), this
+   command needs the network: run it outside the sandbox through the
+   editor's own approval, with one plain line on why.
+5. When it prints `"status": "uploaded"`, the tool `publish_video_share` with
    the `share_id`. It returns the link: give it to them as it is.
-5. Tell them in one line that they get an email at the first view and a daily
-   summary on days it is watched, and that you can show the numbers
+6. Tell them in one line that they get an email at the first view, then at
+   most one an hour while it gets new views, and that you can show the numbers
    (`get_video_share_stats`) or delete the link (`delete_video_share`) whenever
    they ask. `publish_video_share` says whether those emails are on for this
    share.
-6. They want the emails off, or back on: the tool
+7. They want the emails off, or back on: the tool
    `set_video_share_notifications` with the `share_id` and
    `email_notifications` (`false` stops them, `true` turns them on). It covers
    that one video only.
@@ -243,11 +260,11 @@ The tools refuse with a reason you pass on as it is: an EU account (share
 links are not offered there yet - send the file instead), a cap (shares per
 day, or a trial's monthly limit), or a sign-in by API key rather than as a
 person. The CLI never signs in to Foldspace and never reaches the Foldspace
-tools itself: steps 2 and 4 are tool calls you make.
+tools itself: steps 3 and 5 are tool calls you make.
 
 The video holds real data, so it is never saved with the code: `record` writes
-`video/.gitignore` (`*.mp4`, `*.jpg`) in every project. `video/scenes.json`
-stays in git.
+`video/.gitignore` (`*.mp4`, `*.jpg` - the preview card too) in every project.
+`video/scenes.json` stays in git.
 
 ## Change a caption without recording again