@kaydash9999/banker-plugins 0.15.2 → 0.16.1

package/skills/3d-intro-build/references/serve.mjs

@@ -1,123 +1,131 @@
 #!/usr/bin/env node
 /*
- * First-party static preview server for the 3d-intro-build skill.
+ * Local preview server for an assembled intro (index.html + scrub-engine.js + assets/), so the
+ * scroll-scrubbed page is checked in a real browser. The project convention is a self-contained
+ * local page on an unused port, never a claude.ai artifact. Shared by 3d-intro-build and
+ * motion-graphic-make (scripts/sync-adapter.js keeps the copies identical).
  *
- * Serves an assembled intro directory (index.html + scrub-engine.js + assets/) so the
- * scroll-scrubbed page can be previewed in a real browser — the project convention is a
- * self-contained local HTML on an unused port, never a claude.ai artifact.
- *
- * Why a server at all: the page loads each .mp4 with fetch()->Blob (always seekable), and
- * mp4 delivery is smoother with HTTP Range (206) support, which file:// cannot provide.
- *
- * Runtime: Node >=18 builtins ONLY (node:http / node:fs / node:path). No external deps,
- * no shell — cross-platform (path.join, path.resolve, path.sep everywhere).
+ * Why a server at all: the engine loads each clip with fetch() into a Blob, which file:// cannot
+ * serve, and video plays smoother with byte ranges (206).
  *
  * Usage:
- *   node serve.mjs [dir] [--port N]
- *     dir      directory to serve (default: current working directory)
- *     --port   preferred port; falls back through a candidate list if busy/omitted
- *   On listen it writes <dir>/port.txt and prints  PREVIEW http://localhost:<port>/
+ *   node serve.mjs [dir] [--port N] [--csp strict|"<policy>"] [--state file]
+ *   node serve.mjs --stop [dir] [--state file]
+ *     dir      folder to serve (default: the current one)
+ *     --port   preferred port; when busy or absent the system picks a free one
+ *     --csp    sends Content-Security-Policy on every response: `strict` (no inline script or
+ *              style; blob: media) or the production policy as written. Check a page for a site
+ *              with a CSP under that same policy: a plain server hides CSP errors.
+ *     --state  state file (default: <dir>.server.json beside the folder, never inside it)
+ *     --stop   ends the server the state file records, only when it answers with that PID
+ *   A start while the recorded server still answers with the same settings only reports its
+ *   address; with other settings (another folder sharing the --state file, --csp, PREVIEW_HOST, a
+ *   --port other than the one it listens on or its own start asked for) it exits 1: --stop first.
+ *   A request whose Host is a DNS name other than localhost is refused (DNS rebinding).
+ *   On listen it writes the state file and prints  PREVIEW http://localhost:<port>/
+ *   PREVIEW_HOST=0.0.0.0 binds every interface (on-device phone checks) and prints a warning.
+ *
+ * Runtime: Node >=18 builtins only. No shell, cross-platform.
  */
 import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  LOOPBACK, answersPid, cspFrom, decodePath, forgetSelf, hostAllowed, hostWarning, isRunning, listen, portMatches, readState,
+  resolveInside, send, sendFile, siblingState, stopServer, urlFor, writeState,
+} from './preview-lib.mjs';
 
-// ---- args ----
-const argv = process.argv.slice(2);
-let dirArg = null;
-let portArg = null;
-for (let i = 0; i < argv.length; i++) {
-  const a = argv[i];
-  if (a === '--port') portArg = Number(argv[++i]);
-  else if (a.startsWith('--port=')) portArg = Number(a.slice('--port='.length));
-  else if (!a.startsWith('--')) dirArg = a;
+function handler(dir, headers, host) {
+  return (req, res) => {
+    if (!hostAllowed(req.headers.host, [host])) return send(res, 403, 'host not allowed', headers);
+    if (req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, '405', headers);
+    const urlPath = decodePath(req.url);
+    if (urlPath === null) return send(res, 400, '400', headers);
+    if (answersPid(urlPath, res)) return;
+    const fp = resolveInside(dir, urlPath === '/' ? '/index.html' : urlPath);
+    if (!fp) return send(res, 403, '403', headers);
+    sendFile(req, res, fp, headers);
+  };
 }
 
-const DIR = path.resolve(dirArg || process.cwd());
-if (!fs.existsSync(DIR) || !fs.statSync(DIR).isDirectory()) {
-  console.error(`serve: not a directory: ${DIR}`);
-  process.exit(1);
+/**
+ * Serves `dir` until close(). Resolves to { server, port, host, url, stateFile, close }.
+ * @param {{ port?: number, host?: string, csp?: string, stateFile?: string }} opts
+ */
+export async function startServe(dir, { port, host = process.env.PREVIEW_HOST || LOOPBACK, csp, stateFile } = {}) {
+  const root = path.resolve(dir);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`serve: not a directory: ${root}`);
+  const policy = cspFrom(csp);
+  const server = http.createServer(handler(root, policy ? { 'Content-Security-Policy': policy } : {}, host));
+  const bound = await listen(server, { host, port });
+  const url = urlFor(host, bound);
+  const file = stateFile ? path.resolve(stateFile) : siblingState(root);
+  writeState(file, {
+    pid: process.pid, port: bound, requestedPort: port || null, host, url, dir: root, csp: policy, startedAt: new Date().toISOString(),
+  });
+  const close = () => new Promise((resolve) => { forgetSelf(file); server.close(() => resolve()); });
+  return { server, port: bound, host, url, stateFile: file, close };
 }
 
-const MIME = {
-  '.html': 'text/html;charset=utf-8',
-  '.css': 'text/css;charset=utf-8',
-  '.js': 'text/javascript;charset=utf-8',
-  '.mjs': 'text/javascript;charset=utf-8',
-  '.json': 'application/json;charset=utf-8',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.webp': 'image/webp',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.mp4': 'video/mp4',
-  '.webm': 'video/webm',
-  '.mov': 'video/quicktime',
-};
-
-const server = http.createServer((req, res) => {
-  let p = decodeURIComponent((req.url || '/').split('?')[0]);
-  if (p === '/') p = '/index.html';
+function parseArgs(argv) {
+  const o = { dir: null, port: null, csp: null, state: null, stop: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const [key, inline] = a.includes('=') ? [a.slice(0, a.indexOf('=')), a.slice(a.indexOf('=') + 1)] : [a, null];
+    const value = () => (inline !== null ? inline : argv[++i]);
+    if (key === '--port') o.port = Number(value());
+    else if (key === '--csp') o.csp = value();
+    else if (key === '--state') o.state = value();
+    else if (key === '--stop') o.stop = true;
+    else if (!a.startsWith('--')) o.dir = a;
+  }
+  return o;
+}
 
-  // Resolve inside DIR and reject any path that escapes it (traversal guard).
-  const fp = path.normalize(path.join(DIR, p));
-  if (fp !== DIR && !fp.startsWith(DIR + path.sep)) { res.writeHead(403); res.end('403'); return; }
-  if (!fs.existsSync(fp) || fs.statSync(fp).isDirectory()) { res.writeHead(404); res.end('404'); return; }
+// Nothing left running is a success; a port held by another program, or one that stays open, is not.
+async function stopMain(o, dir) {
+  const r = await stopServer(o.state ? path.resolve(o.state) : siblingState(dir));
+  console.log(`STOP ${r.reason}`);
+  process.exit(['stopped', 'not-running', 'no-state'].includes(r.reason) ? 0 : 1);
+}
 
-  const size = fs.statSync(fp).size;
-  const type = MIME[path.extname(fp).toLowerCase()] || 'application/octet-stream';
-  const isVideo = type.startsWith('video/');
-  const range = req.headers.range;
+// Whether the recorded server answers this start: this folder, the same CSP and host, and the port
+// asked for. A state file shared through --state can record another folder's server.
+const sameSettings = (st, o, dir) => path.resolve(String(st.dir || '')) === dir && (st.csp || null) === cspFrom(o.csp)
+  && (st.host || LOOPBACK) === (process.env.PREVIEW_HOST || LOOPBACK) && portMatches(st, o.port);
 
-  // Range requests (video scrubbing benefits from 206 partial content).
-  if (range && isVideo) {
-    const m = /bytes=(\d+)-(\d*)/.exec(range);
-    if (m) {
-      const start = parseInt(m[1], 10);
-      const end = m[2] ? parseInt(m[2], 10) : size - 1;
-      if (start >= size || end >= size || start > end) {
-        res.writeHead(416, { 'Content-Range': `bytes */${size}` }); res.end(); return;
-      }
-      res.writeHead(206, {
-        'Content-Type': type,
-        'Content-Range': `bytes ${start}-${end}/${size}`,
-        'Accept-Ranges': 'bytes',
-        'Content-Length': end - start + 1,
-        'Cache-Control': 'no-store',
-      });
-      fs.createReadStream(fp, { start, end }).pipe(res);
-      return;
-    }
+// A server already running for this state file: the same settings only report its address; other
+// settings (folder, CSP, host, port) never pass for it, so a check meant to run under a CSP cannot
+// run without one, and a page meant for one folder or port is not checked on another.
+async function reportRunning(recorded, o, dir) {
+  if (!(await isRunning(recorded))) return false;
+  const st = readState(recorded);
+  if (sameSettings(st, o, dir)) {
+    console.log(`PREVIEW ${st.url} (already running, pid ${st.pid})`);
+    return true;
   }
+  console.error(`serve: the state file records a server running with different settings (folder: ${st.dir}, `
+    + `csp: ${st.csp ? 'on' : 'off'}, host: ${st.host}, port: ${st.port}); stop it with --stop and start again`);
+  process.exit(1);
+}
 
-  res.writeHead(200, {
-    'Content-Type': type,
-    'Content-Length': size,
-    'Accept-Ranges': 'bytes',
-    'Cache-Control': 'no-store',
-  });
-  fs.createReadStream(fp).pipe(res);
-});
-
-// ---- pick a free port (preferred first, then a candidate list) ----
-const candidates = [8931, 8932, 8933, 8080, 8090, 8100, 8123, 8321];
-const ports = portArg ? [portArg, ...candidates.filter((p) => p !== portArg)] : candidates;
-// Default to loopback (matches the printed localhost URL). Set PREVIEW_HOST=0.0.0.0 for LAN / on-device mobile preview.
-const HOST = process.env.PREVIEW_HOST || '127.0.0.1';
-
-(function tryPort(i) {
-  if (i >= ports.length) { console.error('serve: no free port available'); process.exit(1); }
-  server.once('error', (e) => {
-    if (e.code === 'EADDRINUSE') tryPort(i + 1);
-    else { console.error(e); process.exit(1); }
-  });
-  server.listen(ports[i], HOST, () => {
-    try { fs.writeFileSync(path.join(DIR, 'port.txt'), String(ports[i])); } catch { /* best effort */ }
-    console.log(`PREVIEW http://${HOST === '127.0.0.1' ? 'localhost' : HOST}:${ports[i]}/`);
-    console.log(`serving ${DIR}`);
-  });
-})(0);
+async function main() {
+  const o = parseArgs(process.argv.slice(2));
+  const dir = path.resolve(o.dir || process.cwd());
+  if (o.stop) return stopMain(o, dir);
+  if (await reportRunning(o.state ? path.resolve(o.state) : siblingState(dir), o, dir)) return;
+  const s = await startServe(dir, { port: o.port || undefined, csp: o.csp || undefined, stateFile: o.state || undefined });
+  const warn = hostWarning(s.host);
+  if (warn) console.warn(warn);
+  console.log(`PREVIEW ${s.url}`);
+  console.log(`serving ${dir}${o.csp ? '  (with Content-Security-Policy)' : ''}  state: ${s.stateFile}`);
+  const quit = () => { forgetSelf(s.stateFile); s.server.close(); process.exit(0); };
+  process.on('SIGINT', quit);
+  process.on('SIGTERM', quit);
+}
 
-process.on('SIGINT', () => { server.close(); process.exit(0); });
-process.on('SIGTERM', () => { server.close(); process.exit(0); });
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  main().catch((e) => { console.error(String(e?.message || e)); process.exit(1); });
+}

package/skills/3d-intro-build/references/step-nav.css

@@ -0,0 +1,59 @@
+/* Hints, skip link and main button of step-nav.js (scene-by-scene navigation, opt-in).
+   step-nav.js sets on <html>: isn-on, isn-mouse or isn-touch, isn-last (at the last scene),
+   isn-ready (the last clip has played to its end and the page has a body to go to), isn-body.
+   Colours are variables: set them from the brand (a light pill on a dark site, and so on). */
+
+:root {
+  --isn-pill-bg: rgba(11, 18, 32, .72);
+  --isn-pill-ink: #F1F5F9;
+  --isn-skip-bg: rgba(11, 18, 32, .6);
+  --isn-main-bg: #F1F5F9;
+  --isn-main-ink: #0B1220;
+  --isn-focus: #38BDF8;
+}
+
+/* Mouse users: a dark pill with a wheel and a down key, bottom centre. It replaces the engine hint. */
+.isn-hint {
+  position: fixed; left: 50%; bottom: 26px; z-index: 31; translate: -50% 0;
+  display: none; align-items: center; gap: 10px; padding: 9px 16px; border-radius: 999px;
+  background: var(--isn-pill-bg); color: var(--isn-pill-ink); pointer-events: none;
+  font: 600 .78rem/1.2 system-ui, -apple-system, "Segoe UI", sans-serif; letter-spacing: .02em;
+}
+html.isn-mouse .isn-hint { display: flex; }
+html.isn-mouse .sw-hint { display: none; }
+.isn-hint__wheel { width: 14px; height: 22px; border: 2px solid currentColor; border-radius: 8px; position: relative; opacity: .9; }
+.isn-hint__wheel::after { content: ""; position: absolute; left: 50%; top: 4px; width: 2px; height: 5px; border-radius: 1px; background: currentColor; translate: -50% 0; }
+.isn-hint__key { width: 20px; height: 20px; border: 2px solid currentColor; border-radius: 5px; position: relative; opacity: .9; }
+.isn-hint__key::after { content: ""; position: absolute; left: 50%; top: 4px; width: 6px; height: 6px; border-right: 2px solid currentColor; border-bottom: 2px solid currentColor; translate: -50% 0; rotate: 45deg; }
+
+/* Touch users: the engine's own hint stays up until the last scene (the engine fades it with an
+   inline opacity, which !important overrides). Bottom left at 600px and below. */
+html.isn-touch .sw-hint { opacity: 1 !important; }
+@media (max-width: 600px) {
+  html.isn-touch .sw-hint { left: 18px; transform: none; align-items: flex-start; }
+}
+
+/* A narrow and short window has no room for the mouse hint. */
+@media (max-width: 600px) and (max-height: 700px) {
+  .isn-hint { display: none !important; }
+}
+
+/* Skip link: in every scene but the last. */
+.isn-skip {
+  position: fixed; right: clamp(14px, 2.4vw, 30px); bottom: 22px; z-index: 32;
+  padding: 8px 14px; border-radius: 999px; background: var(--isn-skip-bg); color: var(--isn-pill-ink);
+  font: 600 .8rem/1.2 system-ui, -apple-system, "Segoe UI", sans-serif; text-decoration: none;
+}
+.isn-skip:focus-visible, .isn-main:focus-visible { outline: 3px solid var(--isn-focus); outline-offset: 3px; }
+
+/* Main button: only once the last clip has played to its end. */
+.isn-main {
+  position: fixed; left: 50%; bottom: 26px; z-index: 32; translate: -50% 0; display: none;
+  padding: 12px 22px; border: 0; border-radius: 999px; background: var(--isn-main-bg); color: var(--isn-main-ink); cursor: pointer;
+  font: 700 .95rem/1.2 system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+html.isn-ready .isn-main { display: inline-flex; }
+
+/* The last scene keeps the main button alone; the body shows none of these. */
+html.isn-last .isn-hint, html.isn-last .sw-hint, html.isn-last .isn-skip,
+html.isn-body .isn-hint, html.isn-body .sw-hint, html.isn-body .isn-skip, html.isn-body .isn-main { display: none !important; }