@creator-notes/cnotes 0.33.1 → 0.35.1

package/skills/cnotes/references/humanizer.md

@@ -197,7 +197,10 @@ humanization corrupts a note:
   Do not flatten a checklist into a paragraph.
 - **Relationship mentions** — titles and links intact. `[NOTE-12: Title](relationship:type)`
   must keep both the display ID and a readable title; never strip a mention to
-  bare text or drop its link.
+  bare text or drop its link. And the TYPE must carry the verb: if the prose
+  narrates "blocks" / "depends on" around a `references` chip or untyped
+  `[[NOTE-12]]`, retype the chip (`relationship:blocks`, `[[blocks::NOTE-12]]`)
+  instead of leaving the verb in prose the graph can't see.
 - **Tables and layout** — tables, columns, and canvas placement survive.
 - **Voice as evidence** — a customer quote or raw memo keeps its original wording.
 
@@ -246,6 +249,9 @@ These are objective and never need judgment. Enforce them on every write:
 - **Every note starts with a `# h1`** heading — it becomes the title.
 - **Relationship mentions include a readable title**: `[NOTE-123: Title](relationship:type)`,
   never bare `NOTE-123`.
+- **Relationship type matches the narrated verb** — prose "Blocks X" around a
+  `references`/untyped chip is a graph bug, not a style choice: retype to
+  `relationship:blocks` (or `[[blocks::NOTE-123]]`) and drop the redundant verb.
 - **No mention syntax inside canvas richtext or list descriptions** — it corrupts
   the card. Reference notes there as plain display IDs ("see RISK-64").
 - **Richtext stays card-sized** — at most ~3 sentences, one heading; distinct

package/skills/howto-filmstrips/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: howto-filmstrips
+description: >-
+  Capture a real product UI how-to as a horizontal filmstrip on a CreatorNotes
+  canvas: live CSS highlight on the click target, soft radial spotlight, then
+  screenshot → upload → place. Use when the user wants a screenshot storyboard,
+  click-path how-to, JTBD walkthrough, multi-path UI guide, or "show me how to
+  do X in the app" with accurate click markers (not fat-marker sketches).
+---
+
+# How-to filmstrips (live UI capture on a canvas)
+
+Turn a real product flow into a left-to-right filmstrip of screenshots on a CreatorNotes canvas. Each frame shows the full UI with a clear click (or type) target: **crimson highlight on the real element box** + **soft radial spotlight** dimming the rest.
+
+This is the **pixel-accurate sibling** of `fat-marker-flows`. Use fat-marker for proposed / Shape Up sketches; use this skill for “how do I do this in the live product?”
+
+---
+
+## Design lock (do not invent a new look)
+
+| Element | Spec |
+|---------|------|
+| Highlight colour | Classy crimson `#C43036` (outline, soft wash, CLICK/TYPE pill) |
+| Spotlight | Soft **radial** fade, max opacity **~40%** (up to **~55%** on dark forms), long fade (`fade_mult ≈ 5.5`) |
+| Done frame | Green `#2F9E6A` outline + `DONE` pill; lighter spotlight (~30%) |
+| Captions | Canvas **richtext** under the image (same node), not Notes |
+| Titles | Middle dot `·` as separator; **no em dashes** |
+| Layout | One path = one horizontal row; multiple paths = stacked sections |
+| Language | Match the product UI; prefer UK English in captions unless the product is US-only |
+
+**Do not** use orange bullseyes, yellow highlighters, cyan brackets, or hard rectangular `box-shadow: 0 0 0 9999px` spotlights. The hard box-shadow gets clipped by parent `overflow` and often never appears in the PNG.
+
+---
+
+## When to use / not use
+
+**Use when:** documenting a live click path, comparing entry points (Path A/B/C), workshop how-tos, JTBD storyboards from a real app.
+
+**Do not use when:** the UI does not exist yet (use `fat-marker-flows`), or the user wants a polished Figma mock (use a design tool).
+
+---
+
+## Prerequisites
+
+1. Browser automation available (Cursor browser MCP / CDP `Runtime.evaluate` + screenshot).
+2. `cnotes` authenticated with a writable workspace (`cnotes auth status`, `cnotes workspace current`).
+3. This skill folder installed (`cnotes skills install howto-filmstrips`) so scripts resolve under the agent skills dir.
+
+---
+
+## Step 0 — Scope the paths
+
+1. Name the job (e.g. “Create a new contact”).
+2. List each **entry path** separately (Path A, Path B…). One path = one row.
+3. For each path, list 4–7 frames: each frame is **one action** (click or type) or a final Done state.
+4. Write captions before capture: `N · Click …` / `N · Type …` / `N · Done · …`.
+
+---
+
+## Step 1 — Inject highlight helpers (before any click)
+
+Read `scripts/inject-highlight.js` and evaluate its **entire file contents** in the page via CDP `Runtime.evaluate` (or equivalent). That installs:
+
+- `window.__cnHowto.highlight(el, { label: 'CLICK'|'TYPE'|'DONE' })`
+- `window.__cnHowto.clear()`
+- `window.__cnHowto.findExact(text, opts)` — visible, sized matches; prefer menu-row / control size
+
+The injector uses a **fixed full-viewport radial overlay** (not element `box-shadow`), so the spotlight survives screenshot and parent clipping.
+
+**Calibrate visually:** after first inject, highlight one control and screenshot. Check that the crimson outline hugs the element box (not an inner span), the CLICK pill sits just above it and is legible, and the spotlight is a soft radial fade centred on the control — never a hard-edged rectangle. Adjust opacity only if the product chrome is unusually light or dark.
+
+---
+
+## Step 2 — Capture loop (per frame)
+
+For each click/type frame:
+
+1. **Find** the target with `__cnHowto.findExact` (exact label text) or a tight selector. Prefer the **largest visible** control that matches (menu row over inner text span).
+2. **Highlight** with the right label (`CLICK` / `TYPE`).
+3. **Screenshot** the viewport → save as `A1.png`, `A2.png`, …
+4. **Clear** highlight.
+5. **Perform** the action (click / type), wait for UI settle.
+6. Repeat.
+
+For the **Done** frame: land on the success state, highlight the result (e.g. contact name) with `{ label: 'DONE' }`, screenshot, clear.
+
+### Accuracy rules
+
+- Capture highlights **live** from element `getBoundingClientRect`. Do not guess pixel rings on old PNGs.
+- If a frame teaches picking an option that is already selected, switch to another option first, then highlight the target and shoot — so the frame shows the switch, not a no-op.
+- Retina / DPR: screenshots are often 2× CSS pixels. The injector uses CSS pixels for the overlay; if you fall back to `soft-spotlight.py`, pass `--dpr` (usually `2`).
+
+### Fallback if the in-page spotlight is weak
+
+On very dark UIs the radial overlay can look faint. After capture, run:
+
+```bash
+python3 "<skillDir>/scripts/soft-spotlight.py" \
+  --in A3.png --out A3.png \
+  --cx 276 --cy 219 --dpr 2 \
+  --opacity 0.55
+```
+
+`--cx/--cy` are **CSS-pixel** centres from `getBoundingClientRect` (the script multiplies by `--dpr`).
+
+---
+
+## Step 3 — Upload and place on the canvas
+
+```bash
+WS=<workspaceId>
+CANVAS=<canvasId>
+OUT=/tmp/howto-filmstrip
+mkdir -p "$OUT"
+
+cnotes operations begin -w "$WS" --prompt "How-to filmstrip: <job>" --json >/dev/null
+
+# Upload in frame order; collect storageIds
+> "$OUT/ids.txt"
+for f in A1 A2 A3 A4 A5 A6; do
+  sid=$(cnotes files upload "$OUT/$f.png" -w "$WS" --json \
+    | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('storageId') or d.get('id') or '')")
+  echo "$sid" >> "$OUT/ids.txt"
+done
+```
+
+Build a place spec: header + one **section per path**, each with a **grid** of richtext cells (image markdown + caption). Prefer `columns: N` matching frame count (e.g. 6). Use `size: "medium"` for frames.
+
+Image URL form inside richtext:
+
+```markdown
+![Short alt](/api/images/convex/<storageId>)
+
+1 · Click Create new +
+```
+
+Clear existing storyboard nodes if rebuilding the same canvas:
+
+```bash
+cnotes canvas get "$CANVAS" -w "$WS" --json | python3 -c "
+import sys,json
+d=json.load(sys.stdin)
+ids=[n['id'] for n in (d.get('allNodes') or [])]
+for s in d.get('sectionNodes') or []:
+  if s['id'] not in ids: ids.append(s['id'])
+open('/tmp/howto-remove.json','w').write(json.dumps(ids))
+"
+cnotes canvas agent-run wrap --canvas "$CANVAS" --prompt "Clear before how-to rebuild" -- \
+  cnotes canvas bulk-remove "$CANVAS" --nodes "$(cat /tmp/howto-remove.json)" -w "$WS" --json
+```
+
+Place:
+
+```bash
+cnotes canvas agent-run wrap --canvas "$CANVAS" --prompt "Place how-to filmstrip" -- \
+  cnotes canvas place "$CANVAS" --spec "$OUT/unified.json" -w "$WS" --json
+cnotes operations end -w "$WS" --json
+```
+
+### Multi-path layout sketch
+
+```json
+{
+  "root": {
+    "kind": "stack",
+    "axis": "vertical",
+    "gap": "spacious",
+    "align": "start",
+    "items": [
+      { "kind": "item", "type": "richtext", "size": "large",
+        "content": "# How to …\n\nSame job, several entry points. Read each row left to right." },
+      {
+        "kind": "section",
+        "name": "Path A · …",
+        "child": {
+          "kind": "stack",
+          "axis": "vertical",
+          "gap": "tight",
+          "align": "start",
+          "items": [
+            { "kind": "item", "type": "richtext", "size": "small",
+              "content": "**Path A** · …" },
+            { "kind": "grid", "columns": 6, "gap": "medium", "items": [/* frames */] }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Gotchas (learned the hard way)
+
+- **`box-shadow: 9999px` spotlights get clipped** and vanish from screenshots. Always use the fixed radial overlay from `inject-highlight.js`.
+- **Wrong element:** loose regexes match sibling labels (`/save/i` also matches “Save and close”). Prefer exact text + min width/height + prefer larger hit targets.
+- **CLICK pill vs outline mismatch:** place the pill from the highlighted element’s box after layout; re-highlight after fixing helpers if the first shot drifted.
+- **Dark forms:** bump spotlight opacity toward 0.55 so the fade reads.
+- **DPR:** post-process centres must be CSS × devicePixelRatio.
+- **`place` appends below existing content** unless you bulk-remove first when rebuilding.
+- **Verify images by node count / positions**, not by grepping `![` in stored content (TipTap converts markdown images).
+- **Do not commit secrets** from the product under test; use throwaway trial data in screenshots.
+
+---
+
+## Pairing with fat-marker-flows
+
+| Skill | Fidelity | Source |
+|-------|----------|--------|
+| `fat-marker-flows` | Rough Shape Up sketches | Image model |
+| `howto-filmstrips` | Real product UI | Browser capture + CSS |
+
+Same canvas can hold a fat-marker “proposed” row and a how-to “as shipped” row — keep the visual language of each skill intact so readers never confuse sketch with screenshot.

package/skills/howto-filmstrips/scripts/inject-highlight.js

@@ -0,0 +1,198 @@
+/**
+ * How-to filmstrip highlight helpers for the page under test.
+ *
+ * Evaluate this entire file in the page (CDP Runtime.evaluate / browser console).
+ * Then call:
+ *   __cnHowto.highlight(el, { label: 'CLICK' | 'TYPE' | 'DONE' })
+ *   __cnHowto.clear()
+ *   __cnHowto.findExact('Contact', { minW: 100, minH: 36, preferX: 1100 })
+ *
+ * Uses a fixed full-viewport radial overlay so the spotlight is not clipped by
+ * parent overflow (unlike element box-shadow: 0 0 0 9999px).
+ *
+ * Accent colours are intentional for overlays on third-party product UIs
+ * (not CreatorNotes app chrome): crimson #C43036, done green #2F9E6A.
+ */
+(() => {
+  const CRIMSON = "#C43036";
+  const GREEN = "#2F9E6A";
+  const LABEL_FG = "#ffffff";
+  const LABEL_SHADOW = "0 2px 8px rgba(0,0,0,0.35)";
+  const STYLE_ID = "cn-howto-filmstrip-style";
+  const OVERLAY_ID = "cn-howto-filmstrip-overlay";
+  const LABEL_ID = "cn-howto-filmstrip-label";
+  const HL_CLASS = "cn-howto-filmstrip-hl";
+
+  function ensureStyle() {
+    if (document.getElementById(STYLE_ID)) return;
+    const s = document.createElement("style");
+    s.id = STYLE_ID;
+    s.textContent = `
+      .${HL_CLASS} {
+        outline: 3px solid var(--cn-howto-accent, ${CRIMSON}) !important;
+        outline-offset: 3px !important;
+        border-radius: 6px !important;
+        box-shadow: 0 0 0 6px color-mix(in srgb, var(--cn-howto-accent, ${CRIMSON}) 18%, transparent) !important;
+        background-color: color-mix(in srgb, var(--cn-howto-accent, ${CRIMSON}) 12%, transparent) !important;
+        position: relative !important;
+        z-index: 2147483646 !important;
+      }
+      #${OVERLAY_ID} {
+        position: fixed;
+        inset: 0;
+        pointer-events: none;
+        z-index: 2147483645;
+      }
+      #${LABEL_ID} {
+        position: fixed;
+        z-index: 2147483647;
+        color: ${LABEL_FG};
+        font: 700 11px/1 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        letter-spacing: 0.08em;
+        padding: 5px 8px;
+        border-radius: 4px;
+        pointer-events: none;
+        box-shadow: ${LABEL_SHADOW};
+      }
+    `;
+    document.documentElement.appendChild(s);
+  }
+
+  function clear() {
+    document.querySelectorAll("." + HL_CLASS).forEach((el) => {
+      el.classList.remove(HL_CLASS);
+      el.style.removeProperty("--cn-howto-accent");
+    });
+    document.getElementById(OVERLAY_ID)?.remove();
+    document.getElementById(LABEL_ID)?.remove();
+  }
+
+  function placeSpotlight(cx, cy, { maxOpacity = 0.4, holeR = 100, fadeMult = 5.5 } = {}) {
+    let overlay = document.getElementById(OVERLAY_ID);
+    if (!overlay) {
+      overlay = document.createElement("div");
+      overlay.id = OVERLAY_ID;
+      document.documentElement.appendChild(overlay);
+    }
+    const rampEnd = holeR * fadeMult;
+    overlay.style.background = `radial-gradient(
+      circle at ${cx}px ${cy}px,
+      rgba(0,0,0,0) 0px,
+      rgba(0,0,0,0) ${holeR}px,
+      rgba(0,0,0,${maxOpacity * 0.35}) ${holeR + (rampEnd - holeR) * 0.35}px,
+      rgba(0,0,0,${maxOpacity}) ${rampEnd}px,
+      rgba(0,0,0,${maxOpacity}) 100%
+    )`;
+  }
+
+  function placeLabel(r, text, accent) {
+    document.getElementById(LABEL_ID)?.remove();
+    const label = document.createElement("div");
+    label.id = LABEL_ID;
+    label.textContent = text;
+    label.style.background = accent;
+    document.documentElement.appendChild(label);
+    const lw = label.offsetWidth;
+    const lh = label.offsetHeight;
+    let left = r.left + (r.width - lw) / 2;
+    let top = r.top - lh - 8;
+    if (top < 8) top = r.bottom + 8;
+    left = Math.max(8, Math.min(left, window.innerWidth - lw - 8));
+    label.style.left = left + "px";
+    label.style.top = top + "px";
+  }
+
+  function highlight(el, opts = {}) {
+    if (!el) return { ok: false, reason: "no element" };
+    ensureStyle();
+    clear();
+
+    const label = (opts.label || "CLICK").toUpperCase();
+    const isDone = label === "DONE";
+    const accent = isDone ? GREEN : CRIMSON;
+    const maxOpacity = opts.maxOpacity ?? (isDone ? 0.3 : 0.4);
+
+    el.style.setProperty("--cn-howto-accent", accent);
+    el.classList.add(HL_CLASS);
+    el.scrollIntoView({ block: "nearest", inline: "nearest" });
+
+    const r = el.getBoundingClientRect();
+    const cx = r.left + r.width / 2;
+    const cy = r.top + r.height / 2;
+    const holeR = opts.holeR ?? Math.max(80, Math.max(r.width, r.height) * 0.9);
+
+    placeSpotlight(cx, cy, { maxOpacity, holeR, fadeMult: opts.fadeMult ?? 5.5 });
+    placeLabel(r, label, accent);
+
+    return {
+      ok: true,
+      tag: el.tagName,
+      text: (el.getAttribute("aria-label") || el.textContent || "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 80),
+      box: { x: r.x, y: r.y, w: r.width, h: r.height },
+      center: { x: cx, y: cy },
+      label,
+    };
+  }
+
+  function findExact(exact, opts = {}) {
+    const minW = opts.minW ?? 20;
+    const minH = opts.minH ?? 20;
+    const maxH = opts.maxH ?? 120;
+    const selectors =
+      'button, a, [role="button"], [role="menuitem"], [role="tab"], [role="radio"], label, input, div, span, li';
+
+    const candidates = [...document.querySelectorAll(selectors)]
+      .map((el) => {
+        const r = el.getBoundingClientRect();
+        const text = (el.getAttribute("aria-label") || el.textContent || "")
+          .replace(/\s+/g, " ")
+          .trim();
+        const style = getComputedStyle(el);
+        return {
+          el,
+          text,
+          r,
+          area: r.width * r.height,
+          visible:
+            r.width >= minW &&
+            r.height >= minH &&
+            r.height <= maxH &&
+            style.visibility !== "hidden" &&
+            style.display !== "none",
+        };
+      })
+      .filter((c) => c.text === exact && c.visible);
+
+    if (!candidates.length) return null;
+
+    candidates.sort((a, b) => {
+      let scoreA = a.area;
+      let scoreB = b.area;
+      if (opts.preferLarge !== false) {
+        scoreA = -a.area;
+        scoreB = -b.area;
+      }
+      if (opts.preferX != null) {
+        scoreA += Math.abs(a.r.x - opts.preferX) * 8;
+        scoreB += Math.abs(b.r.x - opts.preferX) * 8;
+      }
+      if (opts.preferY != null) {
+        scoreA += Math.abs(a.r.y - opts.preferY) * 8;
+        scoreB += Math.abs(b.r.y - opts.preferY) * 8;
+      }
+      return scoreA - scoreB;
+    });
+
+    return candidates[0].el;
+  }
+
+  window.__cnHowto = { highlight, clear, findExact, ensureStyle };
+  window.__cnHighlight = (el, opts) => highlight(el, opts);
+  window.__cnClearHighlight = clear;
+  window.__cnFindExact = findExact;
+
+  return { ok: true, api: ["highlight", "clear", "findExact"] };
+})();

package/skills/howto-filmstrips/scripts/soft-spotlight.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Soft radial spotlight post-process for how-to filmstrip frames.
+
+Use when the in-page CSS overlay was weak or missing. Centres are CSS pixels
+from getBoundingClientRect; pass --dpr for retina screenshots (often 2).
+
+Example:
+  python3 soft-spotlight.py --in A3.png --out A3.png --cx 276 --cy 219 --dpr 2 --opacity 0.55
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+
+def soft_spotlight(
+    im: Image.Image,
+    cx: float,
+    cy: float,
+    hole_r: float = 180,
+    max_opacity: float = 0.4,
+    fade_mult: float = 5.5,
+) -> Image.Image:
+    w, h = im.size
+    ys = np.arange(h)[:, None]
+    xs = np.arange(w)[None, :]
+    dist = np.sqrt((xs - cx) ** 2 + (ys - cy) ** 2)
+    ramp_end = hole_r * fade_mult
+    t = np.clip((dist - hole_r) / max(ramp_end - hole_r, 1), 0, 1)
+    t = t * t * (3 - 2 * t)  # smoothstep
+    alpha = (t * max_opacity * 255).astype(np.uint8)
+    overlay = np.zeros((h, w, 4), dtype=np.uint8)
+    overlay[..., 3] = alpha
+    base = im.convert("RGBA")
+    return Image.alpha_composite(base, Image.fromarray(overlay, "RGBA"))
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--in", dest="src", required=True, help="Input PNG")
+    p.add_argument("--out", dest="dst", required=True, help="Output PNG")
+    p.add_argument("--cx", type=float, required=True, help="Centre X in CSS pixels")
+    p.add_argument("--cy", type=float, required=True, help="Centre Y in CSS pixels")
+    p.add_argument("--dpr", type=float, default=1.0, help="Device pixel ratio (default 1)")
+    p.add_argument("--hole", type=float, default=None, help="Clear hole radius in device pixels")
+    p.add_argument("--opacity", type=float, default=0.4, help="Max dim opacity 0–1")
+    p.add_argument("--fade-mult", type=float, default=5.5, help="Fade length as multiple of hole")
+    args = p.parse_args()
+
+    src = Path(args.src)
+    dst = Path(args.dst)
+    im = Image.open(src)
+    cx = args.cx * args.dpr
+    cy = args.cy * args.dpr
+    hole = args.hole if args.hole is not None else max(160.0, 90.0 * args.dpr)
+
+    out = soft_spotlight(
+        im,
+        cx,
+        cy,
+        hole_r=hole,
+        max_opacity=args.opacity,
+        fade_mult=args.fade_mult,
+    )
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    out.convert("RGB").save(dst, quality=92)
+    print(f"wrote {dst} center=({cx:.0f},{cy:.0f}) hole={hole:.0f} opacity={args.opacity}")
+
+
+if __name__ == "__main__":
+    main()