@cube-drone/marquee-markup 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,12 @@
1
+ <img src="https://raw.githubusercontent.com/cube-drone/marqueemarkup/main/marquee-logo.png" alt="Marquee Markup" width="96" align="right">
2
+
1
3
  # @cube-drone/marquee-markup
2
4
 
3
- Marquee, batteries included. One install, everything working:
5
+ The [Marquee](https://github.com/cube-drone/marqueemarkup) Markup Language.
6
+
7
+ Marquee source in, complete styled HTML out, with the stylesheet, fonts, and emoji table along for the ride.
8
+
9
+ This is the package you want unless you know why you want a smaller one.
4
10
 
5
11
  ```
6
12
  npm install @cube-drone/marquee-markup
@@ -13,62 +19,153 @@ import { readFileSync, writeFileSync } from "node:fs";
13
19
  writeFileSync("hello.html", marquee(readFileSync("hello.mq", "utf8")));
14
20
  ```
15
21
 
16
- `marquee(source)` parses, renders, styles, inlines exactly the fonts the page wears,
17
- and hands back a complete self-contained HTML page.
22
+ To learn the *language*, read [WRITING.md](https://github.com/cube-drone/marqueemarkup/blob/main/WRITING.md)
23
+ or see it live at [marquee.cube-drone.com](https://marquee.cube-drone.com). This document is
24
+ the contract for the *tools*.
18
25
 
19
- Or use the CLI:
26
+ ## The CLI
20
27
 
21
28
  ```
22
- npx marquee hello.mq > hello.html one self-contained page
23
- npx marquee mysite/ dist/ a whole website
24
- npx marquee --nofetch hello.mq no network: web turbolinks stay plain links
29
+ npx marquee <file.mq> render one page to stdout
30
+ npx marquee <file.mq> -o out.html ...or to a file
31
+ npx marquee <site-dir> <out-dir> build a whole site
25
32
  ```
26
33
 
27
- Batteries included, no surprises: by default the CLI runs the turbolink fetch-ahead pass, so
28
- a bare web link unfurls into a real OpenGraph summary card. `--nofetch` skips all network for
29
- the spartan, safer output.
30
-
31
- The site form renders every `.mq` in the folder (files named `_*.mq` are shared partials for
32
- `:::include doc=_nav:::` — nav and footer once, every page), resolves page-to-page links,
33
- copies referenced media, and ships only the font faces the site actually uses.
34
-
35
- If `marquee` is a little too all-inclusive for your tastes:
36
-
37
- - `marqueeFetch(source, opts)` → `marquee()` plus the network (async): runs the composed
38
- plugins' `resolve()` phase ahead of the render — OpenGraph summaries for bare web links,
39
- plus whatever gathering your own plugins declare. **This executes plugin fetch code**, even
40
- malicious code if you've somehow loaded a plugin you shouldn't trust — the chain is yours.
41
- Rendering itself stays sync and fetchless; failed fetches degrade to plain links.
42
- - `buildSiteFetch(siteDir, outDir, opts)` → the same fetch-ahead pass over a whole site
43
- - `marqueeBody(source, opts)` → just what goes inside `<body>`
44
- - `marqueeHead(source, opts)` → just what goes inside `<head>` (title + one `<style>` block)
45
- - `marqueeFragment(source, opts)` → `{ body, css, title, fontTokens }` — all the pieces
46
- - `buildSite(siteDir, outDir, opts)` → the CLI's site build as a function
47
- - options: `{ title, fonts: "inline" | "external" | "none", fontBase, emoji, emojiDefaults,
48
- colorScheme, envelope, plugins, profile }` — inline the fonts, reference them externally
49
- (copy the `fontTokens` files via `fontFilePath()`), or skip them; add turbolink expanders;
50
- override any embedder policy
51
- - pages follow the reader's OS light/dark theme by default; `colorScheme: "dark"` (or
52
- `npx marquee --darkmode`) forces one
53
- - color rescue is **on by default** for whole pages: author colors keep their hue but get
54
- lightened on dark canvases and darkened on light ones until they're legible, via CSS
55
- relative color syntax (the author picked their colors against one canvas; the OS theme
56
- flip is the surprise, and the clamp carries their intent across it). Schemes and
57
- `background=`-painted blocks own their own contrast and are left alone; browsers without
58
- relative-color support just see the raw colors. Opt out with `readable: false` (or
59
- `--noreadable`); bare fragments default off instead, since a host theming by class rather
60
- than OS preference would get the clamp backwards — pass `readable: true` when your canvas
61
- follows `prefers-color-scheme`
62
- - `envelope: true` (or `npx marquee --envelope`) wraps plain documents in a 650px centered
63
- envelope so unstructured text reads comfortably. Opt-in, because it could interfere with a
64
- host stack's own layout — and a document that *is* a `:::page` (top-level content is page
65
- directives) is left alone either way; merely mentioning a page demo mid-prose doesn't count
66
- - emoji just work: `:sparkles:` and 1,900 friends resolve out of the box (the standard gemoji
67
- table, via `@cube-drone/marquee-emoji`). Layer your own entries on with
68
- `emoji: { slug: "🎩" }` or `emoji: { slug: { image, alt? } }` for custom image emoji —
69
- yours win on collision — or pass `emojiDefaults: false` to start from a blank table
70
- - **everything underneath is re-exported** — `parse`, `render`, `Profile`, the plugin
71
- machinery, the stylesheet, the font helpers — so when you outgrow the convenience you
72
- don't switch packages, you just reach deeper
73
-
74
- To learn the language itself, read [WRITING.md](https://github.com/cube-drone/marqueemarkup/blob/main/WRITING.md).
34
+ | flag | effect |
35
+ |---|---|
36
+ | `--nofetch` | skip the network fetch-ahead pass. Default is ON: bare web links become real OpenGraph preview cards, fetched once at build time. With `--nofetch`, unrecognized links stay plain links and the build touches no network |
37
+ | `--envelope` | wrap plain documents in a 650px centered column for readability. Documents whose top-level content is `:::page` directives are left alone (the author took layout control) |
38
+ | `--darkmode` | force `color-scheme: dark`. Default: pages follow the reader's OS theme |
39
+ | `--noreadable` | disable the color-readability rescue (see `readable` below). Default is ON for pages |
40
+
41
+ Every flag is a library option first; the CLI is sugar over the functions below.
42
+
43
+ ## Functions
44
+
45
+ ### What Happens if the Marquee is unparseable?
46
+
47
+ I have good news for you: if you give it _text_ you are very likely to be in the clear:
48
+ this language is designed to _always_ be parseable. **any input renders: nothing throws**.
49
+
50
+ The only exception in the whole API is an unknown dialect version declaration
51
+ (`#!marquee 99`), which throws `UnsupportedVersionError` — so that old versions of Marquee
52
+ don't try to parse documents it doesn't understand yet.
53
+
54
+ ### `marquee(source, options?) => string`
55
+
56
+ * parse
57
+ * render
58
+ * inline the stylesheet
59
+ * inline exactly the font faces the page actually uses (as base64, by default)
60
+ * wrap in a complete `<!doctype html>` page shell.
61
+
62
+ The returned string is self-contained (thanks to all of the inlining): you should be able to deliver it as a complete .html file.
63
+
64
+ Turbolinks (bare URLs alone in a paragraph) render through the _fetchless_ plugin chain:
65
+ which is to say, we don't go chasing after OpenGraph data to expand them.
66
+
67
+ YouTube/Spotify links become embeds (these won't work if you don't serve the file from _somewhere_),
68
+
69
+ image/audio/video links become the media, everything else degrades to a plain link.
70
+
71
+ ### `marqueeFetch(source, options?) => Promise<string>`
72
+
73
+ In the above function we didn't fetch OpenGraph data (how could we? we were running in sync mode).
74
+ `marqueeFetch` does the same thing but it _does, in fact, go fetch that OpenGraph data!_.
75
+
76
+ `marquee()` plus the network: before rendering, runs every composed turbolink plugin's async
77
+ `resolve()` phase over the document's link targets — concurrently across targets, with the
78
+ OpenGraph plugin joining the chain automatically (10-second timeout per fetch). Gathered
79
+ summaries render as preview cards; failed or timed-out fetches degrade to plain links.
80
+
81
+ **Trust contract:** this function *executes plugin fetch code*. The default chain is safe;
82
+ if you pass your own turbolink `plugins`, you are vouching for them. Rendering itself remains synchronous and
83
+ fetchless — all network happens in the resolve phase, before render, never during.
84
+
85
+ ### `marqueeFragment(source, options?) => { body, css, title, fontTokens }`
86
+
87
+ The pieces, for embedding in your own page:
88
+
89
+ - `body: string` — one `<div class="mq-doc">…</div>` fragment
90
+ - `css: string` — everything the body needs styled: the Marquee stylesheet, the composed
91
+ plugins' skins, and font faces per the `fonts` option
92
+ - `title: string` — the `title` option, else the document's `:::meta title`, else `"Marquee"`
93
+ - `fontTokens: string[]` — which font faces the body actually wears (feed to
94
+ `fontFilePath()` if you're hosting font files yourself)
95
+
96
+ ### `marqueeBody(source, options?) => string` / `marqueeHead(source, options?) => string`
97
+
98
+ The fragment, pre-split for template stitching: `marqueeBody` returns just the body
99
+ fragment; `marqueeHead` returns `<title>…</title>\n<style>…</style>`, paste-ready for a
100
+ `<head>`.
101
+
102
+ ### `buildSite(siteDir, outDir, options?) => SiteReport`
103
+
104
+ A folder of `.mq` files in, a static website out. The contract, precisely:
105
+
106
+ - **Every `<id>.mq` becomes `<id>.html`**, except files named `_*.mq`, which are *partials*:
107
+ includable via `:::include doc=_nav:::` but not rendered as pages. Includes resolve beside
108
+ the including file; included documents may not themselves include (cycles are therefore
109
+ unrepresentable); a missing include renders a visible placeholder, never an error.
110
+ - **Relative doc-id links resolve to built pages**: `[Menu](menu)` becomes `href="menu.html"`.
111
+ - **Relative media is copied** into `<out>/media/` (deduplicated, name-collision-safe) and
112
+ embeds re-point to the copies. Remote (`https:`) media is left as-is: readers fetch it.
113
+ - **Fonts ship as real files**: only the faces the site's pages actually use are copied to
114
+ `<out>/fonts/`, with a generated `css/fonts.css` pointing at them — cacheable across pages,
115
+ never base64.
116
+ - **Stylesheets are files**: `css/marquee.css` and `css/turbolink.css` (the composed plugin
117
+ chain's skins), linked from every page shell.
118
+ - Page titles come from each document's `:::meta title`, falling back to the file's id.
119
+ - Returns `{ pages: string[], mediaFiles: number, fontFaces: string[], outDir: string }`.
120
+
121
+ ### `buildSiteFetch(siteDir, outDir, options?) => Promise<SiteReport>`
122
+
123
+ `buildSite()` with the fetch-ahead pass: gathers turbolink targets across *all* the site's
124
+ `.mq` files (partials included), resolves them once, builds with the results. Same trust
125
+ contract as `marqueeFetch`.
126
+
127
+ ## Options
128
+
129
+ `MarqueeOptions` — every field optional:
130
+
131
+ | option | type | default | contract |
132
+ |---|---|---|---|
133
+ | `title` | `string` | document's `:::meta title`, else `"Marquee"` | the page `<title>` |
134
+ | `fonts` | `"inline" \| "external" \| "none"` | `"inline"` | `inline`: used faces embedded as base64 (self-contained page). `external`: `@font-face` rules point at `<fontBase><token>.woff2` — you copy the files (`fontTokens` names them, `fontFilePath()` locates them). `none`: no faces; font names degrade to their fallback stacks |
135
+ | `fontBase` | `string` | `"fonts/"` | URL prefix for `fonts: "external"` |
136
+ | `emoji` | `Record<string, string \| { image, alt? }>` | `{}` | your emoji table, layered over the defaults; yours win on collision. String values are replacement text; `{ image, alt? }` renders a character-sized inline `<img>` (the custom-emoji mechanism — the image URL is embedder-trusted, like every hook) |
137
+ | `emojiDefaults` | `boolean` | `true` | the standard gemoji table (`:sparkles:` and ~1,900 friends) loads implicitly. `false`: unlisted shortcodes stay literal `:slug:` |
138
+ | `colorScheme` | `"light" \| "dark"` | follow the reader's OS | forces the page shell's `color-scheme`. Applies to whole pages only; fragments follow their host |
139
+ | `envelope` | `boolean` | `false` | wrap the document in a 650px centered readability column. Defers to documents that *are* a `:::page` |
140
+ | `readable` | `boolean` | `true` for pages, `false` for fragments | the color-readability rescue: author colors keep their hue but their lightness is clamped toward the canvas's opposite (via CSS relative color syntax), so dark-red text survives dark mode. Containers that paint their own background are left alone; browsers without support see raw colors. Fragments default off because a host theming by class rather than OS preference would get the clamp backwards |
141
+ | `plugins` | `TurbolinkPlugin[]` | the fetchless default set | the turbolink chain, in priority order. In fetch mode, `opengraphPlugin` is appended unless already present |
142
+ | `profile` | `Partial<Profile>` | — | override any embedder policy hook (allowed URL schemes, media resolution, emoji, directives). Wins over everything above |
143
+
144
+ `SiteOptions` (for `buildSite`/`buildSiteFetch`) accepts `emoji`, `emojiDefaults`,
145
+ `colorScheme`, `envelope`, `readable`, `plugins`, and `profile` with identical meanings,
146
+ applied per-page.
147
+
148
+ ## Safety, stated plainly
149
+
150
+ - Author bytes never reach output except through escaping; targets only through the profile's
151
+ scheme allowlist; the AST is the contract — nothing `innerHTML`-shaped exists.
152
+ - Unknown vocabulary degrades visibly (placeholders, literal text) and **never eats content**.
153
+ - The rendered page contains **zero JavaScript**. Effects are CSS, honor
154
+ `prefers-reduced-motion`, and reveal effects cannot hide text where animations don't run.
155
+ - The only code execution surface is plugin `resolve()` in the fetch functions, and only for
156
+ plugins you composed.
157
+
158
+ ## Reaching deeper
159
+
160
+ Everything underneath is re-exported, so outgrowing the convenience never means switching
161
+ packages: `parse` and the AST types (`Node`, `Attrs`, `Reason`), `render` / `renderMarquee` /
162
+ `bareWebProfile` / `Profile` and the escapes, `marqueeCss`, `standardEmoji`, the font helpers
163
+ (`FONT_MANIFEST`, `fontFilePath`, `inlineFontFaces`, `externalFontFaces`), and the whole
164
+ turbolink toolkit (`TurbolinkPlugin`, `composeTurbolinks`, `resolveTargets`,
165
+ `turbolinkTargets`, `turbolinkStyles`, `renderCard`, `defaultPlugins`, `opengraphPlugin`).
166
+ The leaner-diet packages behind them: `@cube-drone/marquee-parser`, `-html-renderer`,
167
+ `-css`, `-fonts`, `-emoji`, `-turbolink` — same code, à la carte. This package deliberately
168
+ includes the ~1.3MB font grab bag; that's what batteries-included means.
169
+
170
+ Same version number across every package and the Rust crates = passed the same published
171
+ conformance corpus, by definition. License: MPL-2.0.
File without changes
@@ -93,8 +93,8 @@ export declare function marquee(source: string, opts?: MarqueeOptions): string;
93
93
  * degrades to the plain link. */
94
94
  export declare function marqueeFetch(source: string, opts?: MarqueeOptions): Promise<string>;
95
95
  export { buildSite, buildSiteFetch, type SiteReport } from "./build-site.ts";
96
- export { parse, UnsupportedVersionError } from "@cube-drone/marquee-parser";
97
- export type { Attrs, Node, Reason } from "@cube-drone/marquee-parser";
96
+ export { parse, parseWithPositions, UnsupportedVersionError } from "@cube-drone/marquee-parser";
97
+ export type { Attrs, Node, Reason, Span } from "@cube-drone/marquee-parser";
98
98
  export { FONTS, bareWebProfile, escapeAttr, escapeText, render, renderMarquee, usedFontTokens, } from "@cube-drone/marquee-html-renderer";
99
99
  export type { EmojiResolution, MediaResolution, Profile, TurbolinkLevel } from "@cube-drone/marquee-html-renderer";
100
100
  export { marqueeCss } from "@cube-drone/marquee-css";
package/dist/src/index.js CHANGED
@@ -169,7 +169,7 @@ export async function marqueeFetch(source, opts = {}) {
169
169
  }
170
170
  export { buildSite, buildSiteFetch } from "./build-site.js";
171
171
  // The full toolbox, re-exported: growth never requires switching packages.
172
- export { parse, UnsupportedVersionError } from "@cube-drone/marquee-parser";
172
+ export { parse, parseWithPositions, UnsupportedVersionError } from "@cube-drone/marquee-parser";
173
173
  export { FONTS, bareWebProfile, escapeAttr, escapeText, render, renderMarquee, usedFontTokens, } from "@cube-drone/marquee-html-renderer";
174
174
  export { marqueeCss } from "@cube-drone/marquee-css";
175
175
  export { standardEmoji } from "@cube-drone/marquee-emoji";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cube-drone/marquee-markup",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "Marquee, batteries included: parse + render to HTML in one motion, fonts and styles along for the ride, plus the `marquee` CLI",
5
5
  "license": "MPL-2.0",
6
6
  "repository": {
@@ -38,12 +38,12 @@
38
38
  "prepack": "npm run build"
39
39
  },
40
40
  "dependencies": {
41
- "@cube-drone/marquee-css": "^0.2.0",
42
- "@cube-drone/marquee-emoji": "^0.2.0",
43
- "@cube-drone/marquee-fonts": "^0.2.0",
44
- "@cube-drone/marquee-html-renderer": "^0.2.0",
45
- "@cube-drone/marquee-parser": "^0.2.0",
46
- "@cube-drone/marquee-turbolink": "^0.2.0"
41
+ "@cube-drone/marquee-css": "^0.4.0",
42
+ "@cube-drone/marquee-emoji": "^0.4.0",
43
+ "@cube-drone/marquee-fonts": "^0.4.0",
44
+ "@cube-drone/marquee-html-renderer": "^0.4.0",
45
+ "@cube-drone/marquee-parser": "^0.4.0",
46
+ "@cube-drone/marquee-turbolink": "^0.4.0"
47
47
  },
48
48
  "devDependencies": {
49
49
  "@types/node": "^24.0.0",
package/src/index.ts CHANGED
@@ -266,8 +266,8 @@ export async function marqueeFetch(source: string, opts: MarqueeOptions = {}): P
266
266
  export { buildSite, buildSiteFetch, type SiteReport } from "./build-site.ts";
267
267
 
268
268
  // The full toolbox, re-exported: growth never requires switching packages.
269
- export { parse, UnsupportedVersionError } from "@cube-drone/marquee-parser";
270
- export type { Attrs, Node, Reason } from "@cube-drone/marquee-parser";
269
+ export { parse, parseWithPositions, UnsupportedVersionError } from "@cube-drone/marquee-parser";
270
+ export type { Attrs, Node, Reason, Span } from "@cube-drone/marquee-parser";
271
271
  export {
272
272
  FONTS,
273
273
  bareWebProfile,