@hypersocial/decks-cli 0.9.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",

package/skills/hyperdecks/SKILL.md

@@ -460,7 +460,8 @@ suit it.
 |---|---|---|
 | `hero` | the opening, a section opener; the presenter is the visual, no `.art` unless it shows the real subject (check fails while the placeholder `<div class="art">` is in: swap it for an `<img class="art">` or delete it) | stage, bottom-right; `[wave]`, `[look: h1]` |
 | `number` | one number with its source: proof, traction, a delta | stage; `[look: #<id>-figure]` as it is said |
-| `product` | a screenshot in a browser frame (`.frame.phone` for a phone shot) with the point beside it | stage; `[look: #<id>-frame]`, `[reveal: #<id>-callout]` |
+| `product` | a screenshot in a browser frame (`.frame.card` for a phone) with the point beside it | stage; `[look: #<id>-frame]`, `[reveal: #<id>-callout]` |
+| `phones` | a phone app's flow: a fanned row of phone cards | stage, bottom-left; `[go: #<id>-p1]` … `p3`, `[go: slot]` |
 | `quote` | a customer or user in their own words, quoted exactly | stage, bottom-left; `[look: #<id>-quote]` |
 | `compare` | before/after, them/us, three parallel lines each | stage; `[look: #<id>-before]`, `[go: #<id>-after]` |
 | `timeline` | four milestones: history, a roadmap, a process | stage; `[go: #<id>-m1]` … `m4`, `[go: slot]` |
@@ -469,11 +470,15 @@ suit it.
 | `team` | up to four people, faces only with permission | stage; `[go: #<id>-p1]` … `p4`, `[go: slot]` |
 | `closer` | the end: one line and one action (a command, a link) | stage, bottom-left; `[go: #<id>-cta]`, `[go: slot]`, `[wave]` |
 
+**Phones and backgrounds.** One phone: `product`'s `.frame.card`; a flow of
+two to four: `phones` (`--tilt`, `--shadow` on a card). A few slides at most:
+`bg-dots` (never under text), a `.deco` of inked tiles.
+
 Presenter style follows the deck (step 2, *Which presenter style*): `stage`
 when the presenter carries the story, which is what the layouts are drawn for
 (they keep the slot's corner clear); `corner` on a slide where a big
 visual is the point and moves are not needed; `glass` on a dark or busy
-picture. Two layouts (`quote`, `closer`) sit left; put a `slot-left` on others
+picture. Three layouts (`quote`, `phones`, `closer`) sit left; put a `slot-left` on others
 where there is room so slide changes move the presenter.
 
 **Visuals: real first, generated second.**
@@ -793,6 +798,16 @@ folder) and `hyperdecks source push <slug> [dir]` (a folder's files back to the
 draft), `hyperdecks asset add <slug> <file|url>` for an image, `hyperdecks guide
 [topic]` for these sections, and `--hosted` on `deck new`, `check` and `release`.
 
+## After you ship: say what cost you
+
+When a deck is released, end your report with a short list of what cost you
+time, ranked by cost: a rule you had to work around, a layout or style you
+hand-wrote because the library had none, a check or tool that said the wrong
+thing, something you couldn't find in this guide. One line each, concrete
+(the file, the command, the message), no praise needed. Send it to whoever
+asked for the deck. Hyperdecks turns these into roadmap cards; the Xbox
+rebuild's list on 2026-11-05 produced four.
+
 ## Safety
 
 - For read-only inspection, run commands directly and summarize the important

package/skills/hyperdecks/chat.md

@@ -107,6 +107,10 @@ makes the hello deck; continue from step 5 below.
 - A deck with no narration (a product tour, a silent walkthrough): put
   `data-silent` on the player script and skip narrate_deck; check warns, release
   goes through, and the player shows no Play button or clock.
+- When the deck is released, tell the person what cost you time, ranked by
+  cost: a rule you worked around, a layout you hand-wrote, a tool or check that
+  said the wrong thing, something missing from `deck_guide`. One concrete line
+  each. Hyperdecks turns these into roadmap cards.
 - The deck's own scripts run: slide controllers, `[custom: name]` cues,
   pausing the narrator, tappable and interactive slides. `deck_guide
   { topic: "scripts" }` has the hooks and an example.

package/src/checkRules.mjs

@@ -511,6 +511,8 @@ export function phraseList(value) {
 // own markers: the empty div (or the chart's labelled svg). A div that holds
 // its own picture, or gets one from a url() in its style or a <style> rule
 // naming its class, is the deck's art. A deck that wants none removes it.
+// Each opening tag is read on its own (the inner text is a lookahead), so a
+// stand-in nested in another of its tag, like a phone card's shot, is seen.
 const PLACEHOLDERS = [
   {
     layout: "l-hero", tag: "div", cls: "art", what: "the hero's art", img: '<img class="art" src="…" alt="">, or delete the div for no art (the presenter is the visual)',
@@ -520,6 +522,10 @@ const PLACEHOLDERS = [
     layout: "l-product", tag: "div", cls: "shot", what: "the product screenshot", img: '<img class="shot" src="…" alt="…">',
     how: { hosted: "capture the real page with capture_url", cli: "capture the real page with `hyperdecks screenshot <url>`" },
   },
+  {
+    layout: "l-phones", tag: "div", cls: "shot", what: "each phone screen", img: '<img class="shot" src="…" alt="…"> (or <video class="shot" src="…" autoplay muted loop playsinline>) in each card',
+    how: { hosted: "capture the app at phone size with capture_url (width 390, height 844), or upload a screen recording with upload_deck_asset", cli: "capture the app at phone size with `hyperdecks screenshot <url> --width 390 --height 844`, or add a screen recording with `hyperdecks asset add`" },
+  },
   {
     layout: "l-chart", tag: "svg", cls: "chart", label: /placeholder/i, what: "the chart (made-up numbers)", img: '<img class="chart" src="…" alt="…">',
     how: { hosted: "draw the real data with render_chart", cli: "draw the real data with `hyperdecks chart <spec.json>`" },
@@ -531,7 +537,7 @@ export function placeholderErrors(html, { hosted = false } = {}) {
   const styled = (cls) => [...css.matchAll(/([^{}]*)\{([^{}]*)\}/g)].some(([, sel, body]) => new RegExp(`\\.${cls}(?![\\w-])`).test(sel) && /url\(/i.test(body));
   return slides(html).flatMap((s, i) => {
     const layouts = classes(s.tag);
-    return PLACEHOLDERS.filter((p) => layouts.includes(p.layout) && !(p.tag === "div" && styled(p.cls)) && [...s.body.matchAll(new RegExp(`(<${p.tag}\\b[^>]*>)([\\s\\S]*?)</${p.tag}>`, "gi"))].some(([, tag, inner]) =>
+    return PLACEHOLDERS.filter((p) => layouts.includes(p.layout) && !(p.tag === "div" && styled(p.cls)) && [...s.body.matchAll(new RegExp(`(<${p.tag}\\b[^>]*>)(?=([\\s\\S]*?)</${p.tag}>)`, "gi"))].some(([, tag, inner]) =>
       classes(tag).includes(p.cls) && (p.label ? p.label.test(attr(tag, "aria-label") ?? "") : !inner.trim() && !/url\(/i.test(attr(tag, "style") ?? ""))))
       .map((p) => MESSAGES.placeholder(s.id || `${i + 1}`, p.what, `<${p.tag} class="${p.cls}">`, hosted ? p.how.hosted : p.how.cli, p.img));
   });

package/src/commands.mjs

@@ -340,7 +340,7 @@ commands:
   deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style stage|bubble|glass|corner] [--no-brand] [--dir <path>]
                    scaffold decks/<slug>/: index.html (8 slides, or one per layout, player/v1), script.md, evidence.md,
                    in your saved brand's colours, fonts and logo (--no-brand: the template's look)
-                   layouts: hero, number, product, quote, compare, timeline, features, chart, team, closer
+                   layouts: hero, number, product, phones, quote, compare, timeline, features, chart, team, closer
   check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--layout] [--strict] [--fix] [--json]
                    the narrated-deck gate: slides vs manifest, timing, captions, clip URLs,
                    local refs, pinned player, mobile titles. data-silent on the player script: no narration

package/src/files.mjs

@@ -16,6 +16,7 @@ const FILES = {
   "templates/layouts/hero.html": () => new URL("../templates/layouts/hero.html", import.meta.url),
   "templates/layouts/number.html": () => new URL("../templates/layouts/number.html", import.meta.url),
   "templates/layouts/product.html": () => new URL("../templates/layouts/product.html", import.meta.url),
+  "templates/layouts/phones.html": () => new URL("../templates/layouts/phones.html", import.meta.url),
   "templates/layouts/quote.html": () => new URL("../templates/layouts/quote.html", import.meta.url),
   "templates/layouts/team.html": () => new URL("../templates/layouts/team.html", import.meta.url),
   "templates/layouts/timeline.html": () => new URL("../templates/layouts/timeline.html", import.meta.url),

package/src/layouts.mjs

@@ -5,8 +5,8 @@ import { packageText } from "./files.mjs";
 
 export const NARRATED_FILES = { "index.html": "narrated-deck.html", "script.md": "script.md", "evidence.md": "evidence.md" };
 // The library, in a sensible deck order; `--layouts` takes any order and repeats.
-export const LAYOUTS = ["hero", "number", "product", "quote", "compare", "timeline", "features", "chart", "team", "closer"];
-const LAYOUT_ALIASES = { "big-number": "number", "product-shot": "product", comparison: "compare", "three-up": "features" };
+export const LAYOUTS = ["hero", "number", "product", "phones", "quote", "compare", "timeline", "features", "chart", "team", "closer"];
+const LAYOUT_ALIASES = { "big-number": "number", "product-shot": "product", "phone-row": "phones", comparison: "compare", "three-up": "features" };
 
 const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 

package/src/runtime.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.9.0";
+export const VERSION = "0.9.1";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {

package/templates/layouts/_deck.html

@@ -51,7 +51,7 @@
      and the presenter, and plays the narration. Change the palette and fonts
      here; every layout reads them. */
   :root {
-    --ink: #0b0b0f; --paper: #fafaf7; --accent: #ffda1b; --accent-2: #27ceff; --card: #ffffff;
+    --ink: #0b0b0f; --paper: #fafaf7; --accent: #ffda1b; --accent-2: #27ceff; --accent-3: #ff9ec7; --card: #ffffff;
     --font: "Space Grotesk", system-ui, sans-serif; --mono: "Space Mono", ui-monospace, monospace;
     /* The type scale: one display size per slide at most, then title, sub (a title beside a visual), lead, body, label. */
     --t-display: 128px; --t-title: 84px; --t-sub: 56px; --t-lead: 30px; --t-body: 24px; --t-label: 17px;
@@ -73,12 +73,41 @@
   .slot-top .narration-slot { top: 96px; bottom: auto; }
   .reveal { opacity: 0; transform: translateY(12px); transition: opacity .5s, transform .5s; }
   .reveal.is-revealed { opacity: 1; transform: none; }
+  /* The phone card (product's .frame.card, the phones row): a frameless phone,
+     white with an ink edge, a hard offset shadow and a tilt. Change --tilt and
+     --shadow on the element (style="--tilt: 3deg; --shadow: var(--accent-2)");
+     put an <img class="shot"> or <video class="shot" autoplay muted loop
+     playsinline> in place of the placeholder div. */
+  .slide .frame.card { --tilt: -4deg; --shadow: var(--accent); position: relative; width: 320px; aspect-ratio: 9 / 19.5; padding: 9px; border: 3px solid var(--ink); border-radius: 46px; background: var(--card); box-shadow: 18px 18px 0 var(--shadow); transform: rotate(var(--tilt)); overflow: visible; }
+  .slide .frame.card > .shot { display: block; width: 100%; height: 100%; aspect-ratio: auto; border-radius: 36px; border: 2px solid color-mix(in srgb, var(--ink) 20%, transparent); object-fit: cover; }
+  .slide .frame.card > div.shot { background:
+      linear-gradient(color-mix(in srgb, var(--ink) 16%, transparent) 0 0) 50% 5% / 36% 2.2% no-repeat,
+      linear-gradient(var(--accent-2) 0 0) 50% 30% / 84% 40% no-repeat,
+      linear-gradient(color-mix(in srgb, var(--ink) 14%, transparent) 0 0) 16% 62% / 60% 2.4% no-repeat,
+      linear-gradient(color-mix(in srgb, var(--ink) 14%, transparent) 0 0) 14% 67% / 44% 2.4% no-repeat,
+      linear-gradient(var(--accent) 0 0) 50% 90% / 84% 6% no-repeat,
+      var(--paper); }
+  /* Backgrounds, optional and for a few slides a deck. bg-dots on the section:
+     a dot grid in the slide's text colour, faded in from the side away from the text
+     (--dots-fade is the fade's direction: 90deg puts the dots on the right,
+     270deg on the left). A <div class="deco" aria-hidden="true"> in the slide
+     holds small inked tiles, each a <span> placed by its inline left/top (and
+     background, rotate). Both sit behind the slide's content. */
+  .slide.bg-dots, .slide:has(> .deco) { isolation: isolate; }
+  .slide.bg-dots::before { content: ""; position: absolute; inset: 0; z-index: -1; pointer-events: none; background: radial-gradient(color-mix(in srgb, currentColor 24%, transparent) 3px, transparent 3.6px) 0 0 / 36px 36px; -webkit-mask-image: linear-gradient(var(--dots-fade, 90deg), transparent 40%, #000 80%); mask-image: linear-gradient(var(--dots-fade, 90deg), transparent 40%, #000 80%); }
+  .slide > .deco { position: absolute; inset: 0; z-index: -1; pointer-events: none; }
+  .slide > .deco > span { position: absolute; display: grid; place-items: center; width: 80px; height: 80px; border: 3px solid var(--ink); border-radius: 20px; background: var(--card); box-shadow: 8px 8px 0 var(--ink); color: var(--ink); font: 700 34px var(--font); }
   /* Phones: the slide is the 374×736 card; the presenter is a small head in
      the corner, so keep the bottom 170px clear. */
   @media (max-width: 650px) {
     :root { --t-display: 54px; --t-title: 38px; --t-sub: 28px; --t-lead: 17px; --t-body: 15px; --t-label: 12px; }
     .slide { padding: 28px 20px 170px; gap: 14px; }
     .narration-slot { right: 12px; left: 12px; bottom: 64px; }
+    .slide .frame.card { width: 160px; padding: 5px; border-width: 2px; border-radius: 24px; box-shadow: 8px 8px 0 var(--shadow); }
+    .slide .frame.card > .shot { border-radius: 19px; border-width: 1px; }
+    /* The text fills the card's width: the dots fade in towards the bottom, and the tiles stay off. */
+    .slide.bg-dots::before { background-size: 22px 22px; background-image: radial-gradient(color-mix(in srgb, currentColor 24%, transparent) 2px, transparent 2.5px); -webkit-mask-image: linear-gradient(180deg, transparent 45%, #000 85%); mask-image: linear-gradient(180deg, transparent 45%, #000 85%); }
+    .slide > .deco { display: none; }
   }
 </style>
 <!-- LAYOUT STYLES -->

package/templates/layouts/phones.html

@@ -0,0 +1,54 @@
+<!--
+layout: phones
+summary: A fanned row of two to four phone cards (the inner ones larger and in front, the outer ones tilted out), the point in the column beside it.
+use: a phone app's flow or its key screens. Each card's .shot is a placeholder check fails on: put in a phone-size screenshot (`hyperdecks screenshot <url> --width 390 --height 844`, capture_url) as <img class="shot">, or a screen recording as <video class="shot" autoplay muted loop playsinline>. Two to four cards: the row spaces and tilts them (on phones only the first three show); change one card's --tilt or --shadow on it. One phone only: use product with .frame.card.
+slot: bottom-left
+presenter: stage
+cues: [look: #__ID__-row] when the narration turns to the app; [go: #__ID__-p1] … [go: #__ID__-p3] to walk the screens, then [go: slot].
+script: Here is the app on a phone. [look: #__ID__-row] You start here, [go: #__ID__-p1] you pick one, [go: #__ID__-p2] and it is done. [go: #__ID__-p3] [go: slot]
+-->
+<style>
+  .l-phones { display: grid; grid-template-columns: 500px 1fr; grid-template-areas: "text row"; column-gap: 40px; align-items: center; }
+  .l-phones .text { grid-area: text; align-self: start; display: flex; flex-direction: column; gap: 20px; }
+  .l-phones .tt { font-size: var(--t-sub); line-height: 1.02; }
+  .l-phones .lead { font-size: var(--t-body); }
+  /* The row: cards overlap a little; the first and last tilt out and sit lower,
+     the ones between are larger and in front. The card's look is shared (_deck.html). */
+  .l-phones .row { grid-area: row; display: flex; justify-content: center; align-items: center; padding: 0 0 40px; }
+  .l-phones .row > .frame.card { --tilt: 0deg; flex: none; width: 260px; margin: 0 -14px; }
+  .l-phones .row > .frame.card:first-child { --tilt: -7deg; --shadow: var(--accent-2); translate: 0 36px; }
+  .l-phones .row > .frame.card:last-child { --tilt: 7deg; --shadow: var(--accent-3); translate: 0 36px; }
+  .l-phones .row > .frame.card:not(:first-child, :last-child) { width: 300px; z-index: 1; }
+  .l-phones .row:has(> :nth-child(4)) > .frame.card { width: 220px; }
+  .l-phones .row:has(> :nth-child(4)) > .frame.card:not(:first-child, :last-child) { width: 250px; }
+  @media (max-width: 650px) {
+    .l-phones { display: flex; flex-direction: column; align-items: stretch; }
+    .l-phones .text { gap: 10px; }
+    .l-phones .row { padding: 6px 0 18px; }
+    .l-phones .row > .frame.card, .l-phones .row:has(> :nth-child(4)) > .frame.card { width: 108px; margin: 0 -6px; }
+    .l-phones .row > .frame.card:not(:first-child, :last-child), .l-phones .row:has(> :nth-child(4)) > .frame.card:not(:first-child, :last-child) { width: 128px; }
+    .l-phones .row > .frame.card:is(:first-child, :last-child) { translate: 0 16px; }
+    /* Four do not fit the phone card: the row keeps the first three, the third as its end. */
+    .l-phones .row > .frame.card:nth-child(n + 4) { display: none; }
+    .l-phones .row:has(> :nth-child(4)) > .frame.card:nth-child(3) { --tilt: 7deg; --shadow: var(--accent-3); width: 108px; translate: 0 16px; }
+  }
+</style>
+<section class="slide l-phones slot-left bg-dots" id="__ID__" data-chapter="On a phone" data-note="Phone screens: name the app build and the date they were captured.">
+  <div class="text">
+    <div class="kicker">On a phone</div>
+    <h2 class="tt" data-title-mobile="Three taps.">Three taps, start to finish.</h2>
+    <p class="lead">One line on what the screens show, in order.</p>
+  </div>
+  <div class="row" id="__ID__-row">
+    <div class="frame card" id="__ID__-p1"><div class="shot" role="img" aria-label="Phone screen placeholder: the first step"></div></div>
+    <div class="frame card" id="__ID__-p2"><div class="shot" role="img" aria-label="Phone screen placeholder: the main screen"></div></div>
+    <div class="frame card" id="__ID__-p3"><div class="shot" role="img" aria-label="Phone screen placeholder: the result"></div></div>
+  </div>
+  <!-- Optional decorations, behind the content (a few slides a deck at most):
+  <div class="deco" aria-hidden="true">
+    <span style="left: 52%; top: 8%; background: var(--accent); rotate: -10deg;">★</span>
+    <span style="left: 92%; top: 42%; background: var(--accent-2); rotate: 12deg;">♪</span>
+    <span style="left: 48%; top: 78%; background: var(--accent-3); rotate: 8deg;">☺</span>
+  </div> -->
+  <div class="narration-slot"></div>
+</section>

package/templates/layouts/product.html

@@ -1,7 +1,7 @@
 <!--
 layout: product
-summary: A product screenshot in a browser frame (or .frame.phone for a phone shot), the point in the column beside it.
-use: a demo moment. Its .shot is a placeholder check fails on: put in `hyperdecks screenshot <url>` (capture_url) output as <img class="shot">; a callout chip names what to look at.
+summary: A product screenshot in a browser frame (for a phone shot, .frame.card: the frameless phone card), the point in the column beside it.
+use: a demo moment. Its .shot is a placeholder check fails on: put in `hyperdecks screenshot <url>` (capture_url) output as <img class="shot">; a callout chip names what to look at. For a phone app, make the frame `<div class="frame card" id="__ID__-frame">` holding only the shot (a phone screenshot or a `<video class="shot" autoplay muted loop playsinline>` clip) and the callout; tilt and shadow colour are `--tilt` and `--shadow` on it. `.frame.phone` (the black bezel) stays for older decks.
 slot: bottom-right
 presenter: stage
 cues: [look: #__ID__-frame] when the narration turns to the product; [reveal: #__ID__-callout] for the detail.
@@ -27,6 +27,9 @@ script: This is the product. [look: #__ID__-frame] Look at this part. [reveal: #
       linear-gradient(var(--accent-2) 0 0) 248px 176px / 300px 300px no-repeat,
       linear-gradient(color-mix(in srgb, var(--ink) 8%, transparent) 0 0) 580px 176px / 308px 300px no-repeat,
       linear-gradient(color-mix(in srgb, var(--ink) 6%, transparent) 0 0) 0 0 / 210px 100% no-repeat; }
+  /* The phone card's look is shared (_deck.html); here it sits centred in the frame column, without the browser bar. */
+  .l-product .frame.card { justify-self: center; }
+  .l-product .frame.card .bar { display: none; }
   .l-product .frame.phone { width: 300px; justify-self: center; border-radius: 40px; padding: 12px; background: var(--ink); }
   .l-product .frame.phone .bar { display: none; }
   .l-product .frame.phone .shot { aspect-ratio: 9 / 19.5; border-radius: 28px; }
@@ -39,6 +42,7 @@ script: This is the product. [look: #__ID__-frame] Look at this part. [reveal: #
     .l-product .bar i { width: 7px; height: 7px; }
     .l-product .bar span { font-size: 9px; padding: 2px 8px; margin-left: 6px; }
     .l-product div.shot { background-size: 30% 6%, 60% 2%, 50% 2%, 28% 40%, 28% 40%, 20% 100%; background-position: 26% 8%, 40% 18%, 36% 23%, 26% 70%, 62% 70%, 0 0; }
+    .l-product .frame.card { align-self: center; }
     .l-product .callout { left: 10px; bottom: 10px; padding: 6px 12px; font-size: 12px; }
   }
 </style>