nnw-theme 0.0.0 → 0.1.0

package/assets/guide/skill.md

@@ -0,0 +1,44 @@
+# Create NetNewsWire themes
+
+This guide is for people and agents building a theme with `nnw-theme`. Run the tool
+as `npx nnw-theme@1 <command>`; never install it globally or add it to the theme
+repository. Read another topic with `npx nnw-theme@1 guide <topic>`: `theme-format`,
+`fixtures`, `design-checklist`, or `publishing`.
+
+The upstream `dave-atx/netnewswire-theme-template` repository is a GitHub template.
+Work in the person's own repository made via **Use this template**, not in the
+upstream template or a fork. If they already have their own copy open, use it.
+Otherwise, help them create one from the template if you can, or ask them to create
+and open it; confirm before creating a GitHub repository. Then work on its single
+root-level `*.nnwtheme` bundle. If `.nnw-theme-uninitialized` exists, run the guided
+`npx nnw-theme@1 init` before design work; let the person approve the permanent
+identifier even when other identity details are already known.
+
+Collect or infer a compact design brief: mood, typography, color direction, and any
+specific reading needs. Prefer changing the CSS variables and rules in
+`stylesheet.css`. Edit `template.html` only when the requested structure or behavior
+needs it. For format constraints and macro behavior, read the `theme-format` topic.
+To preview content the built-in articles lack, such as a real feed's markup or
+footnotes, add a fixture as the `fixtures` topic describes.
+
+Iterate with this loop:
+
+1. Make a focused theme edit.
+2. Run `npx nnw-theme@1 render` for fast generated pages or
+   `npx nnw-theme@1 screenshot` when a checked image is needed.
+3. Inspect relevant light/dark and device previews under `build/preview/`.
+4. Explain what changed in visual terms and incorporate the person’s reaction.
+
+Use the `design-checklist` topic during final visual review. Always finish
+implementation with `npx nnw-theme@1 check`; do not substitute a Chromium result for
+the required WebKit gate. Give the person a concrete preview or screenshot path they
+can open. If `check` reports that WebKit is missing, run `npx nnw-theme@1 setup`.
+
+Treat the root bundle filename and `ThemeIdentifier` as permanent after the first
+release. Increase the integer `Version` with `npx nnw-theme@1 bump` for each release.
+Read the `publishing` topic for publishing work. Local packaging is not publication.
+Obtain clear user confirmation immediately before triggering a GitHub release or
+another external mutation.
+
+If the tooling misbehaves, do not work around it in the theme repository: report it at
+https://github.com/dave-atx/nnw-theme/issues with the version line `check` prints.

package/assets/guide/theme-format.md

@@ -0,0 +1,52 @@
+# NetNewsWire theme format
+
+Read this when changing theme structure, metadata, scripts, or resources.
+
+The one root-level `<Name>.nnwtheme` directory is the release bundle. It contains
+exactly `Info.plist`, `template.html`, `stylesheet.css`, and optional license or notice
+files. NetNewsWire does not serve arbitrary bundle-local assets: do not add fonts,
+images, media, or references to them. Small demonstrated assets may use data URLs.
+
+`Info.plist` requires non-empty `ThemeIdentifier`, `Name`, `CreatorHomePage`, and
+`CreatorName`, plus an integer `Version`. `Name` and the bundle stem match exactly,
+including spaces and capitalization. `CreatorHomePage` is an absolute HTTP(S) URL.
+The identifier and bundle name stay stable after the first release.
+
+NetNewsWire performs two single-pass substitutions. First, article values replace
+macros in `template.html`; then that body and combined core/theme CSS enter a platform
+page skeleton. Unknown macros remain literal, and substituted values are not scanned
+again. Common template macros are visible in the starter markup and synthetic
+fixtures.
+
+Article text scales through a different mechanism on each platform, and a theme must
+honor both. On macOS the app substitutes `text_size_class` in `template.html` with one
+of `smallText`, `mediumText`, `largeText`, `xLargeText`, or `xxLargeText`, and the
+theme's CSS supplies the sizes; an unset preference means `largeText`, not `mediumText`.
+On iOS and iPadOS the app leaves `text_size_class` unsubstituted and replaces the
+`font-size` macro in the stylesheet with the reader's Dynamic Type body size instead.
+NetNewsWire emits the capital-L `xLargeText` and `xxLargeText` while its bundled themes
+select the lowercase spellings, so define both.
+
+Neither rule needs a platform query. A macOS render leaves the `font-size` macro
+literal, exactly as the app does, so that declaration is invalid there and is dropped;
+the size classes are inert on iOS, where the app never sets one. Do not reach for
+`@supports (-webkit-touch-callout: none)` even though NetNewsWire's own stylesheet
+uses it: no desktop WebKit implements that property, so every preview resolves the iOS
+branch as false and platform-conditional CSS is checked the wrong way round. Do not
+write macro names in double brackets inside comments either, because substitution
+rewrites those too. NetNewsWire's stylesheet also sets `font: -apple-system-body` at
+`:root`; a theme with its own typography should not, because that shorthand resets
+`font-family` and `line-height`.
+
+The renderer pins NetNewsWire `mac-7.1.3` commit
+`f2daca0f24f29c08d9cb16e1bdc56293fd6fe286`. It uses upstream `core.css`, macOS and
+iOS page skeletons, and `main.js`, `main_mac.js`, `main_ios.js`, and `newsfoot.js`.
+These files ship inside the `nnw-theme` package, verified by SHA-256, so previews work
+offline. iPhone and iPad share the iOS skeleton. WebKit native
+color-scheme emulation controls light/dark captures; CSS is not rewritten.
+
+Inline scripts in `template.html` are supported. External scripts and stylesheets are
+rejected. Remote theme-owned fonts, images, audio, or video require an explicit local
+warning override and are still blocked during checks. The article must remain useful
+when Article JavaScript is off; those smoke renders remove theme inline scripts while
+retaining NetNewsWire’s injected scripts.

package/assets/netnewswire/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2002-2025 Brent Simmons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/netnewswire/Mac/main_mac.js

@@ -0,0 +1,43 @@
+function scrollDetection() {
+	window.onscroll = function(event) {
+		window.webkit.messageHandlers.windowDidScroll.postMessage(window.scrollY);
+	}
+}
+
+function linkHover() {
+	window.onmouseover = function(event) {
+		var closestAnchor = event.target.closest('a')
+		if (closestAnchor) {
+			window.webkit.messageHandlers.mouseDidEnter.postMessage(closestAnchor.href);
+		}
+	}
+	window.onmouseout = function(event) {
+		var closestAnchor = event.target.closest('a')
+		if (closestAnchor) {
+			window.webkit.messageHandlers.mouseDidExit.postMessage(closestAnchor.href);
+		}
+	}
+}
+
+// The selection as an HTML fragment — links, bold, and so on included.
+function selectedHTML() {
+	var selection = window.getSelection();
+	var container = document.createElement("div");
+	for (var i = 0; i < selection.rangeCount; i++) {
+		container.appendChild(selection.getRangeAt(i).cloneContents());
+	}
+	// Relative URLs would break outside this page.
+	container.querySelectorAll("a[href]").forEach(function(anchor) {
+		anchor.setAttribute("href", anchor.href);
+	});
+	// A single-paragraph selection doesn't need its <p> wrapper.
+	if (container.childNodes.length === 1 && container.firstChild.nodeName === "P") {
+		return container.firstChild.innerHTML;
+	}
+	return container.innerHTML;
+}
+
+function postRenderProcessing() {
+	scrollDetection();
+	linkHover();
+}

package/assets/netnewswire/Mac/page.html

@@ -0,0 +1,12 @@
+<html dir="auto">
+	<head>
+		<title>[[title]]</title>
+		<style>
+			[[style]]
+		</style>
+		<base href="[[baseURL]]">
+	</head>
+	<body>
+		[[body]]
+	</body>
+</html>

package/assets/netnewswire/Shared/core.css

@@ -0,0 +1,186 @@
+/* This makes the leading edge of the article stable.
+   <https://discourse.netnewswire.com/t/account-for-layout-shift-from-macos-scrollbar-in-themes/328>
+*/
+
+html {
+	scrollbar-gutter: stable;
+}
+
+/* Keep absolutely positioned feed content from escaping the body and overlapping the title.
+   (.article-body is the Biblioteca theme's name for .articleBody.) */
+
+.articleBody,
+.article-body {
+	position: relative;
+}
+
+/* This is the activity indicator (currently iOS only) that is used while image zooming */
+
+.activityIndicatorWrap {
+    position: relative;
+}
+
+.activityIndicator {
+    z-index: 1;
+    width: 64px;
+    height: 64px;
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%);
+}
+
+/* see removeWpSmiley; this rule is kept in case a wp-smiley is encountered without alt text */
+
+.wp-smiley {
+    height: 1em !important;
+    max-height: 1em !important;
+}
+
+/* Material for MkDocs and Twemoji render emoji and icons in a .twemoji span or img.
+   The inline SVGs have no width or height — without the site's stylesheet
+   they'd render at full column width. */
+
+.twemoji {
+	display: inline-flex;
+	height: 1.125em;
+	vertical-align: text-top;
+}
+
+.twemoji svg {
+	width: 1.125em;
+	max-height: 100%;
+	fill: currentColor;
+}
+
+img.twemoji, img.emoji {
+	height: 1em !important;
+	max-height: 1em !important;
+	width: auto;
+}
+
+/* Hide the external link at the bottom of Daring Fireball posts */
+
+.x-netnewswire-hide {
+	display: none;
+}
+ 
+/*Block ads and junk*/
+
+iframe[src*="feedads"],
+iframe[src*="doubleclick"],
+iframe[src*="plusone.google"],
+iframe[src*="slashdot-it.pl"] {
+	display: none !important;
+}
+
+a[href*=".ads."],
+a[href*="feedads"],
+a[href*="doubleclick"],
+a[href*="//ads."],
+a[href*="api.tweetmeme"],
+a[href*="delicious.com/post?"],
+a[href*="digg.com/submit?"],
+a[href*="google.com/bookmarks/mark?"],
+a[href*="posterous.com/share?"],
+a[href*="tumblr.com/share?"],
+a[href*="linkedin.com/shareArticle?"],
+a[href*="facebook.com/share.php?"],
+a[href*="http://twitter.com/home?"],
+a[href*="addtoany.com/share_save"] {
+	display: none !important;
+}
+
+img[src*=".ads."],
+img[src*="//ads."],
+img[src*="doubleclick"],
+img[src*="feedads"],
+img[src*="feedburner"],
+img[src*="feedblitz"],
+img[src*="share-buttons"],
+img[src*="/img/social/"] {
+	display: none !important;
+}
+
+.social_items {
+	display: none !important;
+}
+
+/* Mailchimp newsletters end with a follow-our-socials icon wall */
+
+.mcnFollowBlock {
+	display: none !important;
+}
+
+/* Newsfoot specific styles. Structural styles come first, theme styles second */
+
+.newsfoot-footnote-container {
+	position: relative;
+	display: inline-block;
+	z-index: 9999;
+}
+
+.newsfoot-footnote-popover {
+	position: absolute;
+	display: block;
+	padding: 0em 1em;
+	margin: 1em auto;
+	top: 0.75em;
+	max-width: 44em;
+	border-radius: 0.3em;
+	box-sizing: border-box;
+}
+
+.newsfoot-footnote-popover {
+	left: calc(-1 * (50vw - 1em));
+	right: calc(-1 * (50vw - 1em));
+}
+
+.newsfoot-footnote-popover-arrow {
+	content: '';
+	display: block;
+	width: 1em;
+	position: absolute;
+	top: -0.5em;
+	left: calc(50% - 0.5em);
+	height: 1em !important;
+	transform: rotate(45deg);
+	z-index:0;
+}
+
+.newsfoot-footnote-popover-inner {
+	border-radius: calc(0.3em - 1px);
+	padding: 1em;
+	position: relative;
+	z-index: 1;
+}
+
+.newsfoot-footnote-popover-inner :first-child {
+	margin-top: 0;
+}
+.newsfoot-footnote-popover-inner :last-child {
+	margin-bottom: 0;
+}
+
+.newsfoot-footnote-popover .reversefootnote,
+.newsfoot-footnote-popover .footnoteBackLink,
+.newsfoot-footnote-popover .footnote-return {
+	display: none;
+}
+
+sup[id^='fn'] {
+	vertical-align: baseline;
+}
+
+a.footnote {
+	display: inline-block;
+	text-decoration: none;
+	padding: 0.05em 0.75em;
+	border-radius: 1em;
+	min-width: 1em;
+	text-align: center;
+	font-size: 0.8em;
+	line-height: 1em;
+	position:relative;
+	top: -0.1em;
+}

package/assets/netnewswire/Shared/main.js

@@ -0,0 +1,221 @@
+// Here we are making iframes responsive.  Particularly useful for inline Youtube videos.
+function wrapFrames() {
+	document.querySelectorAll("iframe").forEach(element => {
+		if (parseInt(element.height) > 0) {
+			preserveAspectRatioOfFixedSizeFrame(element);
+			return;
+		}
+		var wrapper = document.createElement("div");
+		wrapper.classList.add("iframeWrap");
+		element.parentNode.insertBefore(wrapper, element);
+		wrapper.appendChild(element);
+	});
+}
+
+// The stylesheet clamps iframes to the article width with max-width: 100%,
+// which leaves an attribute-sized iframe with its full height — distorted,
+// and a huge blank box when the embed fails to load. Let the height follow
+// the width instead.
+function preserveAspectRatioOfFixedSizeFrame(element) {
+	const numeric = /^[1-9]\d*$/;
+	const width = element.getAttribute("width");
+	const height = element.getAttribute("height");
+	if (!numeric.test(width) || !numeric.test(height) || element.style.height) {
+		return;
+	}
+	element.style.aspectRatio = width + " / " + height;
+	element.style.height = "auto";
+}
+
+// Strip out color and font styling
+
+function stripStylesFromElement(element, propertiesToStrip) {
+	for (name of propertiesToStrip) {
+		element.style.removeProperty(name);
+	}
+}
+
+// Strip inline styles that could harm readability.
+function stripStyles() {
+	document.getElementsByTagName("body")[0].querySelectorAll("style, link[rel=stylesheet]").forEach(element => element.remove());
+	// Removing "background" and "font" will also remove properties that would be reflected in them, e.g., "background-color" and "font-family"
+	document.getElementsByTagName("body")[0].querySelectorAll("[style]").forEach(element => stripStylesFromElement(element, ["color", "background", "font", "max-width", "max-height", "position"]));
+}
+
+// Constrain the height of iframes whose heights are defined relative to the document body to be at most
+// 50% of the viewport width.
+function constrainBodyRelativeIframes() {
+	let iframes = document.getElementsByTagName("iframe");
+
+	for (iframe of iframes) {
+		// The article body container is positioned, so it — not document.body —
+		// is the offsetParent for iframes with no positioned ancestor in the content.
+		const offsetParent = iframe.offsetParent;
+		if (offsetParent === document.body || (offsetParent && (offsetParent.classList.contains("articleBody") || offsetParent.classList.contains("article-body")))) {
+			let heightAttribute = iframe.style.height;
+
+			if (/%|vw|vh$/i.test(heightAttribute)) {
+				iframe.classList.add("nnw-constrained");
+			}
+		}
+	}
+}
+
+// Convert all Feedbin proxy images to be used as src, otherwise change image locations to be absolute if not already
+function convertImgSrc() {
+	document.querySelectorAll("img").forEach(element => {
+		if (element.hasAttribute("data-canonical-src")) {
+			element.src = element.getAttribute("data-canonical-src")
+		} else if (!/^[a-z]+\:\/\//i.test(element.src)) {
+			element.src = new URL(element.src, document.baseURI).href;
+		}
+	});
+}
+
+// Wrap tables in an overflow-x: auto; div
+function wrapTables() {
+	var tables = document.querySelectorAll("div.articleBody table");
+
+	for (table of tables) {
+		var wrapper = document.createElement("div");
+		wrapper.className = "nnw-overflow";
+		table.parentNode.insertBefore(wrapper, table);
+		wrapper.appendChild(table);
+
+		// A negative side margin — usually from the site's own page layout —
+		// would put part of the table where the wrapper can't scroll to it.
+		if (parseFloat(getComputedStyle(table).marginLeft) < 0) {
+			table.style.marginLeft = "0";
+		}
+		if (parseFloat(getComputedStyle(table).marginRight) < 0) {
+			table.style.marginRight = "0";
+		}
+	}
+}
+
+// Add the playsinline attribute to any HTML5 videos that don"t have it.
+// Without this attribute videos may autoplay and take over the whole screen
+// on an iphone when viewing an article.
+function inlineVideos() {
+	document.querySelectorAll("video").forEach(element => {
+		element.setAttribute("playsinline", true);
+		if (!element.classList.contains("nnwAnimatedGIF")) {
+			element.setAttribute("controls", true);
+			element.removeAttribute("autoplay");
+		}
+	});
+}
+
+// Remove some children (currently just spans) from pre elements to work around a strange clipping issue
+var ElementUnwrapper = {
+	unwrapSelector: "span",
+	unwrapElement: function (element) {
+		var parent = element.parentNode;
+		var children = Array.from(element.childNodes);
+
+		for (child of children) {
+			parent.insertBefore(child, element);
+		}
+
+		parent.removeChild(element);
+	},
+	// `elements` can be a selector string, an element, or a list of elements
+	unwrapAppropriateChildren: function (elements) {
+		if (typeof elements[Symbol.iterator] !== 'function')
+			elements = [elements];
+		else if (typeof elements === "string")
+			elements = document.querySelectorAll(elements);
+
+		for (element of elements) {
+			for (unwrap of element.querySelectorAll(this.unwrapSelector)) {
+				this.unwrapElement(unwrap);
+			}
+
+			element.normalize()
+		}
+	}
+};
+
+function flattenPreElements() {
+	ElementUnwrapper.unwrapAppropriateChildren("div.articleBody td > pre");
+}
+
+function reloadArticleImage(imageSrc) {
+	var image = document.getElementById("nnwImageIcon");
+	image.src = imageSrc + "?" + new Date().getTime();
+}
+
+function stopMediaPlayback() {
+	document.querySelectorAll("iframe").forEach(element => {
+		var iframeSrc = element.src;
+		element.src = iframeSrc;
+	});
+
+	// We pause all videos that have controls.  Video without controls shouldn't
+	// have sound and are actually converted gifs.  Basically if the user can't
+	// start the video again, don't stop it.
+	document.querySelectorAll("video, audio").forEach(element => {
+		if (element.hasAttribute("controls")) {
+			element.pause();
+		}
+	});
+}
+
+function error() {
+	document.body.innerHTML = "error";
+}
+
+// Takes into account absoluting of URLs.
+function isLocalFootnote(target) {
+	return target.hash.startsWith("#fn") && target.href.indexOf(document.baseURI) === 0;
+}
+
+function styleLocalFootnotes() {
+	for (elem of document.querySelectorAll("sup > a[href*='#fn'], sup > div > a[href*='#fn']")) {
+		if (isLocalFootnote(elem)) {
+			elem.classList.add("footnote");
+		}
+	}
+}
+
+// convert <img alt="📰" src="[...]" class="wp-smiley"> to a text node containing 📰
+// Tailwind size classes like w-[22px] and h-[22px] encode an SVG icon's intended size.
+// The site stylesheet that implements them is stripped, so apply the sizes directly —
+// otherwise an SVG with no width and height renders at full column width.
+function sizeTailwindSVGs() {
+	document.querySelectorAll("div.articleBody svg").forEach(svg => {
+		const classAttribute = svg.getAttribute("class") || "";
+		const width = classAttribute.match(/(?:^|\s)w-\[([\d.]+(?:px|em|rem))\]/);
+		if (width) {
+			svg.style.width = width[1];
+		}
+		const height = classAttribute.match(/(?:^|\s)h-\[([\d.]+(?:px|em|rem))\]/);
+		if (height) {
+			svg.style.height = height[1];
+		}
+	});
+}
+
+function removeWpSmiley() {
+	for (const img of document.querySelectorAll("img.wp-smiley[alt]")) {
+		 img.parentNode.replaceChild(document.createTextNode(img.alt), img);
+	}
+}
+
+function processPage() {
+	wrapFrames();
+	wrapTables();
+	inlineVideos();
+	stripStyles();
+	sizeTailwindSVGs();
+	constrainBodyRelativeIframes();
+	convertImgSrc();
+	flattenPreElements();
+	styleLocalFootnotes();
+	removeWpSmiley()
+	postRenderProcessing();
+}
+
+document.addEventListener("DOMContentLoaded", function(event) {
+	processPage();
+})