@transclude/core 0.8.0 → 0.9.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Atelier Dakroub
+Copyright (c) 2026 Joe Dakroub
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -15,6 +15,9 @@
   <a href="https://github.com/transclude-dev/transclude/blob/main/LICENSE"
     ><img alt="MIT" src="https://img.shields.io/npm/l/%40transclude%2Fcore?color=0b7285"
   /></a>
+  <a href="https://bsky.app/profile/transclude.dev" rel="me"
+    ><img alt="Bluesky" src="https://img.shields.io/badge/Bluesky-transclude.dev-0b7285"
+  /></a>
 </p>
 
 HTML is the product. A page is an `.html` file, the directory tree is the route
@@ -23,7 +26,10 @@ table, and any fragment of a page is a URL of its own.
 The same app runs on Node, Bun, Deno and workerd, the runtime behind
 Cloudflare Workers, and ships no client JavaScript by default.
 
-**[transclude.dev](https://transclude.dev)** has the documentation.
+**[transclude.dev](https://transclude.dev)** has the documentation, and
+[every example is running](https://transclude.dev/docs/examples).
+[todomvc.transclude.dev](https://todomvc.transclude.dev) ships zero bytes of
+JavaScript, which is easier to believe with the page open.
 
 ```sh
 npm create @transclude my-app
@@ -127,15 +133,23 @@ npm run check:src     # type-check the framework itself
 ```
 
 `examples/` holds apps built against this package the same way any other project
-would be. `todomvc` is TodoMVC with forms and no client JavaScript, `blog` is a
-prerendered site with a sitemap and a feed, `search` swaps a fragment into a
-page that works without it, `htmx` does the same with htmx and the
-`HX-Target` header, `includes` shows transclusion from three sources,
-`auth` guards a section with a layout and a signed cookie, `live` pushes
-updates over server-sent events, `elements` puts a light and a shadow element
-side by side, and `showcase` uses every feature and is where the
-browser checks live, because those need an app to run against. `www/` is the site at transclude.dev: a landing page, the
-documentation under `/docs`, and itself built with the framework.
+would be. Every one of them is deployed, from the same source you would clone.
+
+| Example | What it proves | Running |
+| --- | --- | --- |
+| `todomvc` | Seven actions, one POST handler, zero bytes of JavaScript | [todomvc.transclude.dev](https://todomvc.transclude.dev) |
+| `search` | A fragment that is a substring of the document it came from | [search.transclude.dev](https://search.transclude.dev) |
+| `blog` | Markdown to files, with a sitemap and a feed | [blog.transclude.dev](https://blog.transclude.dev) |
+| `htmx` | htmx and this framework, each doing its own half | [htmx.transclude.dev](https://htmx.transclude.dev) |
+| `includes` | One piece of markup rendered in more than one place | [includes.transclude.dev](https://includes.transclude.dev) |
+| `auth` | A section behind a layout and a signed cookie | [auth.transclude.dev](https://auth.transclude.dev) |
+| `live` | Server-sent events into a fragment | [live.transclude.dev](https://live.transclude.dev) |
+| `elements` | A light element and a shadow one, side by side | [elements.transclude.dev](https://elements.transclude.dev) |
+| `showcase` | Every feature at once, and where the browser checks live | [showcase.transclude.dev](https://showcase.transclude.dev) |
+
+The browser checks are in `showcase` because they need an app to run against.
+`www/` is the site at transclude.dev: a landing page, the documentation under
+`/docs`, the writing under `/blog`, and itself built with the framework.
 
 ### Trying the CLI against this checkout
 

package/bin/build.js

@@ -123,6 +123,29 @@ fs.writeFileSync(entry, `// @ts-nocheck\n${fs.readFileSync(entry, 'utf8')}`);
 
 const { pages } = await import(pathToFileURL(entry).href);
 
+// ---- drafts ---------------------------------------------------------------
+
+/**
+ * `export const draft = true` keeps a page out of the build.
+ *
+ * The dev server reads the directory, so a draft is a page there and you can
+ * open it, reload it and read it on a phone. This is the only place that knows
+ * the difference, and it takes the route out of the one list every step below
+ * reads: nothing is prerendered for it, no pattern reaches `routes.json`, and
+ * the sitemap never hears of it. In production the URL is a 404.
+ *
+ * Assigned back onto the manifest rather than carried alongside it. Three steps
+ * below read `manifest.routes`, and a fourth added later would publish drafts
+ * without anyone noticing. One list is the only version of this that stays true.
+ *
+ * The build says what it skipped, at the end, next to everything else it wrote.
+ * A page that is missing from production and silent about it is an afternoon.
+ */
+const isDraft = (route) => pages[route.id]?.draft === true;
+const drafts = manifest.routes.filter(isDraft);
+
+manifest.routes = manifest.routes.filter((route) => !isDraft(route));
+
 /**
  * A static route has one URL. A dynamic route has as many as its `paths` export
  * names, and none at all if it does not export one, in which case it stays a
@@ -517,6 +540,17 @@ console.log(`\n${summary.join(', ')}`);
 for (const url of prerendered) console.log(`  ${url}`);
 for (const route of dynamic) console.log(`  ${route.pattern}  (server-rendered)`);
 
+// Last, and never silent. A draft is the one thing here that is absent from
+// production on purpose, and the only way to tell a page that was skipped from
+// a page that broke is to be told.
+if (drafts.length) {
+  console.log(
+    `\n${drafts.length} draft${drafts.length === 1 ? '' : 's'} skipped, ` +
+      `and served by \`npm run dev\`:`,
+  );
+  for (const route of drafts) console.log(`  ${route.pattern}`);
+}
+
 if (compressed.files) {
   const kb = (n) => `${(n / 1024).toFixed(1)} KB`;
   const pct = (n) => `${Math.round((1 - n / compressed.raw) * 100)}%`;

package/bin/dev.js

@@ -28,6 +28,10 @@ import { cookiesOf } from '../src/cookies.js';
 import { loadProject, portOf } from '../src/project.js';
 import { includeContext } from '../src/include.js';
 import { nodeLookup } from '../src/lookup.js';
+import { feed, feedPath, feedType } from '../src/feed.js';
+import { sitemap } from '../src/sitemap.js';
+import { documentStore, PROXY_PATH, proxyHandler } from '../src/proxy.js';
+import { afterFor } from '../src/after.js';
 
 const { root, config } = await loadProject();
 const routesDir = resolveRoutesDir(path.join(root, config.appDir), config.routesDir);
@@ -139,6 +143,17 @@ const contextFor = (route, c, extra = {}) => ({
   // is right for a form, and wrong for a caller that asked for markup.
   fragment: fragmentOf(c),
   action: null,
+
+  // Nothing is held between requests here, so there is nothing to drop. A
+  // no-op rather than an omission: an action calling this is correct code, and
+  // it should not throw in dev and work in production.
+  revalidateTag: () => {},
+
+  // Node keeps running after a response, so this only has to handle the
+  // rejection. `console.error` rather than `config.onError`, which the dev
+  // server does not use for anything else either.
+  after: afterFor(c, (error) => console.error('[transclude] ctx.after:', error)),
+
   ...withResponse(c, extra),
 });
 
@@ -312,6 +327,49 @@ async function buildApp() {
     });
   }
 
+  // Before the route table, the same way production registers them, so a
+  // catch-all route cannot answer for one of these.
+  //
+  // They were missing here entirely. `createApp` mounts them and the dev server
+  // builds its own app, so `/feed.xml` and `/sitemap.xml` were 404 in dev and
+  // correct in the build. That is the worst shape a difference can take: the
+  // thing you check by hand is the thing that was never wired.
+  if (config.sitemap) {
+    app.get('/sitemap.xml', async (c) => {
+      // Only a parameter route ever reads its module, for `paths`. Loading the
+      // rest would compile the whole site to answer one request.
+      const pages = {};
+      for (const route of routes) {
+        if (route.params.length) pages[route.id] = await vite.ssrLoadModule(pageModuleId(route.id));
+      }
+
+      const xml = await sitemap({ routes }, pages, config.sitemap, c.req.query('p') ?? null);
+      return c.body(xml, 200, { 'Content-Type': 'application/xml; charset=utf-8' });
+    });
+  }
+
+  if (config.feed) {
+    app.get(feedPath(config.feed), async (c) => {
+      const xml = await feed(config.feed);
+      return c.body(xml, 200, { 'Content-Type': feedType(config.feed) });
+    });
+  }
+
+  // The browser calls this one, so a page using an external include worked in
+  // the build and 404ed here. Default deny is the config's doing either way: no
+  // `proxy` key, no route.
+  //
+  // `/precache.json` is deliberately not here. It names hashed asset filenames,
+  // which only the build knows, and a service worker holding anything in dev is
+  // a bug rather than a feature. It is build output and stays that way.
+  if (config.proxy) {
+    const handler = proxyHandler(config.proxy, {
+      lookup: config.proxy.lookup ?? nodeLookup(),
+      store: documentStore(config.proxy.cache),
+    });
+    app.get(PROXY_PATH, (c) => handler(c.req.raw));
+  }
+
   // Already ordered most-specific first, so registration order is deterministic
   // rather than something to reason about per-router.
   for (const route of routes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "An HTML-first server framework. A page is an .html file, the directory tree is the route table, and any fragment of a page is a URL of its own. Runs on Node, Bun, Deno and workerd, and ships no client JavaScript by default.",
   "keywords": [
     "html",

package/skills/transclude/references/server.md

@@ -141,6 +141,11 @@ this to a page that has to run for each request:
 export const prerender = false;
 ```
 
+**`export const draft = true` keeps a page out of the build.** `npm run dev`
+serves it, because the dev server reads the directory. The build writes no file,
+puts no route in the manifest and no line in the sitemap, and prints what it
+skipped. Deployed, the URL is a 404. Publishing is deleting the line.
+
 `prerender` is read off the page, never off its layouts. A layout that reads a
 cookie makes every page under it request-dependent, and nothing says so.
 
@@ -182,12 +187,18 @@ import that.
 
 ```js
 // app/lib/bindings.js — no `node:` imports, this ends up in the worker bundle
-/** @type {Env|null} */
-let current = null;
-
-export const hold = (env) => (current = env);
+// A symbol in the global registry, not a module variable. The build inlines a
+// copy of this file into the server bundle and wrangler bundles `worker.js`
+// with a second one, so a module variable is written in one copy and read in
+// the other.
+const SLOT = Symbol.for('app.bindings');
+
+export const hold = (env) => {
+  globalThis[SLOT] = env;
+};
 
 export const bindings = () => {
+  const current = globalThis[SLOT];
   if (!current) throw new Error('No bindings: this app is running off workerd.');
   return current;
 };

package/src/compiler/index.js

@@ -91,6 +91,25 @@ export function readFlags(source, label = 'element') {
   return resolveFlags(fromProps, fromClient, label);
 }
 
+/**
+ * Script types the browser executes. Everything else is a data block.
+ *
+ * The list is the HTML spec's, minus the legacy spellings nobody writes. An
+ * absent `type` is a classic script, `module` is a module, and both are code.
+ * `importmap` is not executed either, but the browser reads it, which is the
+ * same reason to emit it rather than compile it.
+ *
+ * @param {{ attrs?: Array<{ name: string, value: string }> }} node
+ * @returns {boolean} whether this script holds data rather than code
+ */
+function isDataBlock(node) {
+  const type = node.attrs?.find((attr) => attr.name === 'type')?.value;
+  if (type === undefined) return false;
+
+  const JS = ['', 'module', 'text/javascript', 'application/javascript'];
+  return !JS.includes(type.trim().toLowerCase());
+}
+
 /**
  * Top-level <script>/<style> blocks are pulled out; everything else is template.
  *
@@ -162,6 +181,12 @@ export function splitBlocks(source) {
       // with nothing said. A nested `<script src>` was always markup; only a
       // top-level one went missing.
       else if (attrs.has('src')) out.nodes.push(node);
+      // A type the browser does not run as JavaScript makes this a data block,
+      // which is markup for the same reason a `src` is: there is no code here to
+      // compile. Import maps, JSON-LD, speculation rules written by hand and
+      // whatever a library reads out of the document were all swallowed, because
+      // anything without a marker was read as a client module.
+      else if (isDataBlock(node)) out.nodes.push(node);
       else out.client.push(block);
       continue;
     }