sdocs-dev 1.14.0 → 1.14.1

package/bin/sdocs-dev.js

@@ -47,6 +47,8 @@ function buildRouter() {
   r.register('schema',   { handler: () => { console.log(helpText.SCHEMA);        process.exit(0); } });
   r.register('charts',   { handler: () => { console.log(helpText.CHARTS_HELP);   process.exit(0); } });
   r.register('diagrams', { handler: () => { console.log(helpText.DIAGRAMS_HELP); process.exit(0); } });
+  r.register('videos',   { handler: () => { console.log(helpText.VIDEOS_HELP);   process.exit(0); } });
+  r.register('video',    { handler: () => { console.log(helpText.VIDEOS_HELP);   process.exit(0); } });
   // `sdoc cells` prints the reference; `sdoc cells verify <file>` evaluates a
   // document's tabs headlessly and prints the computed values (the handler
   // calls process.exit with the 0/1/2 result code).

package/lib/help-text.js

@@ -21,6 +21,7 @@ USAGE
   sdoc schema                      Print the full styles schema
   sdoc charts                      Chart types, options, and styling guide
   sdoc diagrams                    Mermaid diagrams reference (\`\`\`mermaid blocks)
+  sdoc videos                      YouTube embed reference (\`\`\`video blocks)
   sdoc cells                       Inline spreadsheet reference (\`\`\`cells blocks)
   sdoc code                        Syntax highlighting + code-viewer reference
   sdoc app.rb / server.js / ...    Open a source file as a highlighted listing
@@ -928,6 +929,55 @@ EXAMPLE
 `;
 
 
+const VIDEOS_HELP = `
+SmallDocs - Videos
+==================
+Embed a YouTube video in markdown using a \`\`\`video fenced code block.
+The body is a YouTube URL (any common shape) or a bare 11-character
+video id, with optional \`title:\` and \`start:\` lines.
+
+BASIC SYNTAX
+  \`\`\`video
+  https://www.youtube.com/watch?v=dQw4w9WgXcQ
+  \`\`\`
+
+  Bare id, short link, embed link and shorts link all work:
+  \`\`\`video
+  dQw4w9WgXcQ
+  \`\`\`
+
+WITH A TITLE AND START TIME
+  \`\`\`video
+  https://youtu.be/dQw4w9WgXcQ
+  title: Our launch walkthrough
+  start: 1:30
+  \`\`\`
+  \`start:\` accepts seconds (90), clock (1:30, 1:02:03) or 1m30s / 1h2m3s.
+  A \`t=\` parameter already on the URL is used when no \`start:\` is given.
+  \`title:\` sets the iframe title (accessibility) and a caption link.
+
+WHAT RENDERS
+  A responsive 16:9 player that scales with the body column. The embed
+  host is youtube-nocookie.com, so no tracking cookie is set until the
+  viewer presses play. \`rel=0\` is applied, which limits the end-screen
+  suggestions to the source channel (YouTube no longer allows fully
+  removing them from an embed).
+
+LIMITS
+  - Per-block source cap: 8 KB.
+  - Per-document video cap: 50 (excess rendered as plain code).
+
+SECURITY
+  No iframe ever travels through the document markup - SmallDocs still
+  strips iframes from ordinary markdown. The renderer reads only the
+  block text, extracts the 11-character video id, validates it against
+  \`[A-Za-z0-9_-]{11}\`, and builds the player from a src it constructs
+  itself. Anything that is not a recognised YouTube URL or a valid id
+  renders as an inline error, never an embed. Treat block source as
+  untrusted - it travels in the URL hash with the rest of the document.
+`;
+
+
 const CELLS_HELP = `
 SmallDocs - Cells (sheets)
 ======================
@@ -1845,7 +1895,8 @@ navigate.
   errors + the full slide source — for pasting back to an agent.
 
   Common errors:
-    - "shape extends outside grid WxH"   y+h > H (or x+w > W)
+    - "shape extends outside grid WxH"   bbox past an edge by >10% of the
+                                         grid (a little bleed is allowed)
     - \`unknown id "@name"\`               @-ref before the shape is declared
     - \`duplicate id "#name"\`             two shapes share an id
     - \`invalid attribute key\`            key must start with a letter
@@ -1969,6 +2020,37 @@ rather than as designed.
     default. Spend visual weight only on the one or two things the
     slide is about. Empty space is half the design.
 
+  Text alignment.
+    Except for slides with very few elements, or custom shapes with
+    very few words, prefer left-aligned text throughout a slide.
+    Left-aligning most elements - particularly any with more than
+    three words - creates a calm, confident slide that is easy to
+    follow.
+
+  An implicit grid.
+    Take inspiration from Josef Muller-Brockmann's work on grid
+    systems. Consistency of alignment between elements gives off the
+    feeling of considered, structured thinking. Unless you are
+    creating something specific from custom shapes, prefer to build
+    an implicit grid on the slide. A presentation feels even more
+    professional when that grid language flows from slide to slide.
+
+  Branding, borders and background.
+    Less is often more. Precise layouts are hard with custom shapes:
+    overlapping positions may not land where you expect, and you
+    cannot easily check how the slide feels. So when you give a slide
+    a mood through coloured background shapes, keep it relatively
+    simple. This should not stop you being bold, but design with a
+    few key shapes (which may overlap), not many overlapping ones.
+
+  Contrast and legibility.
+    Consider the colour of text against the colour of whatever falls
+    directly beneath it. Readers should be able to calmly take text
+    in from a slide, so ensure there is healthy contrast, at least,
+    between text and the colour beneath it. In general, try to
+    overlay text on a single patch of colour (or very closely
+    related colours) to keep it straightforwardly legible.
+
 ── SHAPE KINDS ───────────────────────────────────────
   r x y w h            rectangle  (x,y = top-left; w,h = size)
   i x y w h            image rect (sugar for \`r\` with \`image=\`; see IMAGES)
@@ -2069,6 +2151,12 @@ rather than as designed.
                                    so the layout doesn't reflow when
                                    icons swap in.
 
+  Pair an icon with its label as two separate shapes - the icon in
+  its own small box, the text in a shape beside or below it. Don't
+  put \`|\` text on an icon (it overlaps the glyph) or drop an icon
+  onto a text shape. Keep every icon in a set the same size (w = h)
+  on a shared row.
+
   Arrow geometry: the coordinates are the line's centerline. The head is
   symmetric around the line, extending up to 3 * strokeWidth perpendicular
   on each side. So a horizontal arrow at y=5.78 with strokeWidth=0.06
@@ -2279,6 +2367,18 @@ rather than as designed.
      The three cards then read as a parallel set rather than three
      improvisations.
 
+  5. Icons collide with text when they share a box.
+
+     The \`icon\` shape paints its glyph across its whole bbox, so
+     text in the same box - or a text shape the icon sits on top of
+     - overlaps it. Keep them as two shapes on one row:
+
+       icon 8 20 4 4 name=recycle color=#0165a5
+       r 13 20 26 4 text=body align=left valign=center | Repairable by design
+
+     Icon in its own 4x4 box; the label starts after it at x=13,
+     centred on the same y. Size every icon in a set the same.
+
 ── SHAPE ATTRIBUTES ──────────────────────────────────
   Between geometry and \`|\`:
 
@@ -2847,4 +2947,4 @@ SUPPORTED LANGUAGES
   they appear. An unknown language label renders as plain text.
 `;
 
-module.exports = { HELP, COMMENTS_HELP, SCHEMA, CHARTS_HELP, DIAGRAMS_HELP, CELLS_HELP, CODE_HELP, SLIDES_HELP, SLIDES_CUSTOM_SHAPES_HELP, LIBRARY_HELP };
+module.exports = { HELP, COMMENTS_HELP, SCHEMA, CHARTS_HELP, DIAGRAMS_HELP, VIDEOS_HELP, CELLS_HELP, CODE_HELP, SLIDES_HELP, SLIDES_CUSTOM_SHAPES_HELP, LIBRARY_HELP };

package/lib/io.js

@@ -8,7 +8,7 @@ const { isWrappedFile, wrapForDisplay } = require('./file-wrap');
 
 const SUBCOMMANDS = new Set([
   'new', 'share', 'schema', 'defaults', 'help', 'version',
-  'charts', 'diagrams', 'cells', 'code', 'comments',
+  'charts', 'diagrams', 'videos', 'video', 'cells', 'code', 'comments',
   'setup', 'safe', 'auto-update', 'refresh', 'upgrade',
   'bridge', 'feedback',
   'slides', 'present',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdocs-dev",
-  "version": "1.14.0",
+  "version": "1.14.1",
   "description": "Open, share, and style markdown files from the terminal",
   "main": "bin/sdocs-dev.js",
   "bin": {