fix(readme-sync): reject noncanonical markers, test the production replacement path

Author: apresmoi

.github/scripts/sync-package-readmes.mjs

@@ -59,7 +59,19 @@ const countByName = (text, re) => {
  * stale block reaches npm.
  */
 export function assertWellFormed(text, label, allowed, onError = fail) {
+  // Canonical form, and the loose form used only to catch near-misses. A typo
+  // (`links2`, `Links`, `:begin`, stray whitespace) must NOT read as "this
+  // package opted out" — that would let `--check` pass on stale content.
   const MARKER_RE = /<!-- polycss:shared:([a-z-]+):(start|end) -->/g;
+  const LOOSE_RE = /<!--[^>]*polycss:shared[^>]*-->/g;
+
+  for (const m of text.matchAll(LOOSE_RE)) {
+    if (!new RegExp(`^${MARKER_RE.source}$`).test(m[0]))
+      return onError(
+        `${label}: malformed shared marker ${JSON.stringify(m[0])} — expected exactly "<!-- polycss:shared:<name>:start -->" or ":end", with a lowercase-and-hyphen name`,
+      );
+  }
+
   const names = new Set();
   let open = null;
 
@@ -93,6 +105,22 @@ export function assertWellFormed(text, label, allowed, onError = fail) {
   return names;
 }
 
+/**
+ * Rewrite every shared block present in `text` from `blocks`. This is the
+ * production replacement path — tests must call THIS, not a local copy.
+ */
+export function applyBlocks(text, blocks, label, allowed, onError = fail) {
+  const present = assertWellFormed(text, label, allowed, onError);
+  if (present === null) return null;
+  let next = text;
+  for (const name of present) {
+    // Replacement passed as a CALLBACK: README content is arbitrary text, and
+    // `$&` / `` $` `` / `$'` in a replacement string would be expanded.
+    next = next.replace(blockRe(name), () => blocks.get(name));
+  }
+  return next;
+}
+
 function main() {
 const rootText = readFileSync(source, "utf8");
 const names = [...assertWellFormed(rootText, "root README", null)];
@@ -121,14 +149,7 @@ for (const target of targets) {
     fail(`${target}: cannot be read (${err.code ?? err.message})`);
   }
 
-  const present = assertWellFormed(text, target, new Set(names));
-
-  let next = text;
-  for (const name of present) {
-    // Replacement passed as a callback: README content is arbitrary text and
-    // `$&` / `` $` `` / `$'` in a replacement STRING would be expanded.
-    next = next.replace(blockRe(name), () => blocks.get(name));
-  }
+  const next = applyBlocks(text, blocks, target, new Set(names));
 
   if (next === text) continue;
   if (checkOnly) {

.github/scripts/sync-package-readmes.test.mjs

@@ -8,7 +8,7 @@
  */
 import { strict as assert } from "node:assert";
 import test from "node:test";
-import { assertWellFormed } from "./sync-package-readmes.mjs";
+import { applyBlocks, assertWellFormed } from "./sync-package-readmes.mjs";
 
 const S = (n) => `<!-- polycss:shared:${n}:start -->`;
 const E = (n) => `<!-- polycss:shared:${n}:end -->`;
@@ -66,16 +66,31 @@ test("rejects a block name the root README does not define", () => {
   assert.match(error, /not defined in the root README/);
 });
 
-test("replacement copies content literally, including $ sequences", () => {
-  // Regression: passing the block as a replacement STRING expands `$&`,
-  // "$`" and `$'`, corrupting any README containing them.
-  const blockRe = /<!-- polycss:shared:links:start -->[\s\S]*?<!-- polycss:shared:links:end -->/;
-  const replacement = `${S("links")}\ncost: $5 — see $& and $\` and $'\n${E("links")}`;
+test("applyBlocks copies content literally, including $ sequences", () => {
+  // Regression: a replacement STRING expands `$&`, "$`" and `$'`. This drives
+  // the PRODUCTION path, so reverting it to the string form fails here.
+  const block = `${S("links")}\ncost: $5 — see $& and $\` and $'\n${E("links")}`;
   const target = `head\n${S("links")}\nold\n${E("links")}\ntail`;
 
-  const viaString = target.replace(blockRe, replacement);
-  const viaCallback = target.replace(blockRe, () => replacement);
+  const out = applyBlocks(target, new Map([["links", block]]), "fixture", ALLOWED);
 
-  assert.ok(viaCallback.includes("$& and $` and $'"), "callback must copy verbatim");
-  assert.notEqual(viaString, viaCallback, "string form is the buggy path this guards against");
+  assert.ok(out.includes("$& and $` and $'"), "block must be copied byte-for-byte");
+  assert.equal(out, `head\n${block}\ntail`);
+});
+
+test("applyBlocks leaves a marker-less file untouched", () => {
+  const target = "# Pkg\n\nnothing shared here\n";
+  assert.equal(applyBlocks(target, new Map(), "fixture", ALLOWED), target);
+});
+
+test("rejects marker-like comments that are not canonical", () => {
+  for (const bad of [
+    "<!-- polycss:shared:links2:start -->",
+    "<!-- polycss:shared:Links:start -->",
+    "<!-- polycss:shared:links:begin -->",
+    "<!--  polycss:shared:links:start  -->",
+  ]) {
+    const { error } = check(`head\n${bad}\nx\n${E("links")}\n`);
+    assert.match(error ?? "", /malformed shared marker/, `should reject ${bad}`);
+  }
 });

packages/core/src/types.ts

@@ -136,11 +136,11 @@ export interface PolyAmbientLight {
  * Material — paint configuration shareable across many polygons.
  *
  * In CSS terms, a material bundles the `background-image` source plus paint
- * config. When a polygon references a material AND its UVs form an
- * axis-aligned rectangle, PolyCSS renders the polygon as an <i> with
- * `background-image: url(material.texture)` directly — no per-polygon canvas
- * rasterization, browser-cached texture, mounting / unmounting one polygon
- * does not affect any other.
+ * config. Material-backed polygons render through the texture atlas by
+ * default. A direct image leaf — source URL and rect, no per-polygon canvas
+ * rasterization — requires valid `imageSource` metadata AND a resolved
+ * presentation of `backend: "image"` with source lighting; the default
+ * `"auto"` backend resolves to the atlas.
  *
  * Three.js parallel: combines THREE.Texture + a basic Material in one. CSS
  * has no shader/sampler concerns, so the texture/material split from

website/public/skill.md

@@ -73,7 +73,7 @@ interface Polygon {
   texture?: string;                      // image URL
   uvs?: [number, number][];              // one per vertex
   material?: PolyMaterial;               // shared material; material.texture wins over `texture`
-  textureImageSource?: PolyTextureImageSource;    // source-exact image leaf (advanced)
+  textureImageSource?: PolyTextureImageSource;    // source image metadata; needs texturePresentation.backend="image" (advanced)
   texturePresentation?: PolyTexturePresentation;  // per-polygon texture overrides (advanced)
   data?: Record<string, string | number | boolean>;  // → data-* attributes
 }
@@ -179,6 +179,8 @@ createPolyOrbitControls(scene, { drag: true, wheel: true });
 
 scene.add(createPolyBox({ size: 100, color: "#ffd166" }), { position: [0, 0, 50] });
 scene.add(await loadMesh("/model.glb"), { castShadow: true });
+// Vanilla has no ground fallback — a caster needs an explicit receiver.
+scene.add(createPolyPlane({ size: 400, color: "#7d848e" }), { receiveShadow: true });
 ```
 
 React (Vue mirrors this with kebab-case props):